VNOX-Client/docs/maintenance/clipboard-wayland.md
loki5512344 f04691c3cd
chore(client): checkpoint deployed features and unfinished server management
User requested a checkpoint and stopped all agents. Deployed artifacts remain the last verified releases; unfinished settings/categories/forums are preserved as WIP. See TODO/roadmap for verification and remaining release/updater work.
2026-11-01 15:31:21 +01:00

69 lines
3.3 KiB
Markdown

# Clipboard shortcuts on Linux/Wayland
## Diagnosis (2026-11-01)
The reported failure follows the active keyboard layout: English Ctrl+V
works; Russian Ctrl+V fails in every Slint input. Slint 1.18.1's
`InternalKeyEvent::shortcut()` recognizes the literal Latin `v`. Winit sends
the Russian logical character `м`, with physical `KeyV`, and the backend
previously forwarded that character unchanged. Clipboard initialization is
not the cause of this layout-specific failure.
The vendored winit backend now translates standard Ctrl shortcuts to Latin
letters using physical key positions only when the logical letter is
non-ASCII. Latin logical letters remain authoritative for AZERTY/Dvorak.
Regular Cyrillic input and Alt/Meta combinations retain their original text.
AltGr is tracked separately from Winit's Alt flag because Linux commonly
uses XKB Mod5 for it. Ctrl+AltGr key sequences therefore keep their text too.
If focus is acquired with AltGr already held and no AltGraph key event is
delivered, the aggregate modifier notification cannot identify Mod5; release
and press AltGr again in that case.
The backend also reconciles Wayland modifier notifications: virtual keyboards
and focus changes can supply modifier state without individual Ctrl events.
Previously `wtype -M ctrl -k v -m ctrl` inserted a plain `v` for this reason.
Native clipboard access already uses arboard with `wayland-data-control`.
Both the installed October 25 binary and the current build contain the
arboard/Wayland clipboard backend; the installed binary predates this
keyboard-layout fix.
References:
- [Winit key-event documentation](https://docs.rs/winit/latest/winit/event/struct.KeyEvent.html)
distinguishes logical characters from layout-independent physical keys.
- [Arboard Linux backend documentation](https://docs.rs/crate/arboard/latest)
explains the required `wayland-data-control` feature.
- [Slint shortcut implementation at v1.18.1](https://github.com/slint-ui/slint/blob/v1.18.1/internal/core/input.rs)
matches Latin letters for standard shortcuts.
## Verification
Run policy regression tests with:
```sh
cargo test --test clipboard_shortcuts --no-default-features
```
For a native GUI check:
```sh
VNOX_CLIPBOARD_EXPECT=vnox-probe cargo run --example clipboard_probe
```
Copy `vnox-probe`, then paste with Ctrl+V in the ordinary, password, and
multiline fields (Tab moves between them). Repeat with English and Russian
keyboard layouts. Output reports field, character count, and equality only;
it never prints pasted text. Also check Ctrl+A/C/X/V in the ordinary field,
and ordinary Cyrillic typing without Ctrl.
The automated workstation check used a separate temporary evdev keyboard,
with its own English/Russian layout selection, on real Hyprland/Wayland.
All three field types received the expected system clipboard text. Russian
Ctrl+A/C/X/V and ordinary Cyrillic input were checked through real key events.
English physical Ctrl+V and virtual-keyboard Ctrl+V were also checked.
The user's original clipboard was retained privately in process and restored;
their physical keyboard layouts were not changed.
Shift+Insert is not a standard paste shortcut in Slint 1.18.1's native
shortcut matcher; use Ctrl+V. This patch keeps clipboard handling in Slint's
backend and does not add application-wide paste interception.