Support Wayland environments on Linux

[savetheclocktower]

Have you checked for existing feature requests?

• Completed

Summary

This library supports X11 environments on Linux (somewhat), but is not currently able to detect the proper keyboard layout in Wayland. But let's back up a bit, since this is the first issue on this repo and some folks maybe didn't even know it existed.

---

First of all: why does this library exist? For the reasons in this blog post.

Pulsar, like Atom before it, offers very powerful and nuanced interpretation of keystrokes. For instance: if a user types @, Pulsar’s interpretation of that keystroke may vary based on how the keyboard produced the character. Quoth the blog post:

Take for example the Swiss-German keyboard layout on macOS. If you want to type an @ character on that layout, you need to hold alt and press the g key.

And later:

We quickly discovered that the new DOM APIs weren’t enough. While the KeyboardEvent.key property accurately reports the typed character, it doesn’t tell us whether that character depends on the current combination of modifier keys. So, for example, if we see an event with a key property of @ and an altKey property of true, should we interpret it as alt-@ or @? If @ is a printed key on the current layout, we want to honor the modifier in the keystroke descriptor, but if the user was holding alt just to access the @ key, we don’t want to include the alt- modifier in the description.

It’s a bit of an outlier, but this is fair. If your keyboard layout requires you to press alt-g to make an @, then pressing alt-g could be interpreted as @, alt-g, or even alt-@, depending on your outlook. And what about ctrl-alt-g? Should that be interpreted as ctrl-@? ctrl-alt-g? ctrl-alt-@?

Someone might be tempted to write the following code to handle this scenario:

1. Inspecting the keyboard event, it would see a code property of KeyG, an altKey property of true, and a key property of @.
2. Since KeyG was pressed, the code would assume that, had alt not been pressed, the keyboard would’ve produced a g character.
3. On other platforms, it would typically interpret this as alt-g; but since we’re on macOS, there’s special logic that prevents “shadowing” of alt- modified keys that produce ASCII characters; so this would be interpreted as @.

But there’s a problem that the excerpted text hints at: despite what it looks like, you cannot assume that the KeyG key (a physical keyboard key) would’ve produced a g character when pressed. The KeyG code simply means “the place where G is on a QWERTY keyboard.”

Codes like KeyG and Digit1 describe physical keys in the positions typical of the vast majority of keyboards in use today. Their names correspond to QWERTY positioning and do not move around if the keyboard layout changes. For instance, a French-style AZERTY keyboard layout maps KeyQ to a and KeyW to z.

Luckily, there’s now an API in Chromium that allows us to know which character would’ve been typed had no modifiers been present:

let layoutMap = await navigator.keyboard.getLayoutMap();
layoutMap.get('KeyG'); // 'g'

This is a major step toward what we need. Does this mean we don’t have to write a bunch of native code to handle this now?

Not quite.

Challenges

In most cases, we only care about comparing the character that a keystroke produced (if any) to the one it would’ve produced without any modifiers.

When the shift key is involved, though, it’s trickier. Suppose we did ctrl+shift+alt+x:

• We’d look at the code produced by the event and compare it to what would’ve been produced by ctrl+shift+x.
• Are they equal? If so, alt didn’t change the character that was delivered to us, so we’ll preserve the modifier, since it wasn’t a necessary part of producing the character we reacted to.
• If they’re not equal, it means the user only pressed alt in order to produce the character we reacted to, so it’s not something we should treat as a modifier.

As far as I can tell, the KeyboardLayoutMap API can’t do stuff like this; it can only tell us which key would’ve been produced had a button been pressed with no modifiers. The use case is mainly for gaming; you want to be able to tell a user, e.g., which keys correspond to the standard WASD layout. (On an AZERTY keyboard, the same keys would spell out ZQSD.)

So we still need a way to loop through all keys present on the keyboard and ask the OS what character, if any, would be produced if we pressed that key…

