Kitty Keyboard Protocol on Windows doesn't handle the `Escape` button properly

[NSPC911]

Have you checked closed issues? (https://github.com/Textualize/textual/issues?q=is%3Aissue+is%3Aclosed)

Yes

Have you checked against the most recent version of Textual? (https://pypi.org/search/?q=textual)

Yes

The bug

For simplicity's sake, I will reference KKP to Kitty Keyboard Protocol

If you enable the KKP on something like Wezterm, you need to send any event to force the escape key to be registered.

2025-11-25_23-41-12.mp4

This is such a genuinely weird bug that I had to pull out my git bisect to find the root cause, and it determined that the reason was that I bumped textual from 6.3.0 to 6.6.0, the release that added KKP for Windows.

However, this issue is a bit different on Rioterm, but I can't exactly properly test it, because Rio doesn't want to disable the KKP. However, the output value is a bit different

left: wezterm, right: rio

but the issue I showed in Wezterm? Doesn't exist on Rio. So, I'm not exactly sure what is going on here...

[github-actions]

We found the following entry in the FAQ which you may find helpful:

• How do I center a widget in a screen?

Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.

This project is developed and maintained by Will McGugan. Consider sponsoring Will's work on this project (and others).

This is an automated reply, generated by FAQtory

[NSPC911]

This issue is most likely a child of #6192

[NSPC911]

Upon further investigation, the reason why Rio behaves strangely is that it is based on Alacritty, which uses its own method to handle keyboard inputs, hence why KKP being enabled and disabled made no difference. So this seems like something with Wezterm as of now, until Windows Terminal does something

[TomJGooding]

Can I just confirm to ensure I've understood correctly: is this problem with esc only in Wezterm? But you've checked other terminals that support the kitty keyboard (kitty, ghostty, alacritty, rio, etc) and those seem to work as expected?

[TomJGooding]

I can't reproduce this after installing Wezterm on Windows. This is with a fresh install after configuring with wezterm --config enable_kitty_keyboard=true.

When running textual keys, pressing esc just works as expected. The kitty keyboard is definitely enabled as alt+j also works.

[NSPC911]

But you've checked other terminals that support the kitty keyboard (kitty, ghostty, alacritty, rio, etc) and those seem to work as expected?

well ghostty and kitty arent supported on windows

I can't reproduce this after installing Wezterm on Windows. This is with a fresh install after configuring with wezterm --config enable_kitty_keyboard=true.

When running textual keys, pressing esc just works as expected. The kitty keyboard is definitely enabled as alt+j also works.

that's weird.

textual diagnose

Textual Diagnostics

Versions

Name	Value
Textual	6.6.0
Rich	14.2.0

Python

Name	Value
Version	3.13.9
Implementation	CPython
Compiler	MSC v.1944 64 bit (AMD64)
Executable	C:\Users\notso\Git\NSPC911\rovr.venv\Scripts\python.exe

Operating System

Name	Value
System	Windows
Release	11
Version	10.0.26200

Terminal

Name	Value
Terminal Application	WezTerm (20251025-070338-b6e75fd7)
TERM	xterm-256color
COLORTERM	truecolor
FORCE_COLOR	Not set
NO_COLOR	Not set

Rich Console options

Name	Value
size	width=187, height=47
legacy_windows	True
min_width	1
max_width	187
is_terminal	False
encoding	cp1252
max_height	47
justify	None
overflow	None
no_wrap	False
highlight	None
markup	None
height	None

[TomJGooding]

Are you running a nightly version of Wezterm? The latest version I installed is wezterm 20240203-110809-5046fc22.

[NSPC911]

Are you running a nightly version of Wezterm?

yes, I'm running a nightly version of wezterm

[TomJGooding]

Thanks, I can reproduce this with the nightly version of WezTerm on Windows.

It looks like this might be a bug in WezTerm. According to the spec for the kitty keyboard protocol:

Turning on this flag will cause the terminal to report the Esc, [...], keys using CSI u sequences instead of legacy ones.

Pressing the esc should send CSI 27 u in this mode, but it looks like WezTerm is instead sending \x1b. I had a quick look at the WezTerm repo and there's already some outstanding PRs related to this.

I'm still not sure exactly why I can only reproduce this on nightly version on Windows, but not on Linux. I haven't dived into the code to understand exactly what in the key handling is causing esc to queue up until the next event.

[NSPC911]

Pressing the esc should send CSI 27 u in this mode, but it looks like WezTerm is instead sending \x1b.

That makes a lot of sense, given my initial screenshot. So there is nothing Textual can do, aside from waiting for wez to do something about it?

[TomJGooding]

Even if there was something Textual could do as a workaround, consider the work involved given this issue seems to only affect the nightly version of WezTerm on Windows.

[NSPC911]

So I should close this as not planned?