Scroll Jitter (some notes)

[1dancook]

For investigating jitter with mouse scrolling, I made a small textual application to log to the screen what is happening with mouse scrolling.

It could be difficult to determine where the problem lies, especially given several layers of interaction for the terminal (OS, emulator, multiplexer, terminal app).

Code

"""
Running the script and scrolling up or down with the mouse in the upper half of the screen will result in text printed to the log on the bottom half.

Any "scroll jitter" will be noticeable in the log--  a mixture of up/down rather than a stream of down or a stream of up.
"""

from textual.app import App
from textual.containers import VerticalScroll
from textual.widgets import RichLog

class TestScroll(App):

    def compose(self):
        yield VerticalScroll()
        yield RichLog()

    def on_mount(self):
        self.position = 0
        self.richlog = self.query_one("RichLog")
        self.richlog.write(f"start: {self.position}")

    def on_mouse_scroll_up(self, event):
        self.position += 1
        self.richlog.write(f"up   : {self.position}")

    def on_mouse_scroll_down(self, event):
        self.position -= 1 if self.position > 0 else 0
        self.richlog.write(f"down : {self.position}")

TestScroll().run()

Results:

Here are my findings with what I currently have available on my machine:

OS	Terminal Emulator	Multiplexer?	Jitter?
macOS	Kitty	tmux	Yes
macOS	Kitty	-	Yes
macOS	Terminal.app	tmux	No
macOS	Terminal.app	-	No

From the above it appears that scroll jitter is a problem with the terminal emulator rather than TMUX or Textual.

However, kitty does not seem to have scroll jitter problems with other applications (neovim, less, etc). They work as you would expect.

Things to look into

• does Kitty have the same issue on Linux?
• do any other terminal emulators have scroll jitter?
• why do other apps work in Kitty for scrolling, but a textual app has issues?
• are there any issues raised on kitty's repo about anything related to this?

[TomJGooding]

If you really wanted to investigate this, I suspect it would involve comparing escape sequences from different terminal emulators. I might be wrong but I wanted to give you a heads up as this is a real rabbit hole!

[1dancook]

Indeed, there are a number of things that I'm not aware of behind the scenes. I took a long stroll through Kitty GitHub issues from over the past five years and saw a recurring theme: scroll issues are likely not the fault of Kitty but in how the application is handling mouse events.

So there could be something there about how textual handles mouse events but at this point it's speculation at best.