@oh-my-pi/pi-tui 13.5.2 → 13.5.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [13.5.3] - 2026-03-01
+
+### Fixed
+
+- Fixed append rendering logic to correctly handle offscreen header changes during content overflow growth, preserving scroll history integrity
+- Fixed visible tail line updates when appending new content during viewport overflow conditions
+- Fixed cursor positioning instability when appending content under external cursor relocation by using absolute screen addressing instead of relative cursor movement
+
 ## [13.5.2] - 2026-03-01
 ### Breaking Changes
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "13.5.2",
+	"version": "13.5.3",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -33,8 +33,8 @@
 		"test": "bun test test/*.test.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "13.5.2",
-		"@oh-my-pi/pi-utils": "13.5.2",
+		"@oh-my-pi/pi-natives": "13.5.3",
+		"@oh-my-pi/pi-utils": "13.5.3",
 		"marked": "^17.0"
 	},
 	"devDependencies": {

package/src/tui.ts

@@ -856,6 +856,12 @@ export class TUI extends Container {
 		return null;
 	}
 
+	#moveToScreenPosition(row: number, col = 0): string {
+		const safeRow = Math.max(0, row);
+		const safeCol = Math.max(0, col);
+		return `\x1b[${safeRow + 1};${safeCol + 1}H`;
+	}
+
 	#doRender(): void {
 		if (this.#stopped) return;
 		const width = this.terminal.columns;
@@ -928,7 +934,7 @@ export class TUI extends Container {
 		// === write only the visible viewport lines.                           ===
 		// Used for height changes, content shrink, and all diff fallback paths.
 		// Key properties:
-		//   - Never uses \x1b[H (home) — avoids scroll-to-top flash
+		//   - Uses absolute screen addressing for stable cursor anchoring
 		//   - Never uses \x1b[3J — preserves scrollback history
 		//   - Writes only viewport-visible lines — no intermediate states
 		const viewportRepaint = (): void => {
@@ -938,11 +944,8 @@ export class TUI extends Container {
 
 			let buffer = "\x1b[?2026h"; // Begin synchronized output
 
-			// Move cursor from current position to screen row 0 (top of our owned area)
-			if (hardwareCursorRow > 0) {
-				buffer += `\x1b[${hardwareCursorRow}A`;
-			}
-			buffer += "\r"; // Column 0
+			// Move cursor to top-left of the viewport using absolute addressing.
+			buffer += this.#moveToScreenPosition(0, 0);
 
 			// Clear from here downward — erases old content and any stale rows below.
 			// Does NOT touch scrollback above us.
@@ -1034,14 +1037,28 @@ export class TUI extends Container {
 				lastChanged = i;
 			}
 		}
-		const appendedLines = newLines.length > this.#previousLines.length;
+		const previousLineCount = this.#previousLines.length;
+		const appendedLines = newLines.length > previousLineCount;
 		if (appendedLines) {
 			if (firstChanged === -1) {
-				firstChanged = this.#previousLines.length;
+				firstChanged = previousLineCount;
 			}
 			lastChanged = newLines.length - 1;
 		}
-		const appendStart = appendedLines && firstChanged === this.#previousLines.length && firstChanged > 0;
+
+		const pureAppendStart = appendedLines && firstChanged === previousLineCount && firstChanged > 0;
+		let canAppendWithOffscreenChanges = false;
+		if (appendedLines && firstChanged >= 0 && firstChanged < previousViewportTop && previousViewportTop > 0) {
+			canAppendWithOffscreenChanges = true;
+			for (let i = previousViewportTop; i < previousLineCount; i++) {
+				if (this.#previousLines[i] !== newLines[i]) {
+					canAppendWithOffscreenChanges = false;
+					break;
+				}
+			}
+		}
+		const appendCandidate = pureAppendStart || canAppendWithOffscreenChanges;
+		const appendFrom = appendCandidate && !pureAppendStart ? previousLineCount : firstChanged;
 
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
@@ -1051,10 +1068,10 @@ export class TUI extends Container {
 		}
 		const renderEnd = Math.min(lastChanged, newLines.length - 1);
 		const viewportShifted = viewportTop !== previousViewportTop;
-		const simpleAppendScroll = appendStart && renderEnd > previousViewportBottom;
-		if (viewportShifted && !simpleAppendScroll) {
+		const appendScroll = appendCandidate && renderEnd >= appendFrom && renderEnd > previousViewportBottom;
+		if (viewportShifted && !appendScroll) {
 			logRedraw(
-				`viewport shift fallback (prevTop=${previousViewportTop}, top=${viewportTop}, first=${firstChanged}, end=${renderEnd}, appendStart=${appendStart})`,
+				`viewport shift fallback (prevTop=${previousViewportTop}, top=${viewportTop}, first=${firstChanged}, end=${renderEnd}, appendScroll=${appendScroll}, appendFrom=${appendFrom})`,
 			);
 			viewportRepaint();
 			return;
@@ -1076,15 +1093,7 @@ export class TUI extends Container {
 				return;
 			}
 			let buffer = "\x1b[?2026h";
-			const lineDiff = targetScreenRow - hardwareCursorRow;
-			if (!Number.isFinite(lineDiff) || Math.abs(lineDiff) > height * 2) {
-				logRedraw(`large deleted-line delta (${lineDiff})`);
-				viewportRepaint();
-				return;
-			}
-			if (lineDiff > 0) buffer += `\x1b[${lineDiff}B`;
-			else if (lineDiff < 0) buffer += `\x1b[${-lineDiff}A`;
-			buffer += "\r";
+			buffer += this.#moveToScreenPosition(targetScreenRow, 0);
 			// Erase stale rows below the new tail without scrolling.
 			if (newLines.length > 0) {
 				if (targetScreenRow < height - 1) {
@@ -1114,7 +1123,7 @@ export class TUI extends Container {
 		// Check if firstChanged is above what was previously visible
 		// Use previousLines.length (not maxLinesRendered) to avoid false positives after content shrinks
 		const previousContentViewportTop = previousViewportTop;
-		if (firstChanged < previousContentViewportTop) {
+		if (!appendScroll && firstChanged < previousContentViewportTop) {
 			// First change is above previous viewport - force a viewport-anchored full re-render.
 			logRedraw(`firstChanged < viewportTop (${firstChanged} < ${previousContentViewportTop})`);
 			viewportRepaint();
@@ -1124,20 +1133,12 @@ export class TUI extends Container {
 		// Render from first changed line to end
 		// Build buffer with all updates wrapped in synchronized output
 		let buffer = "\x1b[?2026h"; // Begin synchronized output
-		const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;
+		const moveTargetRow = appendScroll ? appendFrom - 1 : firstChanged;
 		const moveTargetScreenRow = moveTargetRow - previousViewportTop;
-		if (appendStart && renderEnd > previousViewportBottom) {
+		if (appendScroll) {
 			let appendBuffer = "\x1b[?2026h";
-			const appendLineDiff = moveTargetScreenRow - hardwareCursorRow;
-			if (!Number.isFinite(appendLineDiff) || Math.abs(appendLineDiff) > height * 2) {
-				logRedraw(`append fallback due to large delta (${appendLineDiff})`);
-				viewportRepaint();
-				return;
-			}
-			if (appendLineDiff > 0) appendBuffer += `\x1b[${appendLineDiff}B`;
-			else if (appendLineDiff < 0) appendBuffer += `\x1b[${-appendLineDiff}A`;
-			appendBuffer += "\r";
-			for (let i = firstChanged; i <= renderEnd; i++) {
+			appendBuffer += this.#moveToScreenPosition(moveTargetScreenRow, 0);
+			for (let i = appendFrom; i <= renderEnd; i++) {
 				appendBuffer += "\r\n\x1b[2K";
 				const line = newLines[i];
 				const isImage = TERMINAL.isImageLine(line);
@@ -1148,7 +1149,7 @@ export class TUI extends Container {
 				}
 				appendBuffer += line;
 			}
-			const appendEndScreenRow = Math.min(height - 1, moveTargetScreenRow + (renderEnd - firstChanged + 1));
+			const appendEndScreenRow = Math.min(height - 1, moveTargetScreenRow + (renderEnd - appendFrom + 1));
 			const cursorPosScreen = cursorPos
 				? { row: Math.max(0, cursorPos.row - viewportTop), col: cursorPos.col }
 				: null;
@@ -1169,7 +1170,7 @@ export class TUI extends Container {
 		if (
 			moveTargetScreenRow < 0 ||
 			moveTargetScreenRow >= height ||
-			(!appendStart && renderEnd > previousViewportBottom)
+			(!appendScroll && renderEnd > previousViewportBottom)
 		) {
 			logRedraw(
 				`offscreen diff fallback (move=${moveTargetScreenRow}, renderEnd=${renderEnd}, viewportBottom=${previousViewportBottom})`,
@@ -1178,20 +1179,10 @@ export class TUI extends Container {
 			return;
 		}
 
-		// Move cursor to first changed line (screen-relative)
+		// Move cursor to first changed line (screen-relative) using absolute coordinates.
 		const lineDiff = moveTargetScreenRow - hardwareCursorRow;
-		if (!Number.isFinite(lineDiff) || Math.abs(lineDiff) > height * 2) {
-			logRedraw(`large diff delta (${lineDiff})`);
-			viewportRepaint();
-			return;
-		}
-		if (lineDiff > 0) {
-			buffer += `\x1b[${lineDiff}B`; // Move down
-		} else if (lineDiff < 0) {
-			buffer += `\x1b[${-lineDiff}A`; // Move up
-		}
-
-		buffer += appendStart ? "\r\n" : "\r"; // Move to column 0
+		buffer += this.#moveToScreenPosition(moveTargetScreenRow, 0);
+		if (appendScroll) buffer += "\r\n";
 
 		// Only render changed lines (firstChanged to lastChanged), not all lines to end
 		// This reduces flicker when only a single line changes (e.g., spinner animation)
@@ -1232,15 +1223,16 @@ export class TUI extends Container {
 		}
 
 		// Track where cursor ended up after rendering (screen-relative).
-		let finalCursorRow = moveTargetScreenRow + (appendStart ? 1 : 0) + Math.max(0, renderEnd - firstChanged);
+		let finalCursorRow =
+			moveTargetScreenRow +
+			(appendScroll ? 1 : 0) +
+			Math.max(0, renderEnd - (appendScroll ? appendFrom : firstChanged));
 
 		// If we had more lines before, clear stale rows below new content without scrolling.
 		if (this.#previousLines.length > newLines.length) {
 			if (newLines.length === 0) {
-				if (finalCursorRow > 0) {
-					buffer += `\x1b[${finalCursorRow}A`;
-				}
-				buffer += "\r\x1b[J";
+				buffer += this.#moveToScreenPosition(0, 0);
+				buffer += "\x1b[J";
 				finalCursorRow = 0;
 			} else {
 				const tailScreenRow = newLines.length - 1 - viewportTop;
@@ -1249,13 +1241,8 @@ export class TUI extends Container {
 					viewportRepaint();
 					return;
 				}
-				if (finalCursorRow < tailScreenRow) {
-					buffer += `\x1b[${tailScreenRow - finalCursorRow}B`;
-					finalCursorRow = tailScreenRow;
-				} else if (finalCursorRow > tailScreenRow) {
-					buffer += `\x1b[${finalCursorRow - tailScreenRow}A`;
-					finalCursorRow = tailScreenRow;
-				}
+				buffer += this.#moveToScreenPosition(tailScreenRow, 0);
+				finalCursorRow = tailScreenRow;
 				if (tailScreenRow < height - 1) {
 					buffer += "\x1b[1B\r\x1b[J\x1b[1A";
 				}
@@ -1297,7 +1284,7 @@ export class TUI extends Container {
 		// Write entire buffer at once
 		this.terminal.write(buffer);
 		// cursorRow tracks end of content (for viewport calculation)
-		// hardwareCursorRow tracks screen-relative cursor position used for relative movement
+		// hardwareCursorRow tracks last committed screen-relative cursor row
 		this.#cursorRow = Math.max(0, newLines.length - 1);
 		this.#hardwareCursorRow = cursorUpdate.row;
 		this.#lastCursorSequence = cursorUpdate.sequence;
@@ -1328,14 +1315,7 @@ export class TUI extends Container {
 		// Clamp cursor position to valid range
 		const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
 		const targetCol = Math.max(0, cursorPos.col);
-		let sequence = "";
-		const rowDelta = targetRow - currentRow;
-		if (rowDelta > 0) {
-			sequence += `\x1b[${rowDelta}B`; // Move down
-		} else if (rowDelta < 0) {
-			sequence += `\x1b[${-rowDelta}A`; // Move up
-		}
-		sequence += `\x1b[${targetCol + 1}G`; // Move to absolute column (1-indexed)
+		let sequence = this.#moveToScreenPosition(targetRow, targetCol);
 		sequence += this.#showHardwareCursor ? "\x1b[?25h" : "\x1b[?25l";
 
 		return { sequence, row: targetRow };