Fix stale rows when repainting in place while scrolled back

The terminal's update range is recorded in buffer.y space, relative to
yBase. updateDisplay turns it into an invalidation rect as if buffer row
y were screen row y, but drawTerminalContents maps screen rects back to
buffer rows through yDisp.

Those agree only while the viewport is pinned to the bottom. Scrolled
back by k rows, a change at buffer row y renders at screen row y + k
while the invalidation still covers screen row y, so the rows that
actually changed are never repainted and keep stale content until a
resize or another scroll forces a full redraw.

Scrolling output masks it, since scroll() dirties both scrollTop and
scrollBottom and the rowEnd == rows - 1 branch then invalidates the whole
view anyway. What stays exposed is in-place repainting, where the update
range remains a strict subset: scroll up a few lines while a TUI redraws
a status block and the visible rows stop tracking the buffer.

Invalidate the whole view when yDisp != yBase. The pinned case keeps the
existing partial rect untouched, including the restricted-region
extension from #582, and the draw still repaints only the rows
intersecting the dirty rect, each read from its correct yDisp-relative
line.

Author: evertjr

Sources/SwiftTerm/Apple/AppleTerminalView.swift

@@ -1844,25 +1844,41 @@ extension TerminalView {
 
         #if os(macOS)
         let baseLine = frame.height
-        var region = CGRect (x: 0,
+        var region: CGRect
+        // `rowStart`/`rowEnd` come from the terminal's update range, which is recorded
+        // in `buffer.y` space (relative to `yBase`, the live screen). The rect below
+        // maps them to the screen as if row `y` were screen row `y`, but
+        // drawTerminalContents maps screen rects back to buffer rows via `yDisp`.
+        // Those two agree only while the viewport is pinned to the bottom. Once the
+        // user scrolls back by `k` rows, the cells that changed are drawn at screen
+        // row `y - k` while the invalidation still covers screen row `y`, so the rows
+        // that actually changed are never repainted and keep stale pixels until
+        // something forces a full redraw. Invalidate everything in that case; the
+        // draw still only repaints rows intersecting the dirty rect and reads each
+        // from its correct `yDisp`-relative buffer line.
+        if terminal.displayBuffer.yDisp != terminal.displayBuffer.yBase {
+            region = CGRect (x: 0, y: 0, width: frame.width, height: frame.height)
+        } else {
+            region = CGRect (x: 0,
                              y: baseLine - (cellDimension.height + CGFloat(rowEnd) * cellDimension.height),
                              width: frame.width,
                              height: CGFloat(rowEnd-rowStart + 1) * cellDimension.height)
-        
-        // If we are the last line, we should also queue a refresh for the "remaining" bits at the
-        // end which can be redrawn by large unicode
-        if rowEnd == terminal.rows - 1 {
-            let oh = region.height
-            let oy = region.origin.y
-            region = CGRect (x: 0, y: 0, width: frame.width, height: oh + oy)
-        } else {
-            // Region ends mid-screen (a restricted DECSTBM region): extend the
-            // invalidation down by one cell so the sub-cell remainder just below the
-            // band's bottom row (descenders / tall unicode) is cleared too. Previously
-            // only rowEnd == rows-1 got this, leaving a one-row ghost below the region.
-            let extra = cellDimension.height
-            let newY = max (0, region.origin.y - extra)
-            region = CGRect (x: 0, y: newY, width: frame.width, height: region.maxY - newY)
+
+            // If we are the last line, we should also queue a refresh for the "remaining" bits at the
+            // end which can be redrawn by large unicode
+            if rowEnd == terminal.rows - 1 {
+                let oh = region.height
+                let oy = region.origin.y
+                region = CGRect (x: 0, y: 0, width: frame.width, height: oh + oy)
+            } else {
+                // Region ends mid-screen (a restricted DECSTBM region): extend the
+                // invalidation down by one cell so the sub-cell remainder just below the
+                // band's bottom row (descenders / tall unicode) is cleared too. Previously
+                // only rowEnd == rows-1 got this, leaving a one-row ghost below the region.
+                let extra = cellDimension.height
+                let newY = max (0, region.origin.y - extra)
+                region = CGRect (x: 0, y: newY, width: frame.width, height: region.maxY - newY)
+            }
         }
 #if canImport(MetalKit)
         if metalView != nil {

Tests/SwiftTermTests/ScrollbackRepaintTests.swift

@@ -0,0 +1,78 @@
+import Testing
+@testable import SwiftTerm
+
+#if os(macOS)
+import AppKit
+
+private final class ScrollbackRepaintDelegate: TerminalViewDelegate {
+    func sizeChanged(source: TerminalView, newCols: Int, newRows: Int) {}
+    func setTerminalTitle(source: TerminalView, title: String) {}
+    func hostCurrentDirectoryUpdate(source: TerminalView, directory: String?) {}
+    func send(source: TerminalView, data: ArraySlice<UInt8>) {}
+    func scrolled(source: TerminalView, position: Double) {}
+    func rangeChanged(source: TerminalView, startY: Int, endY: Int) {}
+}
+
+/// Records the rects `updateDisplay` asks AppKit to repaint.
+private final class InvalidationCapturingTerminalView: TerminalView {
+    var invalidated: [NSRect] = []
+
+    override func setNeedsDisplay(_ invalidRect: NSRect) {
+        invalidated.append(invalidRect)
+        super.setNeedsDisplay(invalidRect)
+    }
+}
+
+struct ScrollbackRepaintTests {
+    private let esc = "\u{1b}"
+
+    /// The update range is recorded in `buffer.y` space (relative to `yBase`),
+    /// but the draw maps screen rects back to buffer rows through `yDisp`. When
+    /// the viewport is scrolled back the two disagree by `yBase - yDisp`, so a
+    /// partial invalidation lands on the wrong screen rows and the cells that
+    /// changed keep stale content.
+    ///
+    /// Scrolling output hides this, since `scroll()` dirties both `scrollTop`
+    /// and `scrollBottom` and the whole view gets invalidated anyway. The case
+    /// that stays exposed is an in-place repaint, so the write below neither
+    /// scrolls nor moves the cursor between rows.
+    @Test func inPlaceRepaintWhileScrolledBackInvalidatesRenderedRow() {
+        let view = InvalidationCapturingTerminalView(frame: CGRect(x: 0, y: 0, width: 640, height: 320))
+        view.terminalDelegate = ScrollbackRepaintDelegate()
+        let terminal: Terminal = view.terminal
+        let cellHeight = view.cellDimension.height
+
+        for i in 0..<(terminal.rows * 3) {
+            terminal.feed(text: "line \(i)\r\n")
+        }
+        view.updateDisplay()
+
+        let scrolledBackBy = 3
+        let maxScrollback = max(0, terminal.buffer.lines.count - terminal.buffer.rows)
+        view.scrollTo(row: maxScrollback - scrolledBackBy)
+        #expect(terminal.buffer.yBase - terminal.buffer.yDisp == scrolledBackBy)
+
+        // Park the cursor on the target row and flush, so the repaint below
+        // dirties only that row instead of also dirtying the row it came from.
+        let targetRow = 2
+        terminal.feed(text: "\(esc)[\(targetRow + 1);1H")
+        view.updateDisplay()
+        terminal.clearUpdateRange()
+        view.invalidated.removeAll()
+
+        terminal.feed(text: "XXXX")
+        let updateRange = terminal.getUpdateRange()
+        #expect(updateRange?.startY == targetRow)
+        #expect(updateRange?.endY == targetRow)
+        view.updateDisplay()
+
+        // The change is on buffer row `targetRow` of the live screen, which is
+        // drawn `yBase - yDisp` rows further down the viewport.
+        let renderedRow = targetRow + (terminal.buffer.yBase - terminal.buffer.yDisp)
+        let rowBottom = view.frame.height - CGFloat(renderedRow + 1) * cellHeight
+        let rowTop = rowBottom + cellHeight
+        let repainted = view.invalidated.contains { $0.minY <= rowBottom && $0.maxY >= rowTop }
+        #expect(repainted, "invalidated \(view.invalidated), change renders at [\(rowBottom), \(rowTop)]")
+    }
+}
+#endif