GUACAMOLE-2229: Add meta-to-ctrl connection option for browser sessions (RDP/VNC/SSH).

[bbennett-ks]

Summary

Adds a framework for connection parameters that control browser-side client behavior, separate from protocol-specific server parameters. The framework retrieves connection configuration when a client is focused and bradcasts events to configure JavaScript components accordingly.

This framework is used to introduce a meta-to-ctrl parameter for RDP, SSH, and VNC connections. When enabled, Meta (e.g., Command on macOS) keys are translated to Ctrl keys in the browser client, allowing macOS users to use familiar Ctrl-based shortcuts (Ctrl+C, Ctrl+V, Ctrl+F, etc.) via the Meta key when connecting to remote systems (e.g., Windows or Linux) that expect Ctrl-based shortcuts.

This feature defaults to false for backward compatibility.

Only English translations are included. Internationalization support for additional languages will be added in a separate Jira issue (GUACAMOLE-2230).

Besides reviewing the fix, we should also review the “feature” itself.

The goal is to help Mac users that RDP/VNC to Windows/Linux systems. Many of the most commonly used Command or Command+Shift shortcuts translate directly to Windows and Linux Ctrl or Ctrl+Shift shortcuts.

• Ctrl+C/Ctrl+X/Ctrl+V: copy/cut/paste
• Ctrl+Z/Ctrl+Shift+Z: undo/redo
• Ctrl+A: select all
• Ctrl+S: save
• Ctrl+F: find
• Ctrl+N: new window/document
• Ctrl+O: open
• Ctrl+P: print
• Ctrl+W: close tab/window
• Ctrl+Tab/Ctrl+Shift+Tab: next/previous tab

However, many do not, particularly those involving alt or function keys which often have no direct macOS equivalent or behave differently.

So having the option to treat Command (Meta) as Ctrl provides value for macOS users. However, it does introduce code complexity. Meta->Ctrl is relatively straightforward, but Meta+Shift->Ctrl+Shift adds significant complexity.

Treating Command (Meta) as Ctrl is relatively straightforward, but treating Command+Shift (Meta+Shift) as Ctrl+Shift introduces significant complexity, primarily because of the browser and OS handling of Meta events which Keyboard.js must explicitly compensate for.

[bbennett-ks]

This change is dependent on #1164. Instead of fixing this to work without the change, waitinh until #1164 is merged.

[bbennett-ks]

I have other fixes ready but want to wait 'til #1164 and #1155 are merged.

[mike-jumper]

I have a few issues with this:

1. A flag like metaToCtrl feels too specific for the core library.

   I wouldn't be against some sort of broader keysym filtering callback, though I'm not sure I see the need to perform filtering directly within Guacamole.Keyboard vs. making the decision in the webapp implementation of the key event handler.

2. This will cause problems for SSH/telnet (such as the mismatch between Cmd+C and Ctrl+C behavior noted below).

3. While this would improve the user experience for Mac users for many common keyboard shortcuts, there is no guarantee that Cmd+Something and Ctrl+Something map to the same operation. For example:

   • Firefox for Mac: Cmd+J opens the "Downloads" window.

     Firefox for Linux: Ctrl+J focuses the URL/search bar.

   • Terminal emulators on Mac: Cmd+C copies the current selection.

     Terminal emulators on Linux: Ctrl+C sends SIGINT, terminating the running process.

The potential mismatch between expected and actual behavior is the main reason this hasn't been done within Guacamole thus far.

It could make sense to provide this as a connection parameter specifically for VNC and RDP... but:

I think a far better approach would be to find some means of differentiating between Cmd on a Mac and Meta on a non-Mac. We'd then be able to handle these events based on the user's expectations, which aligns with guac's general design around prioritizing key identity (keysym) over location (scancode), without requiring any manual configuration.