Kitty Terminal Bug Report Mouse Move Events Outside Terminal Surface Not Forwarded
Hey guys! Let's dive into a quirky bug report about kitty, the GPU-based terminal emulator that we all love. This issue revolves around mouse move events when using kitten panels with exclusive focus. It's a bit technical, but I'll break it down in a way that's super easy to grasp. So, let’s get started and figure out what's going on!
Describe the Bug
Alright, so here's the deal. When you're running a kitten panel in kitty with the exclusive focus policy enabled, something weird happens with mouse movements. Basically, mouse move events that occur outside the terminal surface aren't being forwarded to the terminal application.
The Nitty-Gritty Details
To give you the specifics, the compositor (that's the thing managing your windows) is reporting these mouse movements to kitty. We know this because the --debug-input flag in kitty confirms it. But, for some reason, these events don't make it to the actual terminal application. It's like they're getting lost in translation somewhere.
Now, here’s where it gets even more interesting. If you click and drag your mouse outside the terminal surface, those events are correctly forwarded! The application even receives the negative coordinates, which is what you'd expect when the mouse is outside the window bounds. So, click-and-drag works fine, but simple mouse movements? Nope!
The Problem with SGR Pixels Mode
This inconsistency is a real pain, especially if you're using SGR Pixels mode in your terminal application. This mode allows applications to track mouse movement with pixel-level precision, which is super useful for things like drawing or advanced UI interactions. But, because these mouse move events outside the terminal aren't being forwarded, your application can't accurately track the mouse when it leaves the terminal window. This limits the functionality and responsiveness of applications relying on precise mouse tracking.
Why This Matters
Imagine you're using a drawing program in your terminal. You want to be able to click and drag to draw lines, even if your mouse cursor goes a little outside the window. With this bug, that becomes impossible. The application loses track of your mouse as soon as it leaves the terminal surface, making for a frustrating user experience. For developers and users who rely on this functionality, it’s a significant issue that needs addressing.
To Reproduce
Okay, let’s get into how you can actually see this bug in action. It’s pretty straightforward, and if you follow these steps, you’ll be able to reproduce the issue on your own system.
Step-by-Step Instructions
- Run kitten panel with exclusive focus policy and enable 1003 & 1016:
- First, you need to start a kitty terminal with a kitten panel. Make sure you’re using the exclusive focus policy. This is key to triggering the bug. Also, enable mouse reporting modes 1003 and 1016. These modes are what allow the terminal to receive detailed mouse event information, including mouse moves and clicks.
- Move the mouse outside the kitty terminal surface (without clicking):
- Now, here’s the crucial part. Simply move your mouse cursor outside the boundaries of the kitty terminal window. Don’t click anything yet; just move the mouse around.
- Observe that
--debug-inputshows mouse position events being received from the compositor:- Open another terminal and run kitty with the
--debug-inputflag. This will show you all the raw input events that kitty is receiving. You should see that the compositor (your window manager) is indeed sending mouse position events to kitty, even when the mouse is outside the terminal window.
- Open another terminal and run kitty with the
- Observe that the terminal application does not receive these mouse move events (no negative coordinates are sent):
- This is where you’ll see the bug in action. Despite kitty receiving the mouse move events from the compositor, the terminal application running inside kitty isn’t getting them. You won’t see any negative coordinates being sent to the application, which would indicate that the mouse is outside the window.
- Compare with click-and-drag behavior: click outside the terminal, then move the move, These events ARE forwarded with negative coordinates:
- Finally, try clicking and dragging your mouse outside the terminal window. You’ll notice that these events are forwarded to the terminal application, complete with the negative coordinates. This highlights the inconsistency: simple mouse moves are ignored, but click-and-drag events work as expected.
Why These Steps Matter
By following these steps, you can clearly see that the mouse move events are being received by kitty but not passed on to the application. This confirms that the issue lies within kitty’s handling of these events, specifically when using exclusive focus and mouse reporting modes. Reproducing the bug is the first step in getting it fixed, as it provides concrete evidence and a way for developers to investigate the problem directly.
Screenshots
Here's a screenshot that visually demonstrates the issue:
What the Screenshot Shows
The screenshot provides a clear visual representation of the bug. You can see the mouse cursor positioned outside the kitty terminal window, yet the application running inside isn’t receiving the mouse move events. This visual evidence helps to solidify the bug report and makes it easier for developers to understand the issue at a glance.
Environment Details
It's super important to provide detailed environment information when reporting a bug. This helps developers understand the context in which the bug is occurring and can aid in pinpointing the cause. Here are the details from the original bug report:
Key System Information
kitty 0.42.2 created by Kovid Goyal
Linux codelif 6.12.38-1-lts #1 SMP PREEMPT_DYNAMIC Mon, 14 Jul 2025 16:10:56 +0000 x86_64
S{PRETTY_NAME} 6.12.38-1-lts (/dev/tty)
[?12h [?25hDISTRIB_ID="Arch"
DISTRIB_RELEASE="rolling"
DISTRIB_DESCRIPTION="Arch Linux"
Running under: Wayland (Hyprland v0.49.0,) missing: blur icon
OpenGL: '4.6 (Core Profile) Mesa 25.1.5-arch1.1' Detected version: 4.6
Frozen: False
This section tells us:
- kitty version: 0.42.2
- Operating System: Arch Linux
- Kernel version: 6.12.38-1-lts
- Display Server: Wayland (using Hyprland v0.49.0)
- OpenGL version: 4.6 (Mesa 25.1.5-arch1.1)
Knowing the kitty version is crucial because it helps developers track down if the bug was introduced in a specific release. The OS and kernel versions provide insight into the system environment, and the display server (Wayland in this case) is particularly relevant for graphics-related bugs like this one.
Fonts and Paths
Fonts:
medium: SourceCodeVF-Regular: /usr/share/fonts/adobe-source-code-pro/SourceCodeVF-Upright.otf:196608
Features: ()
bold: SourceCodeVF-Semibold: /usr/share/fonts/adobe-source-code-pro/SourceCodeVF-Upright.otf:327680
Features: ()
italic: SourceCodeVF-Italic: /usr/share/fonts/adobe-source-code-pro/SourceCodeVF-Italic.otf:196608
Features: ()
bi: SourceCodeVF-SemiboldItalic: /usr/share/fonts/adobe-source-code-pro/SourceCodeVF-Italic.otf:327680
Features: ()
Paths:
kitty: /usr/bin/kitty
base dir: /usr/lib/kitty
extensions dir: /usr/lib/kitty/kitty
system shell: /usr/bin/zsh
This part gives us information about:
- Fonts: The fonts being used in kitty (SourceCodeVF family).
- Paths: The locations of the kitty executable, base directory, extensions directory, and system shell (zsh).
Font information can be relevant if the bug is related to text rendering or display issues. The paths help developers understand where kitty is installed and how it's being run.
Config Options and Colors
Config options different from defaults:
cursor_trail 3
font_family family="SourceCodeVF"
font_size 15.0
tab_bar_style powerline
tab_powerline_style slanted
tab_title_template {title}{' :{}:'.format(num_windows) if num_windows > 1 else ''}
Colors:
active_border_color #a48cf2
active_tab_background #04d1f9
active_tab_foreground #171928
background #171928
color0 #21222c
color1 #f9515d
color10 #69f8b3
color11 #f1fc79
color12 #a48cf2
color13 #fd92ce
color14 #66e4fd
color2 #37f499
color3 #e9f941
color4 #9071f4
color5 #f265b5
color6 #04d1f9
color7 #ebfafa
color8 #7081d0
color9 #f16c75
cursor #37f499
cursor_text_color #f8f8f2
foreground #ebfafa
inactive_border_color #171928
inactive_tab_background #323449
inactive_tab_foreground #37f499
mark1_background #f9515d
mark1_foreground #171928
selection_background #bf4f8e
selection_foreground #ebfafa
url_color #04d1f9
This section lists:
- Config options: Any kitty configuration options that are different from the defaults. This includes things like cursor trail, font family, font size, tab bar style, and tab title template.
- Colors: The color scheme being used in kitty. This includes colors for the background, foreground, cursor, tabs, and other UI elements.
Custom configuration options can sometimes be the cause of bugs, so it's helpful for developers to know which options are being used. The color scheme is less likely to be directly related to this particular bug, but it's still good information to have.
Important Environment Variables
Important environment variables seen by the kitty process:
PATH /opt/google-cloud-cli/bin:/usr/local/sbin:/usr/local/bin:/usr/bin:/usr/lib/emscripten:/home/harsh/.local/share/flatpak/exports/bin:/usr/lib/jvm/default/bin:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl
LANG en_US.UTF-8
SHELL /usr/bin/zsh
DISPLAY :0
WAYLAND_DISPLAY wayland-1
USER harsh
XCURSOR_SIZE 32
XDG_CONFIG_DIRS /etc/xdg
XDG_MENU_PREFIX hyprland-
XDG_BACKEND wayland
XDG_DATA_HOME /home/harsh/.local/share
XDG_CONFIG_HOME /home/harsh/.config
XDG_SEAT seat0
XDG_SESSION_DESKTOP Hyprland
XDG_SESSION_TYPE wayland
XDG_CURRENT_DESKTOP Hyprland
XDG_CACHE_HOME /home/harsh/.cache
XDG_SESSION_CLASS user
XDG_VTNR 1
XDG_SESSION_ID 1
XDG_STATE_HOME /home/harsh/.local/state
XDG_RUNTIME_DIR /run/user/1000
XDG_DATA_DIRS /home/harsh/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share:/usr/share
This section shows the environment variables that kitty sees when it's running. Key variables include:
- PATH: The list of directories where executable files are located.
- LANG: The language and locale settings.
- SHELL: The default shell being used (zsh).
- DISPLAY and WAYLAND_DISPLAY: Information about the display server (Wayland in this case).
- XDG variables: Various XDG (X Desktop Group) environment variables that define where configuration files, data files, and other resources are located.
Environment variables can sometimes influence how applications behave, so it's important to include them in a bug report. For example, the WAYLAND_DISPLAY variable confirms that kitty is running under Wayland, which is relevant to this bug.
Additional Context
To make sure the bug is reproducible and to narrow down the cause, it's often helpful to try reproducing it with a minimal configuration. This means running kitty with the --config NONE flag, which disables any custom configuration files. If the bug disappears when using the default configuration, it suggests that one of your custom settings might be the culprit.
Minimal Configuration
If you can't reproduce the bug with kitty --config NONE, the next step is to create a minimal kitty.conf file that still triggers the issue. This involves commenting out or removing sections of your configuration file until you're left with the smallest possible configuration that still causes the bug. This helps developers focus on the specific settings that might be interacting with the bug.
Interaction with Other Programs
If the bug involves interaction with another terminal program (like tmux or vim), it's also important to provide a minimal configuration for that program. This helps ensure that the bug can be reproduced consistently and that the interaction between kitty and the other program is well-understood.
Why This Matters
Providing additional context and minimal configurations helps developers quickly isolate the issue and reduces the amount of time they need to spend debugging. The more information you can provide, the better the chances of the bug being fixed promptly.
Summary
So, there you have it! A detailed look at a bug report about mouse move events in kitty. We covered the bug itself, how to reproduce it, the environment details, and the importance of providing additional context. By understanding these elements, you can write effective bug reports and help developers squash those pesky issues. Keep an eye out for updates on this bug, and happy terminal-ing!