How to handle keyboard events in gnome shell extensions?

How can I add an event or other method to listen to keypresses on a gnome shell extension? e.g. show a dialog with each key press showing the pressed key?

I can not find any example. The documentation mentions a keyboard module, but with that common name searching is hard.

Class explanation
...
- General utils
   - Keyboard: Manage and define the keyboard events, etc. for gnome shell.

(read above as a quote from the docs linked above. it is styled as code because the quote styling for some reason do not preserve line breaks in this site)

I found some extensions using the bellow code for results similar to what i'm asking, but i, again, failed to find docs for the specific classes and methods:

workViewInjections['_init'] = injectToFunction(WorkspacesView.WorkspacesView.prototype, '_init', function(width, height, x, y, workspaces) {
        this._pickWorkspace = false;
        this._pickWindow = false;
        this._keyPressEventId = global.stage.connect('key-press-event', Lang.bind(this, this._onKeyPress));                                                                                
        this._keyReleaseEventId = global.stage.connect('key-release-event', Lang.bind(this, this._onKeyRelease));
        connectedSignals.push({ obj: global.stage, id: this._keyPressEventId });
        connectedSignals.push({ obj: global.stage, id: this._keyReleaseEventId });
        });

Also, no class named keyboard anywhere there...

edit1: more searching... i think i may have to use the Clutter api. but again, not much examples or documentation for that. farthest i went was this

edit2: more searching. looking on the gnome shell source code, on the main ui tree, i think the answer is to use the barelly mentioned global object that is available to the extension code. e.g.

global.connect('key-press-event', function(if, i, know, the, signature){} );

I came across this snippet in gcampax's gtk-js-app template some time ago, which may be related to what you're doing:

// Due to limitations of gobject-introspection wrt GdkEvent and GdkEventKey,
// this needs to be a signal handler
this.connect('key-press-event', Lang.bind(this, this._handleKeyPress));

and

_handleKeyPress: function(self, event) {
    return this.main_search_bar.handle_event(event);
},

I haven't had a need to use keyboard events yet, and this is Gtk in GJS, but the same limitation may be affecting gnome-shell extensions.

UPDATE

I've been doing some keybinding stuff lately, and if attaching a signal handler to the global object is working, you can do something like this:

global.display.connect("key-press-event", (widget, event, user_data) => {
    let [success, keyval] = event.get_keyval(); // integer
    let keyname = Gdk.keyval_name(keyval); // string keyname

    if (keyname === "Control_L") {
        // Dialog code or eg. this.keys_array.push("<Ctrl>");
    }
});

There's also some Shell keybinding code here and some shell-global documentation here that might give you more clues. Wish I could help more but I'm wrestling my own GJS atm ;)

ADDENDUM

There is a good answer here with an example class with informative logging, as well as a speculative explanation. I've also found this functionality is exposed over DBus which might be more convenient in some cases:

Bus Name: org.gnome.Shell -> Path: /org/gnome/Shell -> Interface: org.gnome.Shell

Relevant Methods: