Option not to clear terminal when output height larger than the screen

[rafalglowacz]

Hi! I have a command that sometimes makes use of the entire screen width and height. I can limit the output by checking process.stdout.rows (and cols) but apparently I can't react quickly enough when the terminal size changes, for instance when using window splitting in Kitty. So inevitably I'm running into the issue described here:

#382 Terminal history cleared if output is greater than height of terminal window

The thing is that my command's users can live with a little defective output. I also compared it to docker compose pull which downloads Docker images for many services and it dynamically updates many lines with progress information. It tries to make sure everything fits on the screen, but if I resize its terminal window, it produces some borked output for a moment and then everything goes back to normal. The bad output stays there after the command is done, but it's not a big deal.

I tried commenting out the block where Ink clears the screen when outputHeight >= this.options.stdout.rows and it worked just like with Docker Compose, some glitches for a moment and then everything back to normal.

I think It's a valid use case for some applications and there could be an option to disable clearing scrollback at the cost of potential glitches (with a warning in the documentation). I'm not yet familiar with Ink's code, but if current contributors aren't too enthusiastic about this use case, I can work on it. Would you be interested in a PR, @vadimdemedes?

[Feuermurmel]

I also ran into this issue and had a bit of a think about how this could be solved. This is my idea/proposal. There's a table summarizing it at the bottom.

If there's interest in this approach, I'm happu to try to come up with a proof of concept (proably not within ink's implementation though).

---

The implementation would provide two modes of operation. There would need to be way for the application to select one mode (probably best before calling render()):

• default mode

  This mode is useful for applications that mostly handle like an interactive shell, displaying prompts and having some lines of dynamic output (think zsh with its interactive completions). Also for applications that display output where the dynamic part is constrained to the last few lines, with static output scrolling up (think docker pull, wget, jest).

• alternate screen mode

  This mode is useful for full-screen applications that want to take control of the full extent of the terminal window's output (think tmux, aptitude, vim).

The main changes to the current implementation:

• In default mode, UIs that aren't taller as the terminal window work as-is. But UIs that are taller get clipped to the terminal's height. The scrollback buffer does not need to be cleared. The idea is that an application either needs to work with the space it has, needs to be ok with the top part being clipped (e.g. because it is less important), or the user needs to make the window taller. It's a trade-off of course.

• In alternate screen mode, ink would switch to the alternate screen buffer, and enable mouse tracking (\x1b[?1000h). It would use mouse tracking to enable scrolling using the scroll wheel. The full UI could be accessed, no matter how tall it is. It would feel like the UI sits inside a pager like less.

There are some considerations necessary regarding static output:

• In default mode, static output works as-is, being added in front of the top of the UI. If the UI is clipped because it is too tall, static output would be added directly to the scrollback buffer.

• In alternate screen mode, static output is not visible by default. It is added to the main screen instead (1). When the application terminates and switches the terminal to the main screen, that output is now visible to the user, maybe as manifestation/summary of what the command did (think rm -v leaving a trace of which files exactly it deleted).

Terminating:

• In default mode, the process would simply exit. Everything stays visible as it is.
• In alternate screen mode, ink would switch to the main screen and exit. The UI would be hidden and any static output would become visible.

(1): This can't be done immediately and has to be buffered until the application terminates. Otherwise, terminals without support for Synchronized Output would experience severe flickering (but see useMainScreen() below).

Summary

	Current implementation	My proposal (default)	My Proposal (alternate screen)
UI taller than terminal window	Possible. Users can scroll into the scrollback buffer to see the top part of the UI.	Not possible. The top part of the UI gets clipped off.	Possible. The user can scroll to see the top part of UI.
Scrollback buffer access	Users can scroll into the scrollback buffer to see the output of previous commands, unless the UI is taller than the terminal window.	Users can always scroll into the scrollback buffer to see the output of previous commands.	Users cannot scroll into the scrollback buffer while the application is running.
Effect on scrollback buffer	The scrollback buffer is cleared if the UI is taller than the terminal window.	The scrollback buffer is not affected.	The scrollback buffer is not affected.
Static output (2)	Static output is visible in the main buffer and scrolled into the scrollback buffer.	Static output is visible in the main buffer and scrolled into the scrollback buffer.	Static output is not visible. It is added to the main buffer and scrolled into the scrollback buffer. (3)
Visibility of UI on exit	The UI and static output stay in the main screen and scrollback buffer as-is.	The visible part of the UI says stays in the main screen, and static output stays in the main screen and scrollback buffer. (4)	Switching back to the main screen hides the UI and reveals static output. (4)

(2): Output written via useStdout() and <Static>.

(3): An alternative would be to add static output to the top of the alternate screen and allowing the user to scroll into it. This would make the behavior equivalent to the current implementation while the application is running.

(4): An alternative would be to write a full copy of the UI into the main screen on exit. Then the behavior would be equivalent to the current implementation when the application exits.

Extensions

• useMainScreen(enable: boolean): This hook would be useful for an application that uses the alternate screen mode. When enabled, ink would switch to the main screen, allowing the application to use it to write "permanent" output temporarily.

  For example, aptitude is doing this while performing package installs. For the interactive UI, aptitude uses the alternate screen and is taking full control of it. But when calling into dpkg, where dpkg itself and install scripts it's calling usually produce some log output, aptitude switches to the main screen. aptitude's UI is hidden (which couldn't be used during these operations anyway), making that output visible and having it persisted in the scrollback buffer for inspection, even after aptitude has terminated.