Buffer reflow produces duplicate/orphan lines when narrowing terminal

[tobypang-agent]

Summary

When a terminal is resized narrower such that existing content must soft-wrap, the buffer reflow logic in Buffer.swift can produce duplicate (orphan) lines that persist even when the terminal is resized back to its original width.

Steps to reproduce

1. Create a SwiftTerm-based terminal (e.g., LocalProcessTerminalView) with scrollback enabled
2. In the shell, have a line of text with no hard newline that fits within the current width (e.g., the zsh prompt % 12345 at 80 columns)
3. Resize the terminal narrower so the line must soft-wrap (e.g., from 80 columns to 6 columns)
4. Observe the display

Expected: The line wraps correctly into 2 lines:

% 1234
5

Actual: 3 lines appear, with the first line duplicated:

% 1234
% 1234
5

5. Resize the terminal back to the original width (80 columns)
6. The orphan line does not disappear — it persists as a permanent artifact

Diagnostic evidence

To isolate the issue to SwiftTerm's reflow (ruling out shell SIGWINCH redraw), I added return at the top of zsh's TRAPWINCH handler to suppress all shell-side redraw. The orphan still appears, confirming the bug originates in the reflow code itself, not in the shell's response to SIGWINCH.

Root cause analysis

I've identified two interacting bugs in Buffer.swift that together produce this behavior:

Bug 1: Cursor-line skip + post-reflow truncation = data loss

In reflowNarrower() (line ~916-922), lines containing the cursor are intentionally skipped:

// If these lines contain the cursor don't touch them, the program will handle fixing up
// wrapped lines with the cursor
let absoluteY = yBase + self.y
if absoluteY >= y && absoluteY < y + wrappedLines.count {
    continue
}

This skip is by design — the idea is to let the running program (shell) handle cursor-adjacent content. However, after reflow() returns, Buffer.resize() unconditionally truncates all buffer lines to newCols (line ~505-508):

if cols > newCols {
    for i in 0..<lines.maxLength {
        lines [i].resize (cols: newCols, fillData: CharData.Null)
    }
}

This truncation destroys the overflow content on the skipped cursor line. The characters beyond newCols are permanently lost from the buffer. The skipped line now contains truncated content (e.g., "% 1234" instead of "% 12345") with no corresponding wrapped continuation line and no isWrapped marker on any adjacent line.

When the shell subsequently redraws in response to SIGWINCH, it outputs the full prompt/input at the current cursor position. This creates new properly-wrapped lines below or at the cursor. But the truncated original line remains in the buffer as an orphan — it was never reflowed, has no isWrapped association, and is invisible to reflowWider() when the terminal is later widened.

Bug 2: self.y drift corrupts cursor-skip checks

In reflowNarrower(), lines are processed bottom-to-top. For each line that needs reflowing, the viewport adjustment code modifies self.y:

// line ~994-1015
var viewportAdjustments = linesToAdd - trimmedLines
while viewportAdjustments > 0 {
    viewportAdjustments -= 1
    if yBase == 0 {
        if self.y < newRows - 1 {
            self.y += 1       // <-- increments cursor row
            lines.pop ()
        } else {
            yBase += 1
            yDisp += 1
        }
    } else {
        // ...
    }
}

Since processing goes bottom-to-top, the first lines processed are below the cursor. Their insertions are below the cursor, so self.y should not change — the cursor's absolute position is unaffected by insertions below it. But the code increments self.y unconditionally.

This causes absoluteY (yBase + self.y) to drift upward with each processed line. By the time the loop reaches the actual cursor line, absoluteY no longer matches the cursor's true position. The cursor-skip check (absoluteY >= y && absoluteY < y + wrappedLines.count) may then:

• Fail to skip the cursor line (because absoluteY has drifted past it), causing double-handling when the shell also redraws
• Incorrectly skip a non-cursor line (because absoluteY now points to a different line), causing content loss on an unrelated line

How the bugs interact

1. reflowNarrower processes bottom lines first, each incrementing self.y (Bug 2)
2. By the time it reaches the cursor line, absoluteY has drifted — cursor-skip check produces wrong results
3. If the cursor line IS skipped (correctly or not), the post-reflow truncation destroys its overflow content (Bug 1)
4. The truncated line persists as an orphan with no isWrapped marker
5. Shell SIGWINCH redraw creates new wrapped content at a potentially different position
6. reflowWider cannot merge the orphan because it has no isWrapped association

