feat: add option that pauses autoscrolling while browsing term buf

[Run1e]

Hey!

Been using this fantastic plugin for well over a year and I decided to have a go at fixing my one gripe with it.

Currently if you go into normal mode and scroll up to read something that's been printed to your toggleterm, the autoscroll logic will yeet you back to the end of the buffer if any new lines get printed to the terminal. This is quite annoying if you're tailing a file or running the project you're working on and want to read something in peace while stuff is being printed. Your only real option at the moment is to disable autoscrolling, or to stop whatever is printing text to your terminal before you scroll up to read.

This simply makes it so that the autoscrolling logic only runs if your cursor is already at the bottom of the terminal. So if you scroll up you don't need to worry about the autoscroll logic. The logic kicks in again once your cursor is at the bottom of the terminal buffer again (like when pressing G).

I've created an option to enable this (conditional_auto_scroll) which is false by default, but I think most people would like this type of change so if applicable to merge the option could alternatively just be removed altogether.

[atimofeev]

I've tried this, and it works great for the described purpose, but this has also caused numerous issues with nvim_win_get_cursor stealing the event loop even outside of terminal.

I suggest applying this patch to have guardrails against that:

--- a/lua/toggleterm/terminal.lua
+++ b/lua/toggleterm/terminal.lua
@@ -385,8 +385,11 @@ function Terminal:__make_output_handler(handler)
     return function(...)
       if self.auto_scroll then
         if self.conditional_auto_scroll then
-          local cursor = vim.api.nvim_win_get_cursor(self.window)
-          if cursor[1] == vim.api.nvim_buf_line_count(self.bufnr) then self:scroll_bottom() end
+          if self.window and vim.api.nvim_win_is_valid(self.window) then
+            local cursor = vim.api.nvim_win_get_cursor(self.window)
+            if cursor[1] == vim.api.nvim_buf_line_count(self.bufnr) then self:scroll_bottom() end
+          end
+          -- if window is invalid (closed), skip autoscroll
         else
           self:scroll_bottom()
         end

Though there may be better approaches to handle this.

[Run1e]

I've tried this, and it works great for the described purpose, but this has also caused numerous issues with nvim_win_get_cursor stealing the event loop even outside of terminal.

Could you elaborate what issues you were seeing from it stealing the event loop? Not sure how that would manifest.

I saw some errors that happened when the window was hidden because I wasn't checking that the window existed. Seems the window check (and term buf check, for that matter) happen later in Terminal:scroll_bottom anyway, so I moved this logic there.

That function is also called when sending a command to a terminal, which isn't a feature I use so I'm not sure if you'd want conditional auto scrolling disabled if you send a command. I guess? If so maybe Terminal:scroll_bottom should have a force argument that bypasses the conditional auto scrolling.

[atimofeev]

The most obvious issue I've encountered is being unable to do key chords, if terminal updates fast enough with some wheel or progress bar. No matter if it's closed or open.

Example: while I had my pi-coding-agent running in toggleterm instance (fast ui redraws), I was unable to execute gg and other chord commands in text buffers.

This probably has other impact cases, which I haven't caught before applying the patch.

[atimofeev]

I've re-tested the changes with your latest commit and the issue seems to be resolved 👍