@opengeni/react 0.52.1 → 1.0.1

package/src/hooks/use-computer-frame-stream.ts

@@ -9,7 +9,9 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import {
   decodeStreamFrame,
   decodeStreamOpenAck,
+  encodeStreamClose,
   encodeStreamOpen,
+  STREAM_CLOSE_REASON_NORMAL,
   STREAM_KIND_COMPUTER,
   STREAM_ROLE_CLIENT,
 } from "../lib/relay-wire";
@@ -39,6 +41,8 @@ export type ComputerFrameWebSocketFactory = (
 const RELAY_TAG_OPEN = 1;
 const RELAY_TAG_OPEN_ACK = 2;
 const RELAY_TAG_FRAME = 3;
+const RELAY_TAG_CLOSE = 4;
+const MAX_AUTOMATIC_RECONNECTS_WITHOUT_A_FRAME = 2;
 
 export type UseComputerFrameStreamOptions = EmbeddedComputerInteractionClientOverride & {
   computerSessionId: string | null;
@@ -53,7 +57,7 @@ export type UseComputerFrameStreamResult = {
   frame: ComputerFrame | null;
   attachment: Pick<
     ComputerSessionAttachment,
-    "computerSessionId" | "controllerGeneration" | "targetId" | "expiresAt"
+    "computerSessionId" | "controllerGeneration" | "targetId" | "stream" | "expiresAt"
   > | null;
   error: Error | null;
   reconnect: () => void;
@@ -102,66 +106,144 @@ export function useComputerFrameStream(
 
     let disposed = false;
     let socket: ComputerFrameWebSocket | null = null;
+    let socketHandlers: {
+      open: () => void;
+      message: (event: MessageEvent) => void;
+      error: () => void;
+      close: () => void;
+    } | null = null;
     let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
     let expiryTimer: ReturnType<typeof setTimeout> | null = null;
     let failures = 0;
     let controllerGeneration: string | null = null;
+    let activeAttachment: ComputerSessionAttachment | null = null;
     let activeStream: ComputerSessionAttachment["stream"] | null = null;
+    let attachmentExpiresAt = 0;
+    let lastRelaySequence: string | null = null;
     let relayAccepted = false;
+    let pendingFrame: { bytes: Uint8Array; source: ComputerFrameWebSocket } | null = null;
+    let decodingFrame = false;
     const attachmentAbort = new AbortController();
 
-    const clearSocket = () => {
+    const clearSocket = (terminateProducer = false) => {
       if (!socket) return;
-      socket.removeEventListener("open", onOpen);
-      socket.removeEventListener("message", onMessage);
-      socket.removeEventListener("error", onError);
-      socket.removeEventListener("close", onClose);
-      if (socket.readyState === 0 || socket.readyState === 1) {
-        socket.close(1000, "viewer detached");
+      const current = socket;
+      const handlers = socketHandlers;
+      if (terminateProducer && activeStream?.kind === "relay" && socket.readyState === 1) {
+        try {
+          socket.send(
+            relayDatagram(
+              RELAY_TAG_CLOSE,
+              encodeStreamClose({
+                channelId: activeStream.channel.channelId,
+                reason: STREAM_CLOSE_REASON_NORMAL,
+                message: "viewer detached",
+              }),
+            ),
+          );
+        } catch {
+          // OPEN can race a transport close. Local teardown must still finish.
+        }
+      }
+      if (handlers) {
+        current.removeEventListener("open", handlers.open);
+        current.removeEventListener("message", handlers.message);
+        current.removeEventListener("error", handlers.error);
+        current.removeEventListener("close", handlers.close);
+      }
+      if (current.readyState === 0 || current.readyState === 1) {
+        current.close(1000, "viewer detached");
       }
       socket = null;
+      socketHandlers = null;
+      pendingFrame = null;
     };
 
     const scheduleReconnect = () => {
       if (disposed || reconnectTimer) return;
+      if (failures >= MAX_AUTOMATIC_RECONNECTS_WITHOUT_A_FRAME) return;
       const delay = Math.min(5_000, 250 * 2 ** Math.min(failures, 5));
       failures += 1;
       setResult((current) => ({ ...current, state: "reconnecting" }));
       reconnectTimer = setTimeout(() => {
         reconnectTimer = null;
-        void connect();
+        connectSocket();
       }, delay);
     };
 
-    const fail = (cause: unknown) => {
+    const fail = (cause: unknown, reconnectAutomatically = true) => {
       if (disposed) return;
       const error = cause instanceof Error ? cause : new Error(String(cause));
       setResult((current) => ({ ...current, state: "error", error }));
       clearSocket();
-      scheduleReconnect();
+      if (reconnectAutomatically) scheduleReconnect();
     };
 
-    const onOpen = () => {
-      if (disposed) return;
-      failures = 0;
+    const onOpen = (source: ComputerFrameWebSocket) => {
+      if (disposed || source !== socket) return;
       if (activeStream?.kind === "relay") {
         const body = encodeStreamOpen({
           channel: { ...activeStream.channel, kind: STREAM_KIND_COMPUTER },
           token: activeStream.token,
           role: STREAM_ROLE_CLIENT,
-          resumeFromSeq: "0",
+          resumeFromSeq:
+            lastRelaySequence === null ? "0" : (BigInt(lastRelaySequence) + 1n).toString(),
         });
-        socket?.send(relayDatagram(RELAY_TAG_OPEN, body));
+        try {
+          source.send(relayDatagram(RELAY_TAG_OPEN, body));
+        } catch (error) {
+          fail(error);
+        }
         return;
       }
       setResult((current) => ({ ...current, state: "live", error: null }));
     };
 
-    const onMessage = (event: MessageEvent) => {
+    const drainLatestFrame = async () => {
+      if (decodingFrame) return;
+      decodingFrame = true;
+      try {
+        while (pendingFrame) {
+          if (disposed) break;
+          const pending = pendingFrame;
+          pendingFrame = null;
+          const { bytes, source } = pending;
+          const frame = await decodeComputerFrameMessage(bytes);
+          if (disposed || source !== socket) continue;
+          if (frame.computerSessionId !== computerSessionId || frame.targetId !== targetId) {
+            throw new Error("computer frame belongs to another resource");
+          }
+          if (!controllerGeneration || frame.controllerGeneration !== controllerGeneration) {
+            throw new Error("computer frame belongs to a stale controller");
+          }
+          const key = `${computerSessionId}:${targetId}:${frame.controllerGeneration}:${frame.targetGeneration}`;
+          if (latestRef.current.key === key && frame.sequence <= latestRef.current.sequence)
+            continue;
+          latestRef.current = { key, sequence: frame.sequence };
+          // A real decoded frame—not merely a socket handshake—is the recovery
+          // boundary. Resetting on `open` caused a dead producer to reconnect
+          // forever and continuously spawn fresh relay/SCK work.
+          failures = 0;
+          setResult((current) => ({
+            ...current,
+            state: "live",
+            frame,
+            error: null,
+          }));
+        }
+      } catch (cause) {
+        fail(cause);
+      } finally {
+        decodingFrame = false;
+        if (!disposed && pendingFrame) void drainLatestFrame();
+      }
+    };
+
+    const onMessage = (source: ComputerFrameWebSocket, event: MessageEvent) => {
       void (async () => {
         try {
           const bytes = await messageBytes(event.data);
-          if (disposed) return;
+          if (disposed || source !== socket) return;
           let frameBytes = bytes;
           if (activeStream?.kind === "relay") {
             if (bytes.length < 1) throw new Error("computer relay returned an empty message");
@@ -170,46 +252,93 @@ export function useComputerFrameStream(
             if (tag === RELAY_TAG_OPEN_ACK) {
               const ack = decodeStreamOpenAck(body);
               if (!ack.accepted) {
+                activeAttachment = null;
+                activeStream = null;
+                attachmentExpiresAt = 0;
                 throw new Error(ack.error?.message ?? "computer stream was rejected by the relay");
               }
               relayAccepted = true;
               return;
             }
+            if (tag === RELAY_TAG_CLOSE) {
+              // A relay close is terminal for this producer/channel. Reusing
+              // the same attachment only reconnects to a dead channel forever;
+              // invalidate it so the retry mints a fresh producer.
+              activeAttachment = null;
+              activeStream = null;
+              attachmentExpiresAt = 0;
+              lastRelaySequence = null;
+              relayAccepted = false;
+              fail(new Error("Computer frame source ended."), false);
+              return;
+            }
             if (tag !== RELAY_TAG_FRAME || !relayAccepted) return;
-            frameBytes = decodeStreamFrame(body).data;
+            const relayFrame = decodeStreamFrame(body);
+            lastRelaySequence = relayFrame.seq;
+            frameBytes = relayFrame.data;
           }
-          const frame = await decodeComputerFrameMessage(frameBytes);
-          if (disposed) return;
-          if (frame.computerSessionId !== computerSessionId || frame.targetId !== targetId) {
-            throw new Error("computer frame belongs to another resource");
-          }
-          if (!controllerGeneration || frame.controllerGeneration !== controllerGeneration) {
-            throw new Error("computer frame belongs to a stale controller");
-          }
-          const key = `${computerSessionId}:${targetId}:${frame.controllerGeneration}:${frame.targetGeneration}`;
-          if (latestRef.current.key === key && frame.sequence <= latestRef.current.sequence) return;
-          latestRef.current = { key, sequence: frame.sequence };
-          setResult((current) => ({
-            ...current,
-            state: "live",
-            frame,
-            error: null,
-          }));
+          // Digest verification can take longer than an inter-frame interval on
+          // low-power clients. Keep exactly one pending encoded frame and replace
+          // it with newer input while a decode is in flight; never build latency.
+          pendingFrame = { bytes: frameBytes, source };
+          void drainLatestFrame();
         } catch (cause) {
           fail(cause);
         }
       })();
     };
 
-    const onError = () => fail(new Error("Computer view lost connection."));
+    const onError = (source: ComputerFrameWebSocket) => {
+      if (source !== socket) return;
+      fail(new Error("Computer view lost connection."));
+    };
 
-    const onClose = () => {
-      if (disposed) return;
+    const onClose = (source: ComputerFrameWebSocket) => {
+      if (disposed || source !== socket) return;
       clearSocket();
       scheduleReconnect();
     };
 
-    const connect = async () => {
+    const connectSocket = () => {
+      if (disposed) return;
+      clearSocket();
+      if (!activeAttachment || !activeStream || attachmentExpiresAt <= Date.now() + 1_000) {
+        void attach();
+        return;
+      }
+      if (activeStream.kind === "direct_rfb") {
+        setResult((current) => ({ ...current, state: "live", error: null }));
+        return;
+      }
+      relayAccepted = false;
+      setResult((current) => ({
+        ...current,
+        state: "connecting",
+        error: null,
+      }));
+      const createSocket =
+        factoryRef.current ?? ((url: string, protocols: string[]) => new WebSocket(url, protocols));
+      const openedSocket = createSocket(
+        activeStream.kind === "relay"
+          ? activeStream.url
+          : computerFrameSocketUrl(activeAttachment, streamRef.current),
+        activeStream.kind === "direct_websocket" ? [...activeStream.protocols] : [],
+      );
+      socket = openedSocket;
+      socketHandlers = {
+        open: () => onOpen(openedSocket),
+        message: (event) => onMessage(openedSocket, event),
+        error: () => onError(openedSocket),
+        close: () => onClose(openedSocket),
+      };
+      openedSocket.binaryType = "arraybuffer";
+      openedSocket.addEventListener("open", socketHandlers.open);
+      openedSocket.addEventListener("message", socketHandlers.message);
+      openedSocket.addEventListener("error", socketHandlers.error);
+      openedSocket.addEventListener("close", socketHandlers.close);
+    };
+
+    const attach = async () => {
       if (disposed) return;
       clearSocket();
       if (expiryTimer) clearTimeout(expiryTimer);
@@ -237,7 +366,10 @@ export function useComputerFrameStream(
           throw new Error("computer attachment does not match the requested resource");
         }
         controllerGeneration = attachment.controllerGeneration;
+        activeAttachment = attachment;
         activeStream = attachment.stream;
+        attachmentExpiresAt = Date.parse(attachment.expiresAt);
+        lastRelaySequence = null;
         relayAccepted = false;
         setResult((current) => ({
           ...current,
@@ -246,46 +378,37 @@ export function useComputerFrameStream(
             computerSessionId: attachment.computerSessionId,
             controllerGeneration: attachment.controllerGeneration,
             targetId: attachment.targetId,
+            stream: attachment.stream,
             expiresAt: attachment.expiresAt,
           },
           error: null,
         }));
-        const createSocket =
-          factoryRef.current ??
-          ((url: string, protocols: string[]) => new WebSocket(url, protocols));
-        socket = createSocket(
-          attachment.stream.kind === "relay"
-            ? attachment.stream.url
-            : computerFrameSocketUrl(attachment, streamRef.current),
-          attachment.stream.kind === "direct_websocket" ? [...attachment.stream.protocols] : [],
-        );
-        socket.binaryType = "arraybuffer";
-        socket.addEventListener("open", onOpen);
-        socket.addEventListener("message", onMessage);
-        socket.addEventListener("error", onError);
-        socket.addEventListener("close", onClose);
-        const expiresAt = Date.parse(attachment.expiresAt);
-        const refreshIn = Number.isFinite(expiresAt)
-          ? Math.max(1_000, expiresAt - Date.now() - 5_000)
+        const refreshIn = Number.isFinite(attachmentExpiresAt)
+          ? Math.max(1_000, attachmentExpiresAt - Date.now() - 5_000)
           : 60_000;
         expiryTimer = setTimeout(() => {
           if (disposed) return;
-          clearSocket();
-          void connect();
+          clearSocket(true);
+          activeAttachment = null;
+          activeStream = null;
+          attachmentExpiresAt = 0;
+          void attach();
         }, refreshIn);
+        connectSocket();
       } catch (cause) {
         if (attachmentAbort.signal.aborted || disposed) return;
         fail(cause);
       }
     };
 
-    void connect();
+    void attach();
     return () => {
       disposed = true;
+      pendingFrame = null;
       attachmentAbort.abort();
       if (reconnectTimer) clearTimeout(reconnectTimer);
       if (expiryTimer) clearTimeout(expiryTimer);
-      clearSocket();
+      clearSocket(true);
     };
   }, [client, enabled, nonce, options.computerSessionId, options.targetId, workspaceId]);
 

package/src/hooks/use-computer-session.ts

@@ -1,6 +1,7 @@
 import type {
   ComputerAction,
   ComputerActionReceipt,
+  ComputerClipboard,
   ComputerFrame,
   ComputerObservation,
   ComputerSession,
@@ -28,6 +29,7 @@ export type UseComputerSessionResult = {
   mutating: boolean;
   error: Error | null;
   refresh: () => Promise<void>;
+  readClipboard: () => Promise<ComputerClipboard>;
   /** Changes only this viewer's target cursor; it never takes ownership or
    * foregrounds an application. */
   selectTarget: (targetId: string) => Promise<ComputerTarget>;
@@ -112,7 +114,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
       ]);
       if (!mountedRef.current || requestRef.current.id !== id) return;
       const targets = sortComputerTargets(targetResponse.targets);
-      const selected = chooseTarget(targets, selectedTargetIdRef.current);
+      const selected = chooseTarget(targets, selectedTargetIdRef.current, session.platform);
       const observation = selected
         ? await client.observeComputerTarget(workspaceId, computerSessionId, selected.id, {
             signal: controller.signal,
@@ -364,6 +366,11 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
     [dispatchAction],
   );
 
+  const readClipboard = useCallback(async (): Promise<ComputerClipboard> => {
+    if (!computerSessionId) throw new Error("No ComputerSession is selected.");
+    return await client.readComputerClipboard(workspaceId, computerSessionId);
+  }, [client, computerSessionId, workspaceId]);
+
   return {
     session: visible.session,
     targets: visible.targets,
@@ -374,6 +381,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
     mutating: visible.mutating,
     error: visible.error,
     refresh,
+    readClipboard,
     selectTarget,
     act,
     actFromFrame,
@@ -407,9 +415,21 @@ function emptyState(computerSessionId: string | null, loading: boolean): Compute
 function chooseTarget(
   targets: readonly ComputerTarget[],
   preferredId: string | null,
+  platform: ComputerSession["platform"],
 ): ComputerTarget | null {
+  const preferred = targets.find((target) => target.id === preferredId);
+  if (preferred) return preferred;
+  if (platform === "linux") {
+    return (
+      targets.find((target) => target.focused && target.kind === "screen") ??
+      targets.find((target) => target.kind === "screen") ??
+      targets.find((target) => target.focused && target.kind === "window") ??
+      targets.find((target) => target.kind === "window") ??
+      targets[0] ??
+      null
+    );
+  }
   return (
-    targets.find((target) => target.id === preferredId) ??
     targets.find((target) => target.focused && target.kind === "window") ??
     targets.find((target) => target.kind === "window") ??
     targets.find((target) => target.focused && target.kind === "app") ??

package/src/hooks/use-computer-sessions.ts

@@ -9,13 +9,13 @@ import {
   type EmbeddedComputerInteractionClientOverride,
   useEmbeddedComputerInteraction,
 } from "../session-context";
-import { usePageLiveActivity } from "./internal";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
 
 export type UseComputerSessionsOptions = EmbeddedComputerInteractionClientOverride & {
   /** Current agent/session relevance. Workspace peers remain in `sessions`. */
   sessionId?: string | undefined;
   enabled?: boolean | undefined;
-  /** Temporary invalidation path until the interaction event stream lands. */
+  /** Polling fallback used only while the workspace invalidation stream is unavailable. */
   pollIntervalMs?: number | undefined;
 };
 
@@ -43,11 +43,14 @@ export type UseComputerSessionsResult = {
 export function useComputerSessions(
   options: UseComputerSessionsOptions = {},
 ): UseComputerSessionsResult {
-  const { client, workspaceId, registerSessionReconciler } =
-    useEmbeddedComputerInteraction(options);
+  const {
+    client,
+    workspaceId,
+    registerSessionReconciler,
+    workspaceInteractionEvent,
+    workspaceInteractionConnectionState,
+  } = useEmbeddedComputerInteraction(options);
   const enabled = options.enabled ?? true;
-  const pageLive = usePageLiveActivity();
-  const pollIntervalMs = Math.max(1_000, options.pollIntervalMs ?? 3_000);
   const [state, setState] = useState<ComputerRegistryState>(() => emptyState(workspaceId, enabled));
   const requestRef = useRef<{ id: number; controller: AbortController | null }>({
     id: 0,
@@ -120,13 +123,16 @@ export function useComputerSessions(
     };
   }, [cancelLoad, enabled, load, workspaceId]);
 
-  useEffect(() => {
-    if (!enabled || !pageLive) return;
-    const timer = setInterval(() => {
-      if (!requestRef.current.controller) void load(false);
-    }, pollIntervalMs);
-    return () => clearInterval(timer);
-  }, [enabled, load, pageLive, pollIntervalMs]);
+  useInteractionInvalidation({
+    workspaceId,
+    key: workspaceId,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    knownRevision: visible.revision,
+    refresh,
+    fallbackPollIntervalMs: options.pollIntervalMs,
+  });
 
   useEffect(() => {
     if (!enabled || !options.sessionId) return;

package/src/hooks/use-desktop-stream.ts

@@ -6,7 +6,7 @@ import {
   type DesktopRfbLike,
   type DesktopStreamCapability,
 } from "@opengeni/sdk";
-import { type RefObject, useEffect, useRef, useState } from "react";
+import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
 import { type DesktopWebSocketFactory, useRelayFrameStream } from "./use-relay-frame-stream";
 
 export type UseDesktopStreamOptions = {
@@ -19,6 +19,8 @@ export type UseDesktopStreamOptions = {
   scaleViewport?: boolean | undefined;
   /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
   rfbFactory?: DesktopRfbFactory | undefined;
+  /** Additional WebSocket protocols for an authenticated placement proxy. */
+  webSocketProtocols?: string[] | undefined;
   /** Custom socket factory for the `relay-frames` transport (tests). Defaults to
    *  `new WebSocket(url)`. Mirrors `rfbFactory` for the frame renderer. */
   webSocketFactory?: DesktopWebSocketFactory | undefined;
@@ -29,6 +31,8 @@ export type UseDesktopStreamResult = {
   error: Error | null;
   /** Manual reconnect (e.g. after a securityfailure once a fresh URL arrives). */
   reconnect: () => void;
+  /** Synchronous input on the already-open RFB authority. */
+  sendKey?: ((keysym: number, code: string, down?: boolean) => boolean) | undefined;
 };
 
 /** Lazy-load @novnc/novnc's RFB as the default factory. Imported inside the
@@ -44,7 +48,10 @@ async function defaultRfbFactory(): Promise<DesktopRfbFactory> {
     default: new (
       t: HTMLElement,
       u: string,
-      o: { credentials?: { password?: string | undefined } | undefined },
+      o: {
+        credentials?: { password?: string | undefined } | undefined;
+        wsProtocols?: string[] | undefined;
+      },
     ) => DesktopRfbLike;
   };
   const RFB = mod.default;
@@ -71,8 +78,15 @@ async function defaultRfbFactory(): Promise<DesktopRfbFactory> {
  * way, so `DesktopViewer` is transport-agnostic.
  */
 export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopStreamResult {
-  const { capability, containerRef, interactive, scaleViewport, rfbFactory, webSocketFactory } =
-    options;
+  const {
+    capability,
+    containerRef,
+    interactive,
+    scaleViewport,
+    rfbFactory,
+    webSocketProtocols,
+    webSocketFactory,
+  } = options;
 
   // The self-hosted PNG-frame path. Always invoked (rules of hooks); dormant
   // unless `transport === "relay-frames"`, in which case it owns the surface.
@@ -91,6 +105,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   };
 
   const reconnect = () => setNonce((n) => n + 1);
+  const sendKey = useCallback((keysym: number, code: string, down?: boolean): boolean => {
+    const rfb = rfbRef.current;
+    if (!rfb?.sendKey || rfb.viewOnly || stateRef.current !== "connected") return false;
+    rfb.sendKey(keysym, code, down);
+    return true;
+  }, []);
 
   const url = capability?.url ?? null;
   // The credential is keyed into the connect effect so a token rotation (new
@@ -99,6 +119,14 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   const token = capability?.token ?? null;
   const transport = capability?.transport ?? null;
   const mode = capability?.mode ?? "read-only";
+  // For direct sandbox RFB, authorization is carried in WebSocket
+  // subprotocols rather than `capability.token`. The view grant rotates before
+  // expiry while the URL stays stable, so the protocol credential is a real
+  // connection boundary: keeping the old socket leaves the viewer black once
+  // browserd expires it. Key the effect on the primitive value (not the caller's
+  // array identity) so credential rotation reconnects exactly once without
+  // churning on ordinary renders.
+  const webSocketProtocolsKey = webSocketProtocols?.join("\u0000") ?? "";
 
   // The live RFB handle. Holding it in a ref lets us flip view-only (take
   // control / return control) and re-scale on the OPEN connection instead of
@@ -113,10 +141,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   const scaleViewportRef = useRef(scaleViewport);
   const modeRef = useRef(mode);
   const rfbFactoryRef = useRef(rfbFactory);
+  const webSocketProtocolsRef = useRef(webSocketProtocols);
   interactiveRef.current = interactive;
   scaleViewportRef.current = scaleViewport;
   modeRef.current = mode;
   rfbFactoryRef.current = rfbFactory;
+  webSocketProtocolsRef.current = webSocketProtocols;
 
   // read-only is forced when the server says so OR the caller didn't opt in.
   const viewOnlyFor = (m: string, want: boolean | undefined) => m === "read-only" || !want;
@@ -164,6 +194,7 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
         setBoth(nextDesktopState(stateRef.current, { type: "negotiated" }));
         rfb = factory(container, socketUrl, {
           credentials: token ? { password: token } : undefined,
+          ...(webSocketProtocolsRef.current ? { wsProtocols: webSocketProtocolsRef.current } : {}),
         });
         rfb.viewOnly = viewOnlyFor(modeRef.current, interactiveRef.current);
         // Fit-to-panel: SCALE the 1280x800 framebuffer down to the container
@@ -200,11 +231,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
       }
     };
     // ONLY a real transport change reconnects: a fresh url (rotation), a new
-    // credential, the transport flipping, or an explicit manual reconnect
+    // credential (RFB password OR bearer subprotocol), the transport flipping,
+    // or an explicit manual reconnect
     // (`nonce`). `interactive`/`scaleViewport`/`mode`/`rfbFactory` are read via
     // refs and applied live below — they must never re-open the socket.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [url, token, transport, nonce]);
+  }, [url, token, transport, webSocketProtocolsKey, nonce]);
 
   // Apply take-control / return-control to the OPEN connection in place. noVNC
   // honours `viewOnly` live, so flipping it neither blinks the surface nor drops
@@ -236,5 +268,5 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
   // drives; for `vnc-ws` (and everything else) the noVNC path drives while the
   // frame renderer stays idle. Same public shape either way.
   if (transport === "relay-frames") return frameStream;
-  return { state, error, reconnect };
+  return { state, error, reconnect, sendKey };
 }