@oh-my-pi/pi-tui 14.9.2 → 14.9.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+
+## [14.9.5] - 2026-05-12
+### Fixed
+
+- Fixed rapidly blinking cursor artifact during task execution by consolidating cursor control sequences into the synchronized output buffer ([#992](https://github.com/can1357/oh-my-pi/issues/992))
+
 ## [14.5.7] - 2026-04-29
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "14.9.2",
+	"version": "14.9.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "14.9.2",
-		"@oh-my-pi/pi-utils": "14.9.2",
+		"@oh-my-pi/pi-natives": "14.9.5",
+		"@oh-my-pi/pi-utils": "14.9.5",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},

package/src/tui.ts

@@ -1018,10 +1018,12 @@ export class TUI extends Container {
 				const line = newLines[i];
 				buffer += TERMINAL.isImageLine(line) ? line : line + reset;
 			}
+			this.#cursorRow = Math.max(0, newLines.length - 1);
+			const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, this.#cursorRow);
+			this.#hardwareCursorRow = toRow;
+			buffer += seq;
 			buffer += "\x1b[?2026l"; // End synchronized output
 			this.terminal.write(buffer);
-			this.#cursorRow = Math.max(0, newLines.length - 1);
-			this.#hardwareCursorRow = this.#cursorRow;
 			// Reset max lines when clearing, otherwise track growth
 			if (clear) {
 				this.#maxLinesRendered = newLines.length;
@@ -1029,7 +1031,6 @@ export class TUI extends Container {
 				this.#maxLinesRendered = Math.max(this.#maxLinesRendered, newLines.length);
 			}
 			this.#viewportTopRow = Math.max(0, this.#maxLinesRendered - height);
-			this.#positionHardwareCursor(cursorPos, newLines.length);
 			this.#previousLines = newLines;
 			this.#previousWidth = width;
 			this.#previousHeight = height;
@@ -1101,7 +1102,7 @@ export class TUI extends Container {
 
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
-			this.#positionHardwareCursor(cursorPos, newLines.length);
+			this.#writeCursorPosition(cursorPos, newLines.length);
 			this.#viewportTopRow = Math.max(0, this.#maxLinesRendered - height);
 			return;
 		}
@@ -1135,12 +1136,13 @@ export class TUI extends Container {
 				if (moveUp > 0) {
 					buffer += `\x1b[${moveUp}A`;
 				}
+				this.#cursorRow = targetRow;
+				const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, targetRow);
+				this.#hardwareCursorRow = toRow;
+				buffer += seq;
 				buffer += "\x1b[?2026l";
 				this.terminal.write(buffer);
-				this.#cursorRow = targetRow;
-				this.#hardwareCursorRow = targetRow;
 			}
-			this.#positionHardwareCursor(cursorPos, newLines.length);
 			this.#previousLines = newLines;
 			this.#previousWidth = width;
 			this.#previousHeight = height;
@@ -1166,7 +1168,7 @@ export class TUI extends Container {
 				this.#cursorRow = Math.max(0, newLines.length - 1);
 				this.#maxLinesRendered = newLines.length;
 				this.#viewportTopRow = Math.max(0, newLines.length - height);
-				this.#positionHardwareCursor(cursorPos, newLines.length);
+				this.#writeCursorPosition(cursorPos, newLines.length);
 				this.#previousLines = newLines;
 				this.#previousWidth = width;
 				this.#previousHeight = height;
@@ -1249,6 +1251,9 @@ export class TUI extends Container {
 			buffer += `\x1b[${extraLines}A`;
 		}
 
+		const { seq, toRow } = this.#cursorControlSequence(cursorPos, newLines.length, finalCursorRow);
+		this.#hardwareCursorRow = toRow;
+		buffer += seq;
 		buffer += "\x1b[?2026l"; // End synchronized output
 
 		if ($flag("PI_TUI_DEBUG")) {
@@ -1262,6 +1267,7 @@ export class TUI extends Container {
 				`height: ${height}`,
 				`lineDiff: ${lineDiff}`,
 				`hardwareCursorRow: ${hardwareCursorRow}`,
+				`hardwareCursorRow (post): ${this.#hardwareCursorRow}`,
 				`renderEnd: ${renderEnd}`,
 				`finalCursorRow: ${finalCursorRow}`,
 				`cursorPos: ${JSON.stringify(cursorPos)}`,
@@ -1283,51 +1289,65 @@ export class TUI extends Container {
 		// Write entire buffer at once
 		this.terminal.write(buffer);
 
-		// Track cursor position for next render
-		// cursorRow tracks end of content (for viewport calculation)
-		// hardwareCursorRow tracks actual terminal cursor position (for movement)
+		// Track cursor position for next render.
+		// cursorRow tracks end of content (for viewport calculation).
+		// #hardwareCursorRow was already updated by #cursorControlSequence above.
 		this.#cursorRow = Math.max(0, newLines.length - 1);
-		this.#hardwareCursorRow = finalCursorRow;
 		// Track content height for viewport calculation
 		this.#maxLinesRendered = newLines.length;
 		this.#viewportTopRow = Math.max(0, newLines.length - height);
 
-		// Position hardware cursor for IME
-		this.#positionHardwareCursor(cursorPos, newLines.length);
-
 		this.#previousLines = newLines;
 		this.#previousWidth = width;
 		this.#previousHeight = height;
 	}
 
 	/**
-	 * Position the hardware cursor for IME candidate window.
-	 * @param cursorPos The cursor position extracted from rendered output, or null
-	 * @param totalLines Total number of rendered lines
+	 * Build cursor control sequences to position the hardware cursor for the IME
+	 * candidate window. Returns escape sequences and the resulting cursor row for
+	 * the caller to update `#hardwareCursorRow`. The sequences should be appended
+	 * into the caller's own synchronized output block to avoid a flicker between
+	 * content and cursor frames.
 	 */
-	#positionHardwareCursor(cursorPos: { row: number; col: number } | null, totalLines: number): void {
-		if (!cursorPos || totalLines <= 0) {
-			this.terminal.hideCursor();
-			return;
-		}
+	#cursorControlSequence(
+		cursorPos: { row: number; col: number } | null,
+		totalLines: number,
+		fromRow: number,
+	): { seq: string; toRow: number } {
+		// No IME target or no content — hide cursor regardless of preference
+		if (!cursorPos || totalLines <= 0) return { seq: "\x1b[?25l", toRow: fromRow };
 
 		// Clamp cursor position to valid range
 		const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
 		const targetCol = Math.max(0, cursorPos.col);
 
 		// Move cursor from current position to target
-		const rowDelta = targetRow - this.#hardwareCursorRow;
-		let buffer = "";
+		const rowDelta = targetRow - fromRow;
+		let seq = "";
 		if (rowDelta > 0) {
-			buffer += `\x1b[${rowDelta}B`; // Move down
+			seq += `\x1b[${rowDelta}B`; // Move down
 		} else if (rowDelta < 0) {
-			buffer += `\x1b[${-rowDelta}A`; // Move up
+			seq += `\x1b[${-rowDelta}A`; // Move up
 		}
 		// Move to absolute column (1-indexed)
-		buffer += `\x1b[${targetCol + 1}G`;
-		buffer += this.#showHardwareCursor ? "\x1b[?25h" : "\x1b[?25l";
+		seq += `\x1b[${targetCol + 1}G`;
+		seq += this.#showHardwareCursor ? "\x1b[?25h" : "\x1b[?25l";
 
-		this.terminal.write(`\x1b[?2026h${buffer}\x1b[?2026l`);
-		this.#hardwareCursorRow = targetRow;
+		return { seq, toRow: targetRow };
+	}
+
+	/**
+	 * Write the hardware cursor position to the terminal as a standalone
+	 * synchronized output block. Use when there is no surrounding render buffer
+	 * to embed the sequences into.
+	 */
+	#writeCursorPosition(cursorPos: { row: number; col: number } | null, totalLines: number): void {
+		if (!cursorPos || totalLines <= 0) {
+			this.terminal.hideCursor();
+			return;
+		}
+		const { seq, toRow } = this.#cursorControlSequence(cursorPos, totalLines, this.#hardwareCursorRow);
+		this.#hardwareCursorRow = toRow;
+		this.terminal.write(`\x1b[?2026h${seq}\x1b[?2026l`);
 	}
 }