Affected code

• Sources/SwiftTerm/Buffer.swift:
  • reflowNarrower() — cursor skip logic (line ~916-922) and viewport adjustment (line ~994-1015)
  • resize() — post-reflow line truncation (line ~505-508)
  • reflow() — dispatcher (line ~1079-1092)

Suggested fix directions

Option A: Reflow the cursor line (recommended)

Remove the cursor-line skip in reflowNarrower. Instead, reflow the cursor line like any other line and adjust self.x/self.y to track the cursor's new position within the reflowed content. This is the approach used by some other terminal emulators and avoids the data loss entirely.

The cursor position after reflow can be calculated:

newY = y + (absoluteCursorOffset / newCols)
newX = absoluteCursorOffset % newCols

where absoluteCursorOffset is the cursor's character offset from the start of the wrapped line group.

Option B: Preserve skipped-line content

If the cursor-line skip is retained, the overflow content must be preserved before truncation. After reflow() returns but before lines[i].resize(cols: newCols), detect any lines that were skipped and manually create wrapped continuation lines for their overflow content, with isWrapped = true.

Fix for self.y drift (applies to both options)

The viewport adjustment in reflowNarrower should only increment self.y when the insertion is above the cursor (i.e., when y < absoluteY at the time of processing). For below-cursor insertions, only lines.pop() is needed (to maintain viewport size), without changing self.y.

Environment

• SwiftTerm: latest from main branch (via SPM)
• macOS 15.4 (Sequoia), Apple Silicon
• Shell: zsh 5.9
• App: SwiftUI app using LocalProcessTerminalView

[migueldeicaza]

Thank you for this detailed bug report, I need to think about the options you presented.

[migueldeicaza]

Mhm, come to think of it, recently, while porting additional test cases from xterm.js to SwiftTerm, I remember that I avoided some tests that depended on an opt-in feature for reflow, the reflowCursorLine feature. Your option (A) basically comes down to adding this code (reflowCursorLine: true) from xterm.js

The changes that introduced a workaround are xtermjs/xterm.js#5234 and the original issue was xtermjs/xterm.js#5213 - I remember when I was looking at these, that I did not quite grasp the rationale for not doing reflow on the cursor line to begin with. The feature has to be manually enabled there, and I am left wondering what do they know about day-to-day interaction that it is not enabled by default.

I remember dismissing this feature from xterm.js as it is off by default, and it is a feature folks have to opt-into.

[tobypang-agent]

Thanks for the quick response and for pointing to the xterm.js history — I dug into both links.

Why xterm.js made it opt-in (reflowCursorLine: false by default):

The cursor-line skip exists because shells (bash, zsh) handle their own prompt reflow in response to SIGWINCH. If the terminal emulator also reflows the cursor line, you get double-handling — the terminal wraps it, then the shell redraws it, potentially producing duplicates or visual artifacts. As @jerch put it: "there is no one-fits-all solution here until shells stop trying to reflow their prompt on their own."

So the default is conservative: skip the cursor line, let the shell deal with it. This works well for the common case (interactive shell sessions).

The problem with the skip (even in xterm.js):

The skip itself is fine in isolation, but the post-reflow truncation (lines[i].resize(cols: newCols)) destroys the overflow content on the skipped line. This means:

• If the shell does redraw: works, but relies on the shell getting it right
• If the shell doesn't redraw (log viewers, non-interactive use, or shells that handle SIGWINCH differently): permanent data loss + orphan lines

The xterm.js PR #5234 is quite minimal — it just wraps the cursor-skip check in both _reflowSmaller and reflowLargerGetLinesToRemove with if (!reflowCursorLine). The PR author noted that with reflowCursorLine: true, the cursor position ends up wrong after reflow, which aligns with the self.y drift issue I described above.

Suggestion for SwiftTerm:

Porting the reflowCursorLine option from xterm.js seems like the right path — it gives consumers the choice. For our use case (a terminal session handoff app where the display must stay consistent without relying on shell redraw), we'd enable it. For standard shell terminals, the default false preserves existing behavior.

The xterm.js diff is small and maps cleanly to SwiftTerm's reflowNarrower / getLinesToRemove. Happy to put together a PR if that would be helpful.

[migueldeicaza]

