@hienlh/ppm 0.21.0 → 0.22.1

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

@@ -16,12 +16,22 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { api } from "@/lib/api-client";
+import { useSettingsStore } from "@/stores/settings-store";
 import { resolveRemoteDesktopWsUrl } from "./remote-desktop-ws-url";
 import { useH264CanvasDecoder, type DecoderStatus } from "./use-h264-canvas-decoder";
+import {
+  DEFAULT_PRESET_ID, parsePresetId, type QualityChoice, type QualityPresetId,
+} from "../../../shared/remote-desktop-quality";
+import { CLIPBOARD_READ_DELAY_MS, writeClientClipboard } from "./remote-desktop-clipboard-client";
+import { useOpusAudioPlayer } from "./use-opus-audio-player";
 
 export type RemoteDesktopConnState = "connecting" | "streaming" | "error" | "closed";
 
 const PING_INTERVAL_MS = 5_000;
+/** First byte of every binary message. 0/1 are the video's delta/key flags, unchanged; audio is
+ *  a third kind on the same socket rather than a second connection, which would need its own
+ *  nonce and its own eviction rules. */
+const FRAME_AUDIO = 2;
 
 export interface UseRemoteDesktopConnectionResult {
   connState: RemoteDesktopConnState;
@@ -37,6 +47,69 @@ export interface UseRemoteDesktopConnectionResult {
   getTotalBytes: () => number;
   /** Forwards the decoder's own frame counter (see `use-h264-canvas-decoder.ts`). */
   getFrameCount: () => number;
+  /** Pixel size of the decoded picture, 0×0 until the first frame. What the `original`/`custom`
+   *  scale modes multiply — see `remote-desktop-view-style.ts`. */
+  frameSize: { width: number; height: number };
+  /** The rung the *server* is actually streaming at, and whether it is free to change it
+   *  itself. Both come from the server (`config`, then `quality` on every change) rather than
+   *  from what was last requested: the host echoes the rung it settled on, and `held` says how
+   *  much of that rung's bitrate the link is currently allowing (1 = all of it). */
+  quality: { preset: QualityPresetId; held: number };
+  /** Choose a rung. There is no `auto`: the adaptation always runs beneath whichever is
+   *  chosen, so the choice is a ceiling rather than an off switch. */
+  setQuality: (preset: QualityChoice) => void;
+  /** Commit RustDesk's custom rung: a bitrate percentage and an fps. Also selects `custom`. */
+  setCustomQuality: (percent: number, fps: number) => void;
+  /** Whether the host pointer is drawn into the frames. Device pref, not a server report — the
+   *  session never changes this by itself, so there is nothing to echo back. */
+  showCursor: boolean;
+  /** Toggle the host pointer. Respawns the host's ffmpeg (~400ms of held picture): every
+   *  grabber takes `-draw_mouse`/`-capture_cursor` at startup and none can be retuned live. */
+  setShowCursor: (show: boolean) => void;
+  /** The encoder the host is *actually* running, or null while it is on its own first choice.
+   *  Read back from the server rather than from the pref, because the server drops an encoder
+   *  this host cannot run — so the menu shows what is live, not what was asked for. */
+  codec: string | null;
+  /** Ask the host for another H.264 encoder. Also a respawn. */
+  setCodec: (encoder: string | null) => void;
+  /** Whether the host is streaming its audio. Reported by the server, because it also turns
+   *  this back off by itself when the host has no loopback device or its ffmpeg dies. */
+  audioOn: boolean;
+  /** Ask the host to start/stop streaming audio. Starting also resumes the `AudioContext`, so
+   *  it has to be called from a real user gesture (a click), not from an effect. */
+  setAudioOn: (on: boolean) => void;
+  /** Audio tracks for the recorder to mux in; empty while audio is off. */
+  getAudioTracks: () => MediaStreamTrack[];
+  /** Local input blocked + host monitor blanked. Server-reported, because an engage can fail
+   *  (a screen lock already holds the keyboard) and the switch must show what actually holds. */
+  privacyOn: boolean;
+  /** Why the last engage failed, or null. */
+  privacyError: string | null;
+  setPrivacyOn: (on: boolean) => void;
+  /** The host mode id that is live now, read back from the host after every switch — so the
+   *  picker ticks what the host is really doing rather than what was asked for. Null until the
+   *  host has reported once (a non-X11 host never does). */
+  hostModeId: string | null;
+  /** The mode that was live before this session changed it, or null when it has changed none.
+   *  Drives the "Original" item, exactly as RustDesk's `isOriginalResolutionSet` does. */
+  hostOriginalModeId: string | null;
+  /** Why the last switch failed, or null. */
+  resolutionError: string | null;
+  /** Ask the host to change its own display mode. Respawns the capture: `-video_size` is fixed
+   *  at spawn, so the old grabber would keep reading a rectangle the framebuffer no longer has. */
+  setHostMode: (modeId: string) => void;
+  /** Text the host copied that could NOT be written to this device's clipboard automatically —
+   *  `navigator.clipboard` is secure-context only and PPM is usually plain HTTP on a LAN. Non-null
+   *  means the UI must offer a real click to copy it; null means nothing is pending. */
+  pendingHostClipboard: string | null;
+  /** Discard the pending text (copied it, or dismissed the notice). */
+  clearHostClipboard: () => void;
+  /** Put client text on the host clipboard; `paste` also presses the host's paste shortcut,
+   *  with Shift when the user pressed Ctrl+Shift+V (a terminal's paste). */
+  sendClipboard: (text: string, paste: boolean, shift?: boolean) => void;
+  /** Ask the host for its clipboard, after `CLIPBOARD_READ_DELAY_MS` so a just-forwarded copy
+   *  combo has actually landed on the host clipboard first. */
+  requestHostClipboard: () => void;
 }
 
 export interface UseRemoteDesktopConnectionOptions {
@@ -54,19 +127,158 @@ export function useRemoteDesktopConnection(
   const [connState, setConnState] = useState<RemoteDesktopConnState>("connecting");
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const [generation, setGeneration] = useState(0); // bump to force a manual reconnect
+  const [quality, setQualityState] = useState<{ preset: QualityPresetId; held: number }>(() => {
+    // Reflect the restored choice immediately: the server confirms it a moment later with its
+    // own `quality` message, and until then the picker must not tick the wrong rung.
+    const stored = parsePresetId(useSettingsStore.getState().remoteDesktopQuality);
+    return { preset: stored ?? DEFAULT_PRESET_ID, held: 1 };
+  });
+  /** The user's pinned choice, re-applied after a reconnect (the server always starts a fresh
+   *  session on `auto`). A ref, not state: this must never be a dependency of the effect that
+   *  owns the socket, or changing quality would tear down the connection it is tuning.
+   *
+   *  Seeded from the device-local pref via `getState()` rather than the hook, for that same
+   *  reason — subscribing would make the socket effect re-run on a quality change. `useRef`
+   *  reads its argument on the first render only, which is exactly the "restore on open"
+   *  semantics wanted here. */
+  const pinnedRef = useRef<QualityChoice | null>(
+    parsePresetId(useSettingsStore.getState().remoteDesktopQuality),
+  );
+  const [pendingHostClipboard, setPendingHostClipboard] = useState<string | null>(null);
+  const clipboardReadTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const showCursor = useSettingsStore((s) => s.remoteDesktopShowCursor);
+  const clipboardSync = useSettingsStore((s) => s.remoteDesktopClipboardSync);
+  /** Mirrors of the two prefs above for the socket's own closures. The socket effect runs only
+   *  on `generation`/`displayId`, so `onopen`/`onmessage` capture whatever these were when it
+   *  last ran — reading the pref through a ref is what keeps a toggle mid-session honest
+   *  without making a settings change tear the connection down. */
+  const showCursorRef = useRef(showCursor);
+  const clipboardSyncRef = useRef(clipboardSync);
+  useEffect(() => { showCursorRef.current = showCursor; }, [showCursor]);
+  useEffect(() => { clipboardSyncRef.current = clipboardSync; }, [clipboardSync]);
+  /** Same ref-for-the-socket-closure reasoning; seeded from the pref so the first ffmpeg is
+   *  already the right one. `codec` state is what the server confirmed. */
+  const codecRef = useRef(useSettingsStore.getState().remoteDesktopCodec);
+  const [codec, setCodecState] = useState<string | null>(codecRef.current);
 
   const decoder = useH264CanvasDecoder(canvasRef);
+  const audio = useOpusAudioPlayer();
+  const [audioOn, setAudioOn] = useState(false);
+  const [privacyOn, setPrivacyOn] = useState(false);
+  const [privacyError, setPrivacyError] = useState<string | null>(null);
+  const [hostModeId, setHostModeId] = useState<string | null>(null);
+  const [hostOriginalModeId, setHostOriginalModeId] = useState<string | null>(null);
+  const [resolutionError, setResolutionError] = useState<string | null>(null);
 
   const sendMessage = useCallback((msg: Record<string, unknown>) => {
     const ws = wsRef.current;
     if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
   }, []);
 
+  /** Adopt whatever rung the server reports, from either `config` or `quality`. */
+  const applyQualityMessage = useCallback((msg: Record<string, unknown>) => {
+    const preset = parsePresetId(msg.preset);
+    if (!preset) return;
+    // `held` is absent whenever the link is allowing the whole rung, which is the normal case.
+    const held = typeof msg.held === "number" && msg.held > 0 && msg.held < 1 ? msg.held : 1;
+    setQualityState({ preset, held });
+  }, []);
+
+  /** The wire form of a rung. `custom` carries its two numbers, because the server cannot look
+   *  them up — they live in this device's prefs, and the same session may be reconnected to. */
+  const qualityMessage = useCallback((choice: QualityChoice): Record<string, unknown> => {
+    if (choice !== "custom") return { type: "quality", preset: choice };
+    const st = useSettingsStore.getState();
+    return {
+      type: "quality", preset: "custom",
+      percent: st.remoteDesktopCustomQualityPercent,
+      fps: st.remoteDesktopCustomFps,
+    };
+  }, []);
+
+  const setQuality = useCallback((preset: QualityChoice) => {
+    pinnedRef.current = preset;
+    // Remembered per device so a LAN desktop reopens on its 60fps rung without being asked
+    // again, while a phone keeps whatever that phone chose.
+    useSettingsStore.getState().setRemoteDesktopQuality(preset);
+    sendMessage(qualityMessage(preset));
+  }, [qualityMessage, sendMessage]);
+
+  /** Commit the custom dialog's numbers. Writes them first so `qualityMessage` reads the new
+   *  pair, then re-sends — selecting "Custom" and then dragging a slider are the same request
+   *  as far as the host is concerned. */
+  const setCustomQuality = useCallback((percent: number, fps: number) => {
+    const st = useSettingsStore.getState();
+    st.setRemoteDesktopCustomQuality(percent, fps);
+    st.setRemoteDesktopQuality("custom");
+    pinnedRef.current = "custom";
+    sendMessage(qualityMessage("custom"));
+  }, [qualityMessage, sendMessage]);
+
+  const requestPrivacy = useCallback((on: boolean) => {
+    // Not optimistic, unlike audio: claiming the host is locked out when the grab was refused
+    // is the one wrong answer that matters here, so the switch waits for the server.
+    setPrivacyError(null);
+    sendMessage({ type: "privacy", enabled: on });
+  }, [sendMessage]);
+
+  const requestAudio = useCallback((on: boolean) => {
+    // Optimistic: the server confirms with its own `audio` message (and contradicts this when
+    // the host cannot capture), but the AudioContext must be created inside this click.
+    setAudioOn(on);
+    if (!on) audio.reset();
+    sendMessage({ type: "audio", enabled: on });
+  }, [audio, sendMessage]);
+
+  const setCodec = useCallback((encoder: string | null) => {
+    codecRef.current = encoder;
+    useSettingsStore.getState().setRemoteDesktopCodec(encoder);
+    // null means "your choice": there is no message for that (ffmpeg has to be told *some*
+    // encoder), so the session keeps the current one until the next connect. Reflected locally
+    // so the menu does not claim the switch already happened.
+    setCodecState(encoder);
+    if (encoder) sendMessage({ type: "codec", encoder });
+  }, [sendMessage]);
+
+  const setHostMode = useCallback((modeId: string) => {
+    // Not optimistic, for the same reason as privacy: the X server can refuse a mode, and a
+    // picker that ticked it anyway would be describing a screen nobody has.
+    setResolutionError(null);
+    sendMessage({ type: "resolution", modeId });
+  }, [sendMessage]);
+
+  const setShowCursor = useCallback((show: boolean) => {
+    showCursorRef.current = show;
+    useSettingsStore.getState().setRemoteDesktopShowCursor(show);
+    sendMessage({ type: "cursor", show });
+  }, [sendMessage]);
+
+  const sendClipboard = useCallback((text: string, paste: boolean, shift = false) => {
+    sendMessage({ type: "clipboard", text, paste, shift });
+  }, [sendMessage]);
+
+  /** Coalesced: holding Ctrl+C repeats the keydown, and one read per repeat would spawn a
+   *  clipboard helper per frame on the host. */
+  const requestHostClipboard = useCallback(() => {
+    if (clipboardReadTimer.current) clearTimeout(clipboardReadTimer.current);
+    clipboardReadTimer.current = setTimeout(() => {
+      clipboardReadTimer.current = null;
+      sendMessage({ type: "clipboardRead" });
+    }, CLIPBOARD_READ_DELAY_MS);
+  }, [sendMessage]);
+
+  const clearHostClipboard = useCallback(() => setPendingHostClipboard(null), []);
+
+  useEffect(() => () => { if (clipboardReadTimer.current) clearTimeout(clipboardReadTimer.current); }, []);
+
   useEffect(() => {
     let cancelled = false;
     let pingTimer: ReturnType<typeof setInterval> | null = null;
     setConnState("connecting");
     setErrorMessage(null);
+    // A fresh session engages nothing, and the old session's grab died with its socket.
+    setPrivacyOn(false);
+    setPrivacyError(null);
     totalBytesRef.current = 0;
     decoder.reset();
 
@@ -89,7 +301,14 @@ export function useRemoteDesktopConnection(
       wsRef.current = ws;
 
       ws.onopen = () => {
-        ws.send(JSON.stringify({ type: "auth", nonce, ...(displayId ? { displayId } : {}) }));
+        // The cursor pref rides along with `auth`: the grabber takes it at startup, so sending
+        // it as its own message would respawn ffmpeg immediately after every connect.
+        ws.send(JSON.stringify({
+          type: "auth", nonce, ...(displayId ? { displayId } : {}), cursor: showCursorRef.current,
+          ...(codecRef.current ? { codec: codecRef.current } : {}),
+        }));
+        // Re-pin across a reconnect so a deliberate choice is not silently reset to balanced.
+        if (pinnedRef.current) ws.send(JSON.stringify(qualityMessage(pinnedRef.current)));
         pingTimer = setInterval(() => sendMessage({ type: "ping" }), PING_INTERVAL_MS);
       };
       ws.onmessage = (event) => {
@@ -97,7 +316,44 @@ export function useRemoteDesktopConnection(
           let msg: Record<string, unknown>;
           try { msg = JSON.parse(event.data); } catch { return; }
           if (msg.type === "config" && typeof msg.codec === "string") {
+            // A second `config` arrives on every quality change: the new ffmpeg has its own SPS
+            // and resolution, and `configure()` closes the old decoder and waits for a keyframe.
+            applyQualityMessage(msg);
+            setCodecState(typeof msg.encoder === "string" ? msg.encoder : null);
             decoder.configure(msg.codec).then(() => { if (!cancelled) setConnState("streaming"); });
+          } else if (msg.type === "quality") {
+            applyQualityMessage(msg);
+          } else if (msg.type === "codec") {
+            setCodecState(typeof msg.encoder === "string" ? msg.encoder : null);
+          } else if (msg.type === "resolution") {
+            setHostModeId(typeof msg.modeId === "string" ? msg.modeId : null);
+            setHostOriginalModeId(typeof msg.original === "string" ? msg.original : null);
+            setResolutionError(null);
+          } else if (msg.type === "resolutionError") {
+            setResolutionError(typeof msg.message === "string" ? msg.message : "The host refused the mode.");
+          } else if (msg.type === "privacy") {
+            setPrivacyOn(msg.enabled === true);
+            setPrivacyError(typeof msg.reason === "string" ? msg.reason : null);
+          } else if (msg.type === "audio") {
+            const on = msg.enabled === true;
+            setAudioOn(on);
+            if (!on) { audio.reset(); return; }
+            // The host announces its layout once the encoder's header has been parsed, which
+            // is what the decoder needs before the first packet arrives.
+            const channels = typeof msg.channels === "number" ? msg.channels : 2;
+            const rate = typeof msg.sampleRate === "number" ? msg.sampleRate : 48_000;
+            void audio.configure(channels, rate);
+          } else if (msg.type === "clipboard" && typeof msg.text === "string") {
+            // Sync can be turned off while a read is already in flight (the client's own
+            // `clipboardRead` is delayed by 350ms), and "off" has to mean the host's text never
+            // reaches this device's clipboard — so the check is here, at the one place it lands.
+            if (!clipboardSyncRef.current) return;
+            const text = msg.text;
+            // Only surface the manual affordance when the automatic write actually failed, so a
+            // secure-context client syncs silently and an HTTP one gets one button.
+            void writeClientClipboard(text).then((wrote) => {
+              if (!wrote && !cancelled) setPendingHostClipboard(text);
+            });
           } else if (msg.type === "error") {
             setConnState("error");
             setErrorMessage(typeof msg.message === "string" ? msg.message : "Server error");
@@ -107,6 +363,10 @@ export function useRemoteDesktopConnection(
         const bytes = new Uint8Array(event.data as ArrayBuffer);
         if (bytes.length < 1) return;
         totalBytesRef.current += bytes.length;
+        // Audio shares the socket, so the kind byte has to be read before anything is treated
+        // as a video access unit — feeding an Opus packet to the H.264 decoder is a decode
+        // error per 20ms, i.e. a stream that dies the moment sound is turned on.
+        if (bytes[0] === FRAME_AUDIO) { audio.decodePacket(bytes.subarray(1)); return; }
         decoder.decodeAccessUnit(bytes.subarray(1), bytes[0] === 1);
       };
       ws.onerror = () => { if (!cancelled) { setConnState("error"); setErrorMessage("WebSocket error"); } };
@@ -134,6 +394,7 @@ export function useRemoteDesktopConnection(
       try { wsRef.current?.close(); } catch { /* tearing down regardless */ }
       wsRef.current = null;
       try { decoder.reset(); } catch { /* tearing down regardless */ }
+      try { audio.reset(); } catch { /* tearing down regardless */ }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps -- reconnect is driven by `generation` + the display pick
   }, [generation, displayId]);
@@ -150,5 +411,27 @@ export function useRemoteDesktopConnection(
     reconnect,
     getTotalBytes,
     getFrameCount: decoder.getFrameCount,
+    frameSize: decoder.frameSize,
+    quality,
+    setQuality,
+    setCustomQuality,
+    showCursor,
+    setShowCursor,
+    codec,
+    setCodec,
+    audioOn,
+    setAudioOn: requestAudio,
+    getAudioTracks: audio.getTracks,
+    privacyOn,
+    privacyError,
+    setPrivacyOn: requestPrivacy,
+    hostModeId,
+    hostOriginalModeId,
+    resolutionError,
+    setHostMode,
+    pendingHostClipboard,
+    clearHostClipboard,
+    sendClipboard,
+    requestHostClipboard,
   };
 }

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

@@ -32,8 +32,52 @@ export interface RemoteDisplay {
   height: number;
 }
 
+/** Whether the host can stream its own audio, and why not when it cannot. Same shape and same
+ *  reasoning as `ClipboardSupport` below — informational, never a gate. */
+export interface AudioSupport {
+  available: boolean;
+  reason: string | null;
+}
+
+/** Whether the host can block its local input and blank its monitor. `canBlank` false means
+ *  input blocking works on its own — which is still worth offering. */
+export interface PrivacySupport {
+  available: boolean;
+  reason: string | null;
+  canBlank: boolean;
+}
+
+/** One of the host's own display modes. `id` is an XRandR XID as a string — a 64-bit value that
+ *  has to survive JSON, so it is never a number. */
+export interface HostMode {
+  id: string;
+  width: number;
+  height: number;
+  refresh: number;
+  current: boolean;
+  preferred: boolean;
+}
+
+/** The host's display modes. Empty with a `reason` on a host whose resolution cannot be changed
+ *  (anything but X11 today) — informational, never a gate, like the two above. */
+export interface HostResolutions {
+  output: string | null;
+  modes: HostMode[];
+  reason: string | null;
+}
+
+/** Clipboard sync is not a gate (see the server-side note): it never blocks the viewer, it only
+ *  needs explaining when the host has no tool for it. */
+export interface ClipboardSupport {
+  available: boolean;
+  action: RequirementAction | null;
+}
+
 export interface RemoteDesktopCapabilities {
   displays: RemoteDisplay[];
+  /** Every H.264 encoder that really encodes on the host, preference order; the first is the
+   *  one a session uses unless asked otherwise. Empty when ffmpeg is missing. */
+  encoders: string[];
   ffmpegAvailable: boolean;
   videoAvailable: boolean;
   inputAvailable: boolean;
@@ -43,6 +87,36 @@ export interface RemoteDesktopCapabilities {
   requirements: RemoteDesktopRequirement[];
   videoReady: boolean;
   inputReady: boolean;
+  clipboard: ClipboardSupport;
+  audio: AudioSupport;
+  privacy: PrivacySupport;
+  resolutions: HostResolutions;
+}
+
+/**
+ * Fills in whatever the host did not send.
+ *
+ * The client and the host are not one deployable: a browser holds a bundle until it reloads, a
+ * phone holds one until its service worker updates, and `dist/ppm` is a separately-built binary
+ * — so a *new* viewer routinely talks to an *older* `/capabilities`. Every field below arrived
+ * in a different version, and reading one that predates the host crashes the whole viewer
+ * rather than degrading: `caps.resolutions.modes` on a host that has never heard of
+ * `resolutions` is a `TypeError` past the last error boundary, i.e. the blank "could not finish
+ * rendering" page. The call sites cannot be trusted to each remember an optional chain, and a
+ * missing one is invisible until that exact version pairing happens — so the shape is repaired
+ * once, here, and the interface stays non-optional because it is now actually true.
+ */
+export function normalizeCapabilities(raw: RemoteDesktopCapabilities): RemoteDesktopCapabilities {
+  return {
+    ...raw,
+    displays: raw.displays ?? [],
+    encoders: raw.encoders ?? [],
+    requirements: raw.requirements ?? [],
+    clipboard: raw.clipboard ?? { available: false, action: null },
+    audio: raw.audio ?? { available: false, reason: null },
+    privacy: raw.privacy ?? { available: false, reason: null, canBlank: false },
+    resolutions: raw.resolutions ?? { output: null, modes: [], reason: null },
+  };
 }
 
 export const READINESS_POLL_MS = 2000;
@@ -62,7 +136,7 @@ export function useRemoteDesktopReadiness(poll: boolean): {
   useEffect(() => {
     let cancelled = false;
     api.get<RemoteDesktopCapabilities>("/api/remote-desktop/capabilities")
-      .then((c) => { if (!cancelled) { setCaps(c); setFailed(false); } })
+      .then((c) => { if (!cancelled) { setCaps(normalizeCapabilities(c)); setFailed(false); } })
       .catch(() => { if (!cancelled) setFailed(true); });
     return () => { cancelled = true; };
   }, [tick]);

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

@@ -0,0 +1,103 @@
+/**
+ * Records the viewer's canvas (and the session audio, when it is on) to a file the browser
+ * downloads on stop. See `remote-desktop-recording.ts` for why the canvas is the source.
+ *
+ * Chunks are kept in memory until stop, which is the honest limit of this approach: a long
+ * recording is a long array of blobs. `MAX_RECORDING_MS` stops it by itself rather than letting
+ * a session left recording overnight grow until the tab is killed — a file that stops after two
+ * hours is recoverable, a tab that dies takes everything with it.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  downloadBlob, extensionForMime, pickRecordingMime, recordingFileName,
+} from "./remote-desktop-recording";
+
+/** Two hours. Long enough for any real session, short of the point where the blob array is the
+ *  problem (~2 GB at a 1440p60 rung). */
+export const MAX_RECORDING_MS = 2 * 60 * 60 * 1000;
+
+export interface UseRemoteDesktopRecorderResult {
+  /** True while recording. */
+  recording: boolean;
+  /** Whole seconds since the recording started; 0 when idle. Drives the toolbar's timer. */
+  elapsedSec: number;
+  /** null when this browser has no `MediaRecorder` support at all — the UI hides the control
+   *  rather than offering a button that cannot work. */
+  supported: boolean;
+  /** Start, or stop-and-download. Safe to call in either state. */
+  toggle: () => void;
+}
+
+export function useRemoteDesktopRecorder(
+  canvasRef: React.RefObject<HTMLCanvasElement | null>,
+  /** Extra tracks to mux in — the session's audio, when it is playing. Read at start time. */
+  getAudioTracks?: () => MediaStreamTrack[],
+): UseRemoteDesktopRecorderResult {
+  const recorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+  const [recording, setRecording] = useState(false);
+  const [elapsedSec, setElapsedSec] = useState(0);
+  const mime = useRef<string | null>(null);
+  if (mime.current === null) mime.current = pickRecordingMime();
+
+  const stop = useCallback(() => {
+    // `stop()` fires `dataavailable` then `onstop`, which is where the download happens — so
+    // this only asks; it does not assemble the file itself.
+    recorderRef.current?.stop();
+  }, []);
+
+  const start = useCallback(() => {
+    const canvas = canvasRef.current;
+    const mimeType = mime.current;
+    if (!canvas || !mimeType || recorderRef.current) return;
+    // No fps argument: follow the canvas's own draw cadence (see the module header).
+    const stream = canvas.captureStream();
+    for (const track of getAudioTracks?.() ?? []) stream.addTrack(track);
+    let recorder: MediaRecorder;
+    try {
+      recorder = new MediaRecorder(stream, { mimeType });
+    } catch {
+      return; // the MIME was supported but this stream's tracks are not; nothing to report
+    }
+    chunksRef.current = [];
+    recorder.ondataavailable = (e) => { if (e.data.size > 0) chunksRef.current.push(e.data); };
+    recorder.onstop = () => {
+      const blob = new Blob(chunksRef.current, { type: mimeType });
+      chunksRef.current = [];
+      recorderRef.current = null;
+      setRecording(false);
+      setElapsedSec(0);
+      // A recorder stopped before any frame was drawn has nothing to save, and an empty file
+      // is worse than no file: it looks like the feature ran and lost the recording.
+      if (blob.size > 0) downloadBlob(blob, recordingFileName(extensionForMime(mimeType)));
+    };
+    // One second per chunk rather than one blob at the end: a tab that crashes mid-recording
+    // still has everything up to the last second in memory for `onstop` to assemble, and the
+    // allocation pattern stays flat instead of one giant buffer at the finish.
+    recorder.start(1_000);
+    recorderRef.current = recorder;
+    setRecording(true);
+    setElapsedSec(0);
+  }, [canvasRef, getAudioTracks]);
+
+  const toggle = useCallback(() => {
+    if (recorderRef.current) stop(); else start();
+  }, [start, stop]);
+
+  useEffect(() => {
+    if (!recording) return;
+    const startedAt = Date.now();
+    const id = setInterval(() => {
+      const ms = Date.now() - startedAt;
+      setElapsedSec(Math.floor(ms / 1000));
+      if (ms >= MAX_RECORDING_MS) stop();
+    }, 1_000);
+    return () => clearInterval(id);
+  }, [recording, stop]);
+
+  // A viewer closed mid-recording must still save what it has: without this the recorder is
+  // garbage-collected with the chunks and the whole recording is silently lost.
+  useEffect(() => () => { recorderRef.current?.stop(); }, []);
+
+  return { recording, elapsedSec, supported: mime.current !== null, toggle };
+}

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

@@ -6,6 +6,10 @@
  * - 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.
+ * - A paste is taken from the `paste` event rather than `beforeinput`: Chromium reports it as
+ *   `insertFromPaste` with the text in `data` and a *null* `dataTransfer`, which is the opposite
+ *   of what the spec's contenteditable case describes — `clipboardData` is the one place every
+ *   browser agrees on. `preventDefault()` there also stops 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
@@ -46,7 +50,12 @@ export function forwardBeforeInput(inputType: string, data: string | null, send:
   }
 }
 
-export function useRemoteDesktopVirtualKeyboard(sendMessage: Send, enabled: boolean): UseRemoteDesktopVirtualKeyboardResult {
+export function useRemoteDesktopVirtualKeyboard(
+  sendMessage: Send,
+  enabled: boolean,
+  /** Text pasted into the hidden input, for the caller to route through the host clipboard. */
+  onPasteText?: (text: string) => void,
+): UseRemoteDesktopVirtualKeyboardResult {
   const inputRef = useRef<HTMLInputElement | null>(null);
 
   useEffect(() => {
@@ -74,6 +83,12 @@ export function useRemoteDesktopVirtualKeyboard(sendMessage: Send, enabled: bool
       if (e.data) sendMessage({ type: "text", text: e.data });
       input.value = ""; // the composed text landed in the input; the host already has it
     };
+    const onPaste = (e: ClipboardEvent) => {
+      const text = e.clipboardData?.getData("text/plain");
+      if (!text || !onPasteText) return;
+      e.preventDefault(); // suppresses the `insertFromPaste` beforeinput that would double it
+      onPasteText(text);
+    };
     const onBlur = () => releaseAll();
     const onVisibilityChange = () => { if (document.hidden) releaseAll(); };
 
@@ -81,6 +96,7 @@ export function useRemoteDesktopVirtualKeyboard(sendMessage: Send, enabled: bool
     input.addEventListener("keyup", onKeyUp);
     input.addEventListener("beforeinput", onBeforeInput);
     input.addEventListener("compositionend", onCompositionEnd);
+    input.addEventListener("paste", onPaste);
     input.addEventListener("blur", onBlur);
     document.addEventListener("visibilitychange", onVisibilityChange);
 
@@ -89,11 +105,12 @@ export function useRemoteDesktopVirtualKeyboard(sendMessage: Send, enabled: bool
       input.removeEventListener("keyup", onKeyUp);
       input.removeEventListener("beforeinput", onBeforeInput);
       input.removeEventListener("compositionend", onCompositionEnd);
+      input.removeEventListener("paste", onPaste);
       input.removeEventListener("blur", onBlur);
       document.removeEventListener("visibilitychange", onVisibilityChange);
       releaseAll();
     };
-  }, [enabled, sendMessage]);
+  }, [enabled, sendMessage, onPasteText]);
 
   const show = useCallback(() => inputRef.current?.focus(), []);