Add multi key overlay

[alek-sys]

Just exploring the idea for now, wondering what you think?

Similar to which-key in Emacs and other editors, this helps to navigate and discover multi-key mappings. Basically when you press first part of the multi-key sequence, it'll show a hints overlay with available follow-ups. Requires quite a bit of hacking on the boss.py level, so not sure how you feel about it? Don't think it is possible to do via a kitten, it can't really handle keys that well as far as understand.

Here is a little demo

kitty-multi-key-hint.mp4

PSA: not going to lie, I've used AI agents to draft the idea and navigate codebase. Obviously if you like the idea, happy to hand-polish the AI slop before merging.

Example (kitty.conf):

map ctrl+h>a <action a>
map ctrl+h>b <action b>
multi_key_hint_delay 600

When you hit ctrl+h and hesitate for 600ms, hints overlay will appear showing what's available:

a <action a>
b <action b>

Pressing a or b will activate the mapped action.

Modifiers are supported as well, i.e.

map ctrl+h>a <action a>
map ctrl+h>ctrl+a <action b>
map ctrl+h>shift+a <action c>

Will display:

a a <action a>
1 ctrl+a <action b>
A shift+a <action c>

1 here is because hints overlay requires a key, but there is nothing exactly matching ctrl, so it's a compromise.

Nested mappings are supported as well:

map ctrl+h>a>1 <action 1>
map ctrl+h>a>2 <action 2>

Will display two hints sequentially.

[alek-sys]

This text parsing is quite ugly, to be fair. But not sure what to do - introducing structured input is not an option because of backwards compatibility. Maybe just add hotkey "tags" to every options line, e.g. : option one <ctrl+1>?

[kovidgoyal]

In principle this is fine, you can easily introduce a new mode to the hints kitten so that when it sees customize_processing is choose_entry it processes STDIN as JSON data or whatever. I haven't looked at the code yet, as I am swamped for the next few days, but a couple of points off the top of my head:

1. Does it handle multi-level multi key mappings, such as a>b>c>d? What hint would be used for these? And they should probably have a multi-stage select?

2. There should be a line of text to start that tells the user they can press esc to abort

3. How is map --on-unknown handled?

[alek-sys]

In principle this is fine, you can easily introduce a new mode to the hints kitten so that when it sees customize_processing is choose_entry it processes STDIN as JSON data or whatever. I haven't looked at the code yet, as I am swamped for the next few days, but a couple of points off the top of my head:

Cool, I'll see what I can do with JSON without breaking the world.

1. Does it handle multi-level multi key mappings, such as a>b>c>d? What hint would be used for these? And they should probably have a multi-stage select?

Yes. Once you press a, it'll pop up with b, then with c, then with d. You can see a bit of a flash, when the previous hints overlay is hidden and new displayed, but it does work. I guess with JSON I can just pass the whole tree of potential mappings, and keep it within the kitten, so no need to hide/show when moving between levels.

2. There should be a line of text to start that tells the user they can press esc to abort

I'll add that.

3. How is map --on-unknown handled?

Didn't know about this, will have a look!