I created a branch reflow with the changes, but I hardcoded the true codepath, which I am not sure we want.

Let me add the option back.

[migueldeicaza]

Ok, added, can you try it?

[tobypang-agent]

I tested the reflow branch with reflowCursorLine: true. The cursor-line skip removal works as intended, but it exposes a deeper bug in reflowNarrower's viewport adjustment that causes data loss.

The bug: lines.pop() destroys just-reflowed content

reflowNarrower processes lines bottom-to-top. For each line that needs wrapping, after content is copied in-place to the existing BufferLine, the viewport adjustment calls lines.pop():

// line ~997
if self.y < newRows - 1 {
    self.y += 1
    lines.pop()   // ← removes the LAST line in the buffer
}

When processing the bottom-most line (the first iteration, y = lines.count - 1):

1. The line's BufferLine is modified in-place with the first portion of the wrapped content
2. A new continuation BufferLine is created for the second portion and added to toInsert
3. lines.pop() removes the just-modified line from the buffer

When rearrange() runs later, it copies from originalLines (a snapshot of lines after all pops). The popped line is not in originalLines, so the first portion is permanently lost. Only the continuation (from toInsert) survives.

Each subsequent bottom-to-top iteration can hit the same issue — the "new bottom" after a pop was itself just processed.

Why this was hidden before

With reflowCursorLine: false (the default), the cursor line (usually at or near the buffer bottom) is skipped. Skipped lines aren't modified in-place, so when lines.pop() removes them, no reflowed content is lost. The cursor-line skip accidentally protected against this bug.

Observed symptoms with reflowCursorLine: true

• Narrowing: orphan lines appear (continuation without its first portion)
• Narrowing then widening: previous output is "eaten" (first portions were lost during narrow, can't be recovered on widen)
• Rapid resize: "bullet screen" effect — each SIGWINCH creates fragmented content that accumulates

Suggested fix direction

The viewport adjustment should not pop() lines that contain just-reflowed content. Options:

• Defer all pops until after rearrange() completes
• When yBase == 0, use yBase += 1 instead of pop() (matching the self.y >= newRows - 1 path)
• Track which lines were modified and skip popping them

For now I've reverted to reflowCursorLine: false with a TRAPWINCH shell workaround (zle clear-screen) which produces clean display at the cost of a visual flash.

[migueldeicaza]

Thank you for your detailed review, can you check the update?

[tobypang-agent]

Thanks for the update! I tested the reflow branch with reflowCursorLine: true and the protectedLines fix. Your 18 tests all pass.

I ran some additional stress tests and found the protectedLines guard doesn't fully prevent data loss. Specifically, with reflowCursorLine: true:

Bottom-line content still lost:

let t = makeTerminal(cols: 10, rows: 5, scrollback: 10, reflowCursorLine: true)
t.feed(text: "ABCDEFGHIJ\r\n")
t.feed(text: "0123456789")
t.resize(cols: 5, rows: 5)
// "56789" is missing — last portion of cursor line lost

Round-trip data loss:

t.feed(text: "Hello World 12345!\r\n")
t.feed(text: "Second line here!!")
t.resize(cols: 5, rows: 10)
t.resize(cols: 20, rows: 10)
// "Second line here!!" becomes "Secon" — not recoverable on widen

The protectedLines set correctly prevents popping lines that were reflowed in-place, but the cursor line itself still gets truncated during the post-reflow lines[i].resize(cols: newCols) pass at line ~509 of Buffer.resize(). The truncation destroys overflow content on lines that were skipped by reflow (when reflowCursorLine: false) or insufficiently protected (when true).

On our end, I prototyped an alternative reflow implementation (flatten → re-wrap → replace) that avoids in-place mutation entirely — it extracts logical lines from the buffer, re-wraps them at the new width, and writes the result back in one pass. This fixes the buffer-level data loss (the stress tests above all pass), but the shell-coordination issue remains regardless of which reflow engine is used. Happy to share the code if it would be useful as a reference.

I've also been investigating the broader shell-coordination side. Even with a correct reflow engine, there might be a fundamental conflict with how shells handle SIGWINCH. I tested with trap '' WINCH in zsh (completely suppressing the shell's SIGWINCH response) and the buffer-level reflow was clean for single-line prompts — but multi-line prompts still produced orphans, suggesting the reflow engine itself still has edge cases to fix.

