index.md (5170B)
1 scrollback-reflow-standalone 2 ============================ 3 4 Description 5 ----------- 6 A standalone scrollback and reflow implementation for st that integrates history 7 storage, mouse scrolling, selection handling, and resize reflow into a single 8 cohesive patch. 9 10 st does not provide scrollback by default. This patch adds scrollback support by 11 modifying resize and screen buffer handling. It is intended as an alternative 12 design, not as a patch stack to be combined with other scrollback-related 13 patches. 14 15 Two variants are provided: 16 17 * **Normal**: scrollback, reflow, mouse and keyboard scrolling, and screen-bound 18 selection. 19 * **Extended**: identical to the basic variant, but with persistent selection 20 that remains valid even when scrolled outside the visible screen. 21 22 #### Why another scrollback patch? 23 24 One patch is easier to handle than many. 25 26 Existing scrollback patches for st typically address individual features in 27 isolation (history storage, mouse scrolling, resize behavior, or selection). 28 When combined, these patches often interact in subtle ways, particularly during 29 terminal resize operations. 30 31 This patch explores a unified approach where scrollback storage, rendering, 32 selection, and resize handling are driven through a single abstraction. By 33 routing all visible content through the same view layer, it avoids common issues 34 such as selection drift, incorrect wrapping after resize, and conflicting mouse 35 behavior. 36 37 The goal is not to replace existing solutions, but to provide a standalone 38 alternative that emphasizes correctness and predictable behavior. 39 40 #### Key Features 41 42 * Ring buffer scrollback with O(1) insertion 43 * Text reflow on resize (O(N) in scrollback size) 44 * Mouse wheel and touchpad scrolling 45 * Keyboard scrolling via `Shift + PageUp/PageDown` and `Shift + Home/End` 46 * Altscreen-aware mouse handling (applications such as vim and tmux receive mouse 47 events when requested) 48 * Cursor hidden while viewing scrollback history 49 * Stable selection while scrolling 50 * Optional persistent selection (extended variant) 51 52 #### Resize Reflow 53 54 When the terminal width changes, scrollback content is reflowed to match the new 55 column width. Wrapped lines are flattened and rewrapped so that text is neither 56 clipped nor lost when shrinking the window. 57 58 To reduce overhead, reflow is skipped when it is not required. 59 60 #### Which patch should I choose? 61 62 Choose the **extended** variant if you prefer selection behavior similar to 63 most modern terminal emulators, where a selection remains valid even when 64 scrolled outside the visible screen. Be mindful that this might interact 65 poorly with more patches than the **basic** version. 66 67 Choose the **basic** variant if you prefer st’s traditional selection behavior, 68 where selection is limited to the visible screen, or if you plan to combine 69 this patch with other modifications that interact with selection logic. 70 71 #### Patch Compatibility 72 73 This patch modifies `tresize()` and related resize handling to support scrollback 74 reflow and history preservation across window size changes. 75 76 As a result, it is **not intended to be combined** with other scrollback patches 77 or patches that modify `tresize()` or rely on its stock side effects. It should 78 be treated as a standalone scrollback implementation. 79 80 Patches that do not modify scrollback or resize behavior (e.g. transparency, 81 clipboard helpers, key bindings) are generally easier to integrate. 82 83 The extended variant relaxes certain selection bounds checks to allow selection 84 to persist outside the visible screen. This may interact poorly with patches 85 that make assumptions about screen-local selection coordinates. 86 87 #### Notes & Caveats 88 89 * **Selection behavior** 90 * In the **Normal** variant, selection is tied to visible screen coordinates. 91 If a selection is scrolled completely off-screen, it is cleared. 92 * In the **extended** variant, selection persists even when scrolled outside 93 the visible screen. 94 95 * **Shell prompt artifacts** 96 When resizing to very narrow widths, shell prompts may briefly appear 97 duplicated or "ghosted". This is normal behavior caused by the shell reacting 98 to `SIGWINCH` while st simultaneously reflows historical content. 99 100 #### Configuration 101 102 * **Scrollback size:** configurable via `scrollback_lines` in `config.h` 103 (default: 5000). 104 105 * **Key bindings:** defaults to `MouseWheel`, `Shift + PageUp/PageDown`, and 106 `Shift + Home/End`. 107 108 #### Example 109 110 The following example demonstrates resize reflow using a single line of 111 colored blocks: 112 113 ```sh 114 for i in {41..46}; do printf "\e[${i}m "; done; echo -e "\e[0m" 115 ``` 116 117 **Wide terminal:** color blocks appear on a single line. 118 119  120 121 **Narrow terminal:** the original line is reflowed into multiple lines. 122 No content is clipped or lost; only wrapping changes. 123 124  125 126 Download 127 -------- 128 * [st-scrollback-reflow-standalone-0.9.3.diff](st-scrollback-reflow-standalone-0.9.3.diff) 129 * [st-scrollback-reflow-standalone-extended-0.9.3.diff](st-scrollback-reflow-standalone-extended-0.9.3.diff) 130 131 Author 132 ------ 133 * Loshmi - <nloshmi@gmail.com>