scrollback-reflow-standalone

Description

A standalone scrollback and reflow implementation for st that integrates history storage, mouse scrolling, selection handling, and resize reflow into a single cohesive patch.

st does not provide scrollback by default. This patch adds scrollback support by modifying resize and screen buffer handling. It is intended as an alternative design, not as a patch stack to be combined with other scrollback-related patches.

Two variants are provided:

Normal: scrollback, reflow, mouse and keyboard scrolling, and screen-bound selection.
Extended: identical to the basic variant, but with persistent selection that remains valid even when scrolled outside the visible screen.

Why another scrollback patch?

One patch is easier to handle than many.

Existing scrollback patches for st typically address individual features in isolation (history storage, mouse scrolling, resize behavior, or selection). When combined, these patches often interact in subtle ways, particularly during terminal resize operations.

This patch explores a unified approach where scrollback storage, rendering, selection, and resize handling are driven through a single abstraction. By routing all visible content through the same view layer, it avoids common issues such as selection drift, incorrect wrapping after resize, and conflicting mouse behavior.

The goal is not to replace existing solutions, but to provide a standalone alternative that emphasizes correctness and predictable behavior.

Key Features

Ring buffer scrollback with O(1) insertion
Text reflow on resize (O(N) in scrollback size)
Mouse wheel and touchpad scrolling
Keyboard scrolling via Shift + PageUp/PageDown and Shift + Home/End
Altscreen-aware mouse handling (applications such as vim and tmux receive mouse events when requested)
Cursor hidden while viewing scrollback history
Stable selection while scrolling
Optional persistent selection (extended variant)

Resize Reflow

When the terminal width changes, scrollback content is reflowed to match the new column width. Wrapped lines are flattened and rewrapped so that text is neither clipped nor lost when shrinking the window.

To reduce overhead, reflow is skipped when it is not required.

Which patch should I choose?

Choose the extended variant if you prefer selection behavior similar to most modern terminal emulators, where a selection remains valid even when scrolled outside the visible screen. Be mindful that this might interact poorly with more patches than the basic version.

Choose the basic variant if you prefer st’s traditional selection behavior, where selection is limited to the visible screen, or if you plan to combine this patch with other modifications that interact with selection logic.

Patch Compatibility

This patch modifies tresize() and related resize handling to support scrollback reflow and history preservation across window size changes.

As a result, it is not intended to be combined with other scrollback patches or patches that modify tresize() or rely on its stock side effects. It should be treated as a standalone scrollback implementation.

Patches that do not modify scrollback or resize behavior (e.g. transparency, clipboard helpers, key bindings) are generally easier to integrate.

The extended variant relaxes certain selection bounds checks to allow selection to persist outside the visible screen. This may interact poorly with patches that make assumptions about screen-local selection coordinates.

Notes & Caveats

Selection behavior
- In the Normal variant, selection is tied to visible screen coordinates. If a selection is scrolled completely off-screen, it is cleared.
- In the extended variant, selection persists even when scrolled outside the visible screen.
Shell prompt artifacts When resizing to very narrow widths, shell prompts may briefly appear duplicated or "ghosted". This is normal behavior caused by the shell reacting to SIGWINCH while st simultaneously reflows historical content.

Configuration

Scrollback size: configurable via scrollback_lines in config.h (default: 5000).
Key bindings: defaults to MouseWheel, Shift + PageUp/PageDown, and Shift + Home/End.

Example

The following example demonstrates resize reflow using a single line of colored blocks:

`sh for i in {41..46}; do printf "\e[${i}m "; done; echo -e "\e[0m"`

Wide terminal: color blocks appear on a single line.

Wide terminal with color blocks on one line

Narrow terminal: the original line is reflowed into multiple lines. No content is clipped or lost; only wrapping changes.

Narrow terminal with color blocks reflowed across multiple lines

Download

Author

Loshmi - nloshmi@gmail.com