From a2d03555f872025bd9753c706cd24d8ffa432e05 Mon Sep 17 00:00:00 2001 From: ZacharyZcR Date: Mon, 9 Nov 2026 15:05:19 +0800 Subject: [PATCH] fix: claim the Windows keys for a focused remote session On Windows the local shell takes the Windows key and shortcuts such as Win+R before the page sees them, so they never reached the remote desktop. The Moonlight tab already asks for a keyboard lock; Guacamole sessions did not. Request a keyboard lock on MetaLeft and MetaRight while the display captures input and release it with the focus or the connection. Browsers only honour the lock in fullscreen, so windowed sessions keep using the toolbar keys. --- src/frontend/GuacamoleDisplay.tsx | 4 +++ src/frontend/guacamole-meta-key.ts | 22 +++++++++++++ tests/frontend/guacamole-key-release.test.ts | 7 +++- tests/frontend/guacamole-meta-key.test.ts | 34 +++++++++++++++++++- 4 files changed, 65 insertions(+), 2 deletions(-) diff --git a/src/frontend/GuacamoleDisplay.tsx b/src/frontend/GuacamoleDisplay.tsx index d535331..d490abc 100644 --- a/src/frontend/GuacamoleDisplay.tsx +++ b/src/frontend/GuacamoleDisplay.tsx @@ -60,6 +60,7 @@ import { createRdpReadyGate } from "./guacamole-ready.ts"; import { remoteKeysym, isToggleKey, + systemKeyLock, watchRightAlt, } from "./guacamole-meta-key.ts"; @@ -191,6 +192,7 @@ export const GuacamoleDisplay = forwardRef< const unbindAudioRef = useRef<(() => void) | null>(null); const unbindPointerRef = useRef<(() => void) | null>(null); const unwatchAltRef = useRef<(() => void) | null>(null); + const systemKeysRef = useRef(systemKeyLock()); const scaleRef = useRef(1); const fitScaleRef = useRef(1); const zoomRef = useRef(1); @@ -233,6 +235,7 @@ export const GuacamoleDisplay = forwardRef< unbindAudioRef.current = null; unwatchAltRef.current?.(); unwatchAltRef.current = null; + systemKeysRef.current(false); const client = clientRef.current; clientRef.current = null; tunnelWatchRef.current?.stop(); @@ -447,6 +450,7 @@ export const GuacamoleDisplay = forwardRef< windowFocusedRef.current && (hasKeyboardFocusRef.current || displayIsFocused); + systemKeysRef.current(shouldCaptureInput); if (!shouldCaptureInput) { keyboard.reset(); keyboard.onkeydown = null; diff --git a/src/frontend/guacamole-meta-key.ts b/src/frontend/guacamole-meta-key.ts index aa30b30..de5175a 100644 --- a/src/frontend/guacamole-meta-key.ts +++ b/src/frontend/guacamole-meta-key.ts @@ -222,3 +222,25 @@ export function remoteKeysym( optionKeysSent.delete(keysym); return sent; } + +type KeyboardLock = { + lock?: (codes: string[]) => Promise; + unlock?: () => void; +}; + +/** + * Claims the Windows keys for a focused session, so Win+R and the like reach + * the remote desktop instead of the local one. Browsers only honour the lock + * in fullscreen, so windowed sessions keep the toolbar keys. + */ +export function systemKeyLock( + keyboard = (navigator as Navigator & { keyboard?: KeyboardLock }).keyboard, +): (on: boolean) => void { + let locked = false; + return (on) => { + if (on === locked) return; + locked = on; + if (on) void keyboard?.lock?.(["MetaLeft", "MetaRight"])?.catch(() => {}); + else keyboard?.unlock?.(); + }; +} diff --git a/tests/frontend/guacamole-key-release.test.ts b/tests/frontend/guacamole-key-release.test.ts index 34d2ad8..26a18b5 100644 --- a/tests/frontend/guacamole-key-release.test.ts +++ b/tests/frontend/guacamole-key-release.test.ts @@ -34,7 +34,7 @@ if (!callback) throw new Error("Missing refreshKeyboardHandlers callback"); const runRefresh = new Function( "state", ts.transpileModule( - `const { keyboardRef, clientRef, displayElementRef, isVisible, windowFocusedRef, hasKeyboardFocusRef, sessionProtocolRef, remoteKeysym, isToggleKey } = state; + `const { keyboardRef, clientRef, displayElementRef, isVisible, windowFocusedRef, hasKeyboardFocusRef, sessionProtocolRef, remoteKeysym, isToggleKey, systemKeysRef } = state; (${callback})();`, { compilerOptions: { target: ts.ScriptTarget.ES2022 } }, ).outputText, @@ -68,6 +68,7 @@ describe("remote keyboard focus loss", () => { windowFocusedRef: { current: true }, hasKeyboardFocusRef: { current: true }, sessionProtocolRef: { current: "vnc" }, + systemKeysRef: { current: vi.fn() }, remoteKeysym, isToggleKey, }; @@ -91,6 +92,8 @@ describe("remote keyboard focus loss", () => { [...keys].sort((a, b) => a - b).map((key) => [0, key]), ); expect(Object.keys(keyboard.pressed)).toEqual([]); + // The Windows keys go back to the local system with the focus. + expect(state.systemKeysRef.current.mock.calls).toEqual([[true], [false]]); expect(keyboard.onkeydown).toBeNull(); expect(keyboard.onkeyup).toBeNull(); keyboard.press(0x6c); @@ -137,6 +140,7 @@ describe("remote keyboard on a Mac", () => { windowFocusedRef: { current: true }, hasKeyboardFocusRef: { current: true }, sessionProtocolRef: { current: protocol }, + systemKeysRef: { current: vi.fn() }, remoteKeysym, isToggleKey, }); @@ -182,6 +186,7 @@ describe("Korean toggle keys with the real keyboard", () => { windowFocusedRef: { current: true }, hasKeyboardFocusRef: { current: true }, sessionProtocolRef: { current: "rdp" }, + systemKeysRef: { current: vi.fn() }, remoteKeysym, isToggleKey, }; diff --git a/tests/frontend/guacamole-meta-key.test.ts b/tests/frontend/guacamole-meta-key.test.ts index 24d1738..783811d 100644 --- a/tests/frontend/guacamole-meta-key.test.ts +++ b/tests/frontend/guacamole-meta-key.test.ts @@ -1,8 +1,9 @@ -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import { detectMetaKeyFamily, metaKeyLabels, remoteKeysym, + systemKeyLock, watchRightAlt, } from "../../src/frontend/guacamole-meta-key.js"; @@ -179,3 +180,34 @@ describe("Option on an ARD host", () => { stop(); }); }); + +describe("systemKeyLock", () => { + it("claims the Windows keys once and gives them back once", () => { + const keyboard = { + lock: vi.fn(() => Promise.resolve()), + unlock: vi.fn(), + }; + const set = systemKeyLock(keyboard); + set(true); + set(true); + expect(keyboard.lock).toHaveBeenCalledTimes(1); + expect(keyboard.lock).toHaveBeenCalledWith(["MetaLeft", "MetaRight"]); + set(false); + set(false); + expect(keyboard.unlock).toHaveBeenCalledTimes(1); + }); + + it("is harmless where the browser has no keyboard lock", () => { + const set = systemKeyLock(undefined); + expect(() => { + set(true); + set(false); + }).not.toThrow(); + }); + + it("ignores a refused lock", async () => { + const set = systemKeyLock({ lock: () => Promise.reject(new Error("no")) }); + set(true); + await Promise.resolve(); + }); +});