Kitty keyboard protocol: should German (DE) AltGR+plus match Linux and macOS?

[mitchellh]

👋 Hello! A bug was just reported to Ghostty about our Kitty keyboard protocol not matching Kitty's behavior. I consider this a bug in every case as Kitty is the source of truth but in this case I also wanted to ask if perhaps the behavior in Kitty is incorrect as well.

The setup:

• Keyboard layout is German standard (DE)
• Physical keyboard is US standard (not sure if it matters but relevant to steps below)
• kitty +kitten show_key -m kitty
• Press (on US standard keyboard): Right Alt + ]
• kitty --version => 0.37.0

Output on macOS

alt+RIGHT_ALT PRESS 
CSI 57449 ; 3 u

alt++ PRESS ~
CSI 43 :  : 93 ; 3 ; 126 u
Alternate key: ] 

alt++ RELEASE 
CSI 43 :  : 93 ; 3 : 3 u
Alternate key: ] 

RIGHT_ALT RELEASE 
CSI 57449 ; 1 : 3 u

Output on Linux

ISO_LEVEL3_SHIFT PRESS 
CSI 57453 u

~ PRESS ~
CSI 126 :  : 93 ;  ; 126 u
Alternate key: ] 

~ RELEASE 
CSI 126 :  : 93 ; 1 : 3 u
Alternate key: ] 

ISO_LEVEL3_SHIFT RELEASE 
CSI 57453 ; 1 : 3 u

The Question

I don't think it's explicitly stated as such but I view one of the goals of the Kitty keyboard protocol as providing a consistent cross-platform key input API that masks the platform-specific quirks below.

In this case, TUI authors have to be aware of this potential quirk on input and in practice that is what has happened here (the issue reporter on Ghostty is a TUI author).

The question: should the right-alt+plus DE input match on both platforms?

I haven't researched the issue enough yet to know which "side" is better or what the proper encoding should be. I'll report back with more info as I dive into it, for now my focus is just on matching Kitty.

cc @rockorager @gpanders who expressed interest and provided feedback on this topic

[kovidgoyal]

While, in theory, abstracting platform differences would be nice, it's not practically possible. To do that you would need to specify the behavior of every key in every keyboard layout * every physical keyboard combination. Not to mention what would be the point since, the behavior of the same keys differs across layouts and TUI applications have no way to know which layout is active and even if they did, they are not going to maintain tables of keys in each layout anyway. Further, most platforms allow users to create custom layouts. The state of keyboard handling is generally a complete mess, I dont think we can successfully paper over that mess. This same issue affects cross platform GUI applications as well. So how do you propose cross platform differences be abstracted? Coming to the concrete issue you asked about. In Linux under the de keyboard layout AltGr (Right alt) + ] is defined to be ~ if terminals were to change that key to be alt++ to match macOS it would be very surprising to Linux de layout users. The terminal would no longer match the behavior of other applications on the system. This IMO is a bigger problem than cross platform behavior not matching. On Linux, German layout users expect to be able to press AltGr and ] to type ~ I am not sure but there maybe no other way to type ~ in that layout at all. The same applies to changing behavior on macOS to match Linux, in reverse.

[rockorager]

In Linux under the de keyboard layout AltGr (Right alt) + ] is defined to be ~

Both encodings are producing `~` as the text, but I am curious why Linux would report the key as `~` instead of `+`? The encoding I would have expected is: ``` CSI 43 : : 93 ; ; 126 u ``` or, depending on how you count the Iso Level 3 shift modifier ``` CSI 43 : : 93 ; 3 ; 126 u ``` That is, a `+` key, which on a US layout would have been a `]` key, with an alt modifier that produced `~` for text. That alt modifier seems odd to me, because this is actually an iso_level3_shift modified press, but we don't have a way to encode that - so I could see that one either way.

…

-- Tim

[kovidgoyal]

Run kitty with --debug-input and you will see the exact key events it receives from the OS. If you think those are being encoded incorrectly that would be a bug, but otherwise it's just a platform difference.

[kovidgoyal]