• …on its own.
• …with Shift pressed.
• …with AltGraph pressed.
• …with Shift and AltGraph pressed.

Wayland support on Linux

The crucial failing here is that our current keyboard-handling code on Linux presumes an X11 environment, so the associated APIs fall down when we’re on Wayland.

We could migrate entirely to libxkbcommon, or we could add a new code path for Wayland environments and leave the current X11-specific code in its own branch. Sadly, my early experiments with the libxkbcommon API have not been incredibly fruitful.

If Claude is to be believed — a pretty big if — the techniques we use to spy on the current input mechanism in X11 don’t have direct equivalents in Wayland. To my increasing disbelief, I am having trouble finding a way to ask a question like “which keymap is the current user typing with right now?” in imperative fashion. The techniques I’ve found outside of Claude for this sort of thing seem to involve reimplementing a nontrivial portion of the Wayland protocol itself along with libxkbcommon and listening for, e.g., keymap events.

The upside of this is that it would allow keyboard-layout to subscribe to keymap layout switches on Linux, a feature it’s never had before. The downside is how complex it is and how ill-equipped I feel to write it.

Conclusions

I’ll throw myself against a brick wall for a little while. Meanwhile, the new KeyboardLayoutMap API in the browser is huge, even though it’s not 100% of what we want. At some point I’ll probably play around with it so I can get a sense of how much functionality we’d be giving up if we had only KeyboardLayoutMap to fall back on. (Not easy to tell at a glance; amazingly, for how much code has been written to avoid this problem, there aren’t a lot of specs documenting how this should behave.)

What benefits does this feature provide?

Preserves the status quo for Linux users; prevents users of non-US keyboard layouts from having their keystrokes misinterpreted.

Any alternatives?

Yes, as explained above:

• The KeyboardLayoutMap API in the browser
• It seems a bit batty, but wayland-client is a pure-JS implementation of a Wayland client. It's got types like wl_keyboard that seem to contain keymap metadata. It would be hard to use this alongside native code, but maybe it can be used as a sanity check, or as a way of iterating more quickly, or as a spec helper.

Other examples:

No response

[savetheclocktower]

Largely good news to report.

With the help of Claude and a healthy amount of patience and skepticism, I’ve managed to get to the point where I can get both a keymap and a human-readable description of the current keyboard layout. This would bring us to feature parity with the X11 approach.

The techinque

• Create a Wayland “display” via wl_display_connect
• Create an xkb_context
• Create a wayland “registry” so that we can add a “seat”
• Once we have a seat, we can obtain a keyboard
• Once we bind to a keyboard, we get a keymap event that we can feed to libxkbcommon.
• Once that happens, we have what we need (more or less) to interpret keys for a hypothetical keyboard.

This is confusing

Frustratingly, some amount of what happens between GNOME and Wayland appears to be treated as nobody else’s business.

Here’s what I can ascertain:

• I can go into GNOME’s keyboard layout settings and reorder the input sources.
• Whatever I drag to the top of the list will be reported to keyboard-layout.
• Using that layout, we're able to discern which key characters are available when various modifiers are pressed.
• We're also able to get the human-readable name of that layout.

And yet:

• GNOME gives you a way to switch between “input sources” on the fly. For instance, you can press alt-space and switch from “English (US)” to “French (AZERTY).” But when you do that, Wayland doesn’t tell you that the keymap has changed! From its perspective, the keymap has not changed.
• This might be GNOME’s fault — or else they have a deep understanding of the Wayland spec and have decided this is the right thing to do here. (GNOME lets you have a different input source for each application if you opt into it, so it would get pretty chaotic in that scenario — the keymap would be constantly changing.)
• I’d be offended about this, but it’s not just us affected by it. I installed Chromium and tested the navigator.keyboard.getLayoutMap() API… and the same is true of it. No matter which input source is active for GNOME, the keyboard layout at the top of the list will be the one that Wayland considers to be active; if there were an easy way around this, I can only assume Chromium would've picked up on it before we did.
• So I think we can live with that as a constraint. You can type into Pulsar using whatever input source you want, but the one at the top of the keyboard layouts list will be the one we use to interpret your keypress data. (We could possibly have some sort of recovery behavior if some sanity checks fail — e.g., if the actual key reported by the keyboard event doesn’t agree with any of the values we expect — but I don’t think this is a big deal.)