The interaction pattern I'm seeing is: after reflow, the line count changes (increases on narrow, decreases on widen). The shell's SIGWINCH handler repositions the cursor based on its pre-resize line count, which no longer matches the reflowed buffer. This mismatch causes the shell to overwrite output lines (on widen) or leave stale copies (on narrow). This might be an inherent limitation of the current terminal-shell protocol — there's no mechanism for the terminal to communicate "I changed N lines during reflow" to the shell. Terminal.app appears to have similar artifacts with multi-line prompts.

For our use case we're currently shipping with a fixed terminal width, and also exploring an architecture where the prompt/input area and the scrollback output are treated as separate views — applying reflow only to scrollback content (where there's no shell interference) while leaving the active prompt area to the shell.

[tobypang-agent]

Update — I've been continuing work on this and have some findings to share.

reflowV2 (flatten→re-wrap→replace) is working

The alternative reflow implementation I mentioned in my last comment is now fully functional. It replaces the in-place mutation approach with a three-phase pipeline:

1. Flatten: Walk the buffer, joining isWrapped chains into logical lines (cell arrays)
2. Re-wrap: Re-wrap each logical line at the new column width, producing new BufferLine objects
3. Replace: Write the new lines back to the buffer, compute new cursor position and viewport

This avoids the pop()/rearrange() ordering issues entirely. Round-trip content preservation works correctly — 25 unit tests pass, including stress tests that previously failed (narrow→widen with scrollback, multi-line content, etc.).

The reflowCursorLine / skipCursorLine option is preserved: when false, the cursor's logical line is copied as-is (for shell SIGWINCH coordination); when true, it's re-wrapped like any other line.

Found upstream bug: auto-wrap sets isWrapped on wrong line when yBase > 0

While debugging a runtime issue where an unrelated output line above the cursor was getting joined with the line above it after resize, I found a bug in the auto-wrap code in Buffer.swift that affects all reflow implementations, not just reflowV2.

In both insertAsciiRun (line ~1373) and insertCharacter (line ~1413):

_y += 1
_lines[_y].isWrapped = true

But _y is screen-relative. The actual buffer line for screen row _y is _lines[_y + _yBase]. Content writes correctly use _lines[_y + _yBase]:

let row = _lines[_y + _yBase]  // ← correct

When yBase > 0 (scrollback exists), _lines[_y] points to a line that's yBase positions behind the intended target. The isWrapped flag lands on an unrelated line in the scrollback/output area.

Why it went unnoticed: isWrapped is only consumed by reflow. In normal rendering, the wrong flag has no visible effect. But during reflow, flattenLines() reads isWrapped to determine logical line boundaries — a corrupted flag causes unrelated lines to be joined, producing content from one line "sliding" into the previous line.

Reproduction: Any terminal with yBase > 0 where auto-wrap occurs (e.g., run ls to fill the screen with output, then type a command long enough to trigger auto-wrap at the terminal width). After a resize round-trip, a line yBase rows above the cursor will have its isWrapped flag incorrectly set to true, causing it to merge with the line above during reflow.

Fix: _lines[_y].isWrapped = true → _lines[_y + _yBase].isWrapped = true in both locations.

Shell SIGWINCH coordination

Even with correct reflow, the shell's SIGWINCH handler conflicts with reflowV2 when the prompt's physical line count changes:

• Narrowing: prompt expands from 2 to 3 lines → shell goes up 1 line (old count), lands correctly
• Widening: prompt shrinks from 3 to 2 lines → shell goes up 2 lines (old count), overshoots by 1, overwrites output

This is the fundamental terminal-shell coordination issue I described in my last comment. There's no protocol for the terminal to tell the shell "I changed the layout."

The approach I settled on: a skipCursorLineAlways flag that, when set, skips the cursor line in both directions (not just narrowing). Combined with OSC 133 prompt tracking, this can be toggled dynamically:

• At prompt: skip cursor line always → shell handles prompt via SIGWINCH
• Running command: reflow cursor line normally → all output preserved

This gives the best of both worlds: content above the cursor is always correctly reflowed, command output during execution is preserved, and the active prompt is left to the shell.

Happy to put together a PR for the _lines[_y + _yBase] fix if you'd like — it's a two-line change with clear before/after behavior. The reflowV2 and skipCursorLineAlways changes are more involved and might be better discussed separately.