Kitty Terminal Mouse Move Events Bug Outside Terminal Surface In Exclusive Focus Panel

Introduction

Hey guys! Today, we're diving into a fascinating issue reported in the Kitty terminal emulator, specifically concerning mouse move events when using a kitten panel with exclusive focus. This article will break down the bug, how to reproduce it, and the technical details surrounding it. If you're a developer or a regular Kitty user, you'll definitely find this insightful.

Understanding the Bug

The core issue revolves around mouse move events that occur outside the terminal surface when a kitten panel is running in exclusive focus mode. In simpler terms, when you have a Kitty panel set to grab all focus, the terminal should ideally capture all mouse movements, even those happening outside the visible terminal window. The bug, however, prevents these mouse move events from being correctly forwarded to the terminal application. While click-and-drag events outside the surface are correctly forwarded (including negative coordinates, which indicate the position is outside the window), regular mouse movements are not. This inconsistency poses a problem for applications that need to track mouse movement precisely, especially in scenarios like SGR Pixels mode, where accurate cursor positioning is crucial. For terminal applications that rely on precise mouse tracking, this bug can lead to unexpected behavior and a degraded user experience.

To elaborate further, let's consider why this is a significant issue. Many modern terminal applications are becoming increasingly sophisticated, offering features that go beyond simple text input and output. Some applications use the mouse for drawing, graphical interfaces, or even advanced text editing. In these cases, the ability to track mouse movement outside the terminal window can be essential. For instance, a drawing application might allow the user to start a stroke inside the terminal and continue it outside the window boundaries. Without proper forwarding of mouse move events, this becomes impossible. The problem lies in the fact that Kitty receives these events from the compositor (as confirmed by the --debug-input flag), but it fails to pass them on to the terminal application. This means the application is effectively blind to the mouse's movement outside the window, even though Kitty is aware of it. Click-and-drag events, which are forwarded correctly, provide a partial workaround, but they are not a substitute for continuous mouse tracking. The negative coordinates sent with click-and-drag events indicate the mouse position relative to the terminal window, even when the mouse is outside the window. This mechanism should ideally be extended to all mouse move events for consistency and functionality.

Reproducing the Issue: A Step-by-Step Guide

So, how can you see this bug in action? It's pretty straightforward, guys. Here’s a step-by-step guide to reproduce the behavior:

1. Run Kitten Panel with Exclusive Focus Policy: First, you need to launch a Kitty panel with the exclusive focus policy enabled. This setting ensures that the panel captures all input events.
2. Enable 1003 & 1016: Next, enable mouse tracking modes 1003 and 1016 within your terminal application. These modes are crucial for capturing detailed mouse events, including those with pixel-precise coordinates (1016).
3. Move the Mouse Outside the Kitty Terminal Surface (Without Clicking): Now, the key step: move your mouse cursor outside the boundaries of the Kitty terminal window without clicking any buttons.
4. Observe --debug-input: Use the --debug-input flag when launching Kitty. This will show you the raw input events Kitty receives from the compositor. You should see mouse position events being registered here, confirming that Kitty is indeed receiving the information.
5. Observe the Terminal Application: Here’s where the bug manifests. You'll notice that your terminal application does not receive these mouse move events. No negative coordinates or any other indication of the mouse's position outside the window are sent to the application.
6. Compare with Click-and-Drag Behavior: To highlight the inconsistency, try this: click outside the terminal window, and while holding the mouse button, move the cursor around. You’ll see that these click-and-drag events are forwarded, complete with negative coordinates. This demonstrates that Kitty can send mouse position information for events outside the window, but it's not doing so consistently for simple mouse movements.

By following these steps, you can clearly see the discrepancy between how Kitty handles regular mouse move events and click-and-drag events outside the terminal surface. This reproduction guide is essential for developers who want to investigate the issue further and work on a fix.

Environment Details: Setting the Stage

To provide a clear context, let's look at the environment in which this bug was observed. The following details outline the system configuration, Kitty version, and other relevant information:

• Kitty Version: 0.42.2
• Operating System: Linux (specifically, Arch Linux)
• Kernel: 6.12.38-1-lts
• Desktop Environment: Wayland (Hyprland v0.49.0)
• OpenGL: 4.6 (Core Profile) Mesa 25.1.5-arch1.1

Additionally, the configuration details include the fonts used, loaded configuration files, and color scheme. Here are some key configuration options that are different from the 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 ''}

The color scheme details provide the specific color codes used for various elements like the background, foreground, cursor, and tabs. Knowing the color scheme can be relevant if the bug were related to visual rendering, but in this case, it's less likely to be a factor. The crucial environment variables seen by the Kitty process include PATH, LANG, SHELL, DISPLAY, WAYLAND_DISPLAY, and various XDG_* variables. These variables define the runtime environment and can sometimes influence the behavior of applications. For instance, the WAYLAND_DISPLAY variable indicates that Kitty is running under Wayland, which is a modern display server protocol. The specific version of Hyprland (v0.49.0) is also important, as it helps narrow down the potential interactions between Kitty and the window compositor. The OpenGL version and Mesa drivers are relevant for graphics rendering, and while not directly related to input handling, they provide a complete picture of the system's graphics capabilities. Understanding these environment details is essential for anyone attempting to reproduce the bug or investigate its root cause. The configuration options different from defaults, especially those related to fonts and tabs, might indirectly influence the behavior of Kitty, although they are unlikely to be the primary cause of the mouse event issue.

Visual Evidence: Screenshots

A picture is worth a thousand words, right? A screenshot is provided to visually demonstrate the issue. While the screenshot itself might not directly show the missing mouse move events, it provides context about the terminal setup and the environment in which the bug occurs. It helps to visualize the scenario and understand the layout of the Kitty panel and the surrounding desktop environment. Visual evidence is always helpful in bug reports as it provides a quick and clear understanding of the problem for anyone looking into it.

Additional Context and Next Steps

To further troubleshoot the issue, it's recommended to try reproducing the problem with kitty --config NONE. This command launches Kitty with a minimal configuration, eliminating any potential interference from custom settings. If the bug disappears with the default configuration, it suggests that a specific option in the user's kitty.conf file might be the culprit. In such cases, posting a minimal kitty.conf that reproduces the problem is crucial for further investigation. If the problem involves interaction with another terminal program, providing a minimal configuration for that program is also essential. This helps to isolate the issue and determine whether it's a bug in Kitty itself or a compatibility problem with another application. Guys, by providing these details, we can make it easier for the developers to understand and fix the bug.

Conclusion: Wrapping Up

In conclusion, the bug where mouse move events outside the terminal surface are not forwarded in exclusive focus Kitty panels is a significant issue that affects applications relying on precise mouse tracking. The inconsistency between handling regular mouse movements and click-and-drag events highlights a gap in the input event processing. By understanding the steps to reproduce the bug, the environment details, and the additional context, we can contribute to a more robust and user-friendly Kitty terminal emulator. The next steps would involve further investigation by the Kitty developers, potentially involving debugging the input event handling code and identifying the reason why mouse move events are not being forwarded consistently. A fix for this bug would enhance the functionality of Kitty and improve the user experience for applications that require accurate mouse tracking capabilities.

So, there you have it! A deep dive into the mouse move event bug in Kitty. Stay tuned for more updates and discussions on terminal emulation and related topics!