Still to be resolved

AltGraph needs work

We’re able to ask “what would this key produce if we pressed it with these hypothetical modifiers active?” And we get back results that seem mostly correct on the surface.

But I haven’t seen any cases where the withAltGraph character differs from the unmodified character. Presumably there should be a few of these in AZERTY, including KeyE (KeyE + AltGr should produce €.) So those aren’t working quite yet.

KeyT is a good test character here for AZERTY; according to GNOME, it should produce four different characters in the four modifier modes:

• unmodified: t
• with Shift: T
• with AltGr: {
• with Shift+AltGr: ™

When that’s correct, we’ll be interpreting these keys correctly.

Evented interface

Since the emitting of keymaps is event-based, I figured it would be pretty easy to wire up onDidChangeCurrentKeyboardLayout — which so far has always been a no-op on Linux.

It’s not quite that easy, though, because it requires the periodic consuming of an event queue and the sending of wl_display_dispatch calls. I’m not trying to go multi-threaded unless explicitly invited to, and Claude seemed to indicate that’s not a great idea with Wayland, so I was easily persuaded to try scheduling work via libuv.

So far it’s not working right, but I’ll keep plugging away at it.

Wayland or X11?

I’ve played around with various techniques that Claude and the internet have told me about — techniques for discerning whether the user is running Wayland or X11. Some of them involve checking multiple environment variables and have the feel of really fuzzy heuristics.

Instead, I’m leaning toward assuming Wayland first, at least until an attempt to create a Wayland display. Failure to do so would demonstrate pretty clearly that this is not a Wayland environment — at which point we could try the X11 setup process instead.

Side effects?

Again, the weirdness of this abstraction makes me wonder if there are any side effects to this approach. I was a bit confused that I had to create a “display” to talk to Wayland, but I’m now reasonably sure that that’s just a term of art. And I think we’re binding to the existing “seat” (which Wikipedia describes as “a set of input/output devices”) rather than creating a new one.

Breadth of testing?

I’ve been testing on a VM of Ubuntu 25 in UTM (VMWare Fusion’s Wayland support barely existed) and can at least prove that all this stuff works with Ubuntu running GNOME on Wayland. Since Wayland is a protocol, I can’t assert that every Wayland server (as implemented by the window manager/environment) will behave the same way.

I suppose we’ll find out!

[savetheclocktower]

OK, I'm on the verge of declaring victory here.

The n-api-wayland branch of my fork has a lot of junky commits that need rebasing, but otherwise delivers better Wayland support than X11 support at this point. (onDidChangeCurrentKeyboardLayout works, plus getCurrentKeymap() includes information about AltGraph even when the X11 implementation doesn't.)

The main caveat is that I've only tested this on one Wayland implementation: Ubuntu/GNOME. I'm hoping that other window managers consume Wayland in similar fashion and that I'm not just relying on the conventions of one server.

I've tried very hard to be paranoid so that this package works exactly as it used to if Wayland is not present, and even if the associated libraries are not present. (The binding.gyp checks for the presence of libwayland-client and sets a compilation flag based on whether it's available.) Platform setup happens immediately after the library is required, and if anything goes wrong in the Wayland setup path, we fall through to the X11 path, so the defaults should be the same as they were before.

I've updated the updated-latest-electron branch on the Pulsar repo so that the next build of PulsarNext should have better support for non-QWERTY keyboards using Wayland. If I get good field reports, I'll either close this ticket or designate it for closing whenever we actually land these changes to pulsar-edit/keyboard-layout.