To be precise it will bebecause of some compose rule in the keyboard layout, you should see it reflected in the events as clean_sym vs compose_sym

[kovidgoyal]

And I looked at this quickly on my systems. The difference basically comes down to the fact that on Linux, right_alt is an "unknown" modifier ISO_Level_shift_3 in this layout while on macos it is a known modifier alt itself. The way kitty implements the spec is that unknown modifiers are absorbed into the key event so that the reported key is the key resulting from the action of any unknown modifiers + known modifiers. In this way it abstracts away the detail of unknown modifiers on linux from TUI applications. Otherwise the key event would have to be represented as ISO_Level3_Shift+plus on linux and alt+plus on macOS. Instead it is tilde on linux and alt+plus on macOS.

From a TUI application perspective, if a key event produces text, then you should treat it as a text input event not a shortcut. So on both platforms the kez event is basicallz a text inptu event with text of "~".

The platform differencs rear their ugly heads when there is more than one modifier. For example ctrl+right_alt+] will be ctrl+tilde on linux and ctrl+alt+plus on macOS. IMO the linux behavior is more "correct". The user expects right_alt+] to be tilde so adding ctrl to it should yield ctrl+tilde. However, because of limitations of macOS keyboard APIs I dont know of a good way to implement this in macOS if yu do, pointers are welcome.

[mitchellh]

(Sorry I posted a response but just deleted them. I want to do a bit more research here. I currently have COVID so there's some brain fog and I think my previous comments were premature and missing some important points)

[kovidgoyal]

Never used GTK (more of a Qt man myself) so cant comment on that. The actual "correct" (IMO) way to decode key events on Linux is to not use a toolkit each of which imposes its own ideas on top of the underlying data, but instead use libxkbcommon with the raw key events from either X11 or Wayland. This is the closest there is to a "standard" on Linux, and it will avoid you needing to have hacks like that list of chromium key mappings. Instead you can use the actual XF86 symbolic key names to map keys. But, regardless of library choice, the basic issue is that altgr+] is ~ under the DE layout. Therefore, for example, ctrl+altgr+] should be ctrl+~ not ctrl+plus. As an end user if I press a particular key on my keyboard and that key gives me ~ then I would expect ctrl+that key to give me ctrl+tilde, here that key is altgr+]. However, this is very much a matter of opinion, there is no single "correct" answer, or authoritative source that I know of. The question hinges on what one thinks altgr+key is, is it a modifier+key or is it a single "virtual" key. Sorry to hear about your COVID hope you recover quickly and fully from it. And please dont stress about this issue, unless you enjoy this sort of thing, it's very much a corner case and there is absolutely no rush in resolving it.

[kovidgoyal]

I should also emphasize before it gets lost in all the verbiage that the kitty on Linux behavior is what seems to me to be the correct behavior, for that platform. However, as I said this is a matter of opinion, and I am open to being convinced another way is better. The actual spec does not say anything on this subject so we can settle on an implementation that is the most sensible.

I have checked that Qt on Linux at least, maps altgr+] as just ~ without modifiers, not alt+plus, matching kitty's behavior. However it maps, ctrl+altgr+] as ctrl+alt+plus not ctrl+~ which IMO is completely inconsistent.

Adding shift to this is a whole other can of worms. shift+altgr+] is macron in both qt and kitty although kitty for some reason is not reporting the shifted key. That's probably a bug.

[neurocyte]

I think it's probably wrong to view this as a cross platform issue. The ISO german keyboard layout and the mac german keyboard layout are two very different things, defined by different people and standards and with very different goals. The most obvious difference is that the ISO german keyboard has only one Alt key and the mac german keyboard has two, but there are many other differences. I don't think it's possible, or even desirable, to get them to behave identically.

I might expect identical behaviour if a user was using an ISO german keyboard on macos, or a mac german keyboard on linux, but there is no expectation that different layouts produce the same input and that, I think, is independent of the OS in use.

[mitchellh]

The ISO german keyboard layout and the mac german keyboard layout are two very different things, defined by different people and standards and with very different goals.

Ah I actually wasn't even aware of this. This is a good point!