@oh-my-pi/pi-tui 12.11.2 → 12.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-tui",
-	"version": "12.11.2",
+	"version": "12.12.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -52,8 +52,8 @@
 	"bun": ">=1.3.7"
 },
 "dependencies": {
-	"@oh-my-pi/pi-natives": "12.11.2",
-	"@oh-my-pi/pi-utils": "12.11.2",
+	"@oh-my-pi/pi-natives": "12.12.1",
+	"@oh-my-pi/pi-utils": "12.12.1",
 	"@types/mime-types": "^3.0.1",
 	"chalk": "^5.6.2",
 	"marked": "^17.0.2",

package/src/components/editor.ts

@@ -246,6 +246,7 @@ function decodeKittyPrintable(data: string): string | undefined {
 		return undefined;
 	}
 }
+const DEFAULT_PAGE_SCROLL_LINES = 10;
 
 interface EditorState {
 	lines: string[];
@@ -284,6 +285,8 @@ interface HistoryStorage {
 	getRecent(limit: number): HistoryEntry[];
 }
 
+type HistoryCursorAnchor = "start" | "end";
+
 export class Editor implements Component, Focusable {
 	#state: EditorState = {
 		lines: [""],
@@ -388,8 +391,9 @@ export class Editor implements Component, Focusable {
 	}
 
 	setMaxHeight(maxHeight: number | undefined): void {
+		if (this.#maxHeight === maxHeight) return;
 		this.#maxHeight = maxHeight;
-		this.#scrollOffset = 0;
+		// Don't reset scrollOffset — #updateScrollOffset will clamp it on next render
 	}
 
 	setPaddingX(paddingX: number): void {
@@ -451,28 +455,29 @@ export class Editor implements Component, Focusable {
 	#navigateHistory(direction: 1 | -1): void {
 		this.#resetKillSequence();
 		if (this.#history.length === 0) return;
-
 		const newIndex = this.#historyIndex - direction; // Up(-1) increases index, Down(1) decreases
 		if (newIndex < -1 || newIndex >= this.#history.length) return;
-
 		this.#historyIndex = newIndex;
-
 		if (this.#historyIndex === -1) {
 			// Returned to "current" state - clear editor
-			this.#setTextInternal("");
+			this.#setTextInternal("", "end");
 		} else {
-			this.#setTextInternal(this.#history[this.#historyIndex] || "");
+			const cursorAnchor: HistoryCursorAnchor = direction === -1 ? "start" : "end";
+			this.#setTextInternal(this.#history[this.#historyIndex] || "", cursorAnchor);
 		}
 	}
-
 	/** Internal setText that doesn't reset history state - used by navigateHistory */
-	#setTextInternal(text: string): void {
+	#setTextInternal(text: string, cursorAnchor: HistoryCursorAnchor = "end"): void {
 		this.#undoStack.length = 0;
 		const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
 		this.#state.lines = lines.length === 0 ? [""] : lines;
-		this.#state.cursorLine = this.#state.lines.length - 1;
-		this.#setCursorCol(this.#state.lines[this.#state.cursorLine]?.length || 0);
-
+		if (cursorAnchor === "start") {
+			this.#state.cursorLine = 0;
+			this.#setCursorCol(0);
+		} else {
+			this.#state.cursorLine = this.#state.lines.length - 1;
+			this.#setCursorCol(this.#state.lines[this.#state.cursorLine]?.length || 0);
+		}
 		if (this.onChange) {
 			this.onChange(this.getText());
 		}
@@ -501,6 +506,12 @@ export class Editor implements Component, Focusable {
 		return Math.max(1, this.#maxHeight - 2);
 	}
 
+	#getPageScrollStep(totalVisualLines: number): number {
+		const visibleHeight =
+			this.#maxHeight === undefined ? DEFAULT_PAGE_SCROLL_LINES : this.#getVisibleContentHeight(totalVisualLines);
+		return Math.max(1, visibleHeight - 1);
+	}
+
 	#updateScrollOffset(layoutWidth: number, layoutLines: LayoutLine[], visibleHeight: number): void {
 		if (layoutLines.length <= visibleHeight) {
 			this.#scrollOffset = 0;
@@ -751,13 +762,20 @@ export class Editor implements Component, Focusable {
 			else if (
 				matchesKey(data, "up") ||
 				matchesKey(data, "down") ||
+				matchesKey(data, "pageUp") ||
+				matchesKey(data, "pageDown") ||
 				matchesKey(data, "enter") ||
 				matchesKey(data, "return") ||
 				data === "\n" ||
 				matchesKey(data, "tab")
 			) {
-				// Only pass arrow keys to the list, not Enter/Tab (we handle those directly)
-				if (matchesKey(data, "up") || matchesKey(data, "down")) {
+				// Only pass navigation keys to the list, not Enter/Tab (we handle those directly)
+				if (
+					matchesKey(data, "up") ||
+					matchesKey(data, "down") ||
+					matchesKey(data, "pageUp") ||
+					matchesKey(data, "pageDown")
+				) {
 					this.#autocompleteList.handleInput(data);
 					this.onAutocompleteUpdate?.();
 					return;
@@ -935,6 +953,22 @@ export class Editor implements Component, Focusable {
 		} else if (matchesKey(data, "end")) {
 			this.#moveToLineEnd();
 		}
+		// Page navigation (PageUp/PageDown)
+		else if (matchesKey(data, "pageUp")) {
+			if (this.#isEditorEmpty()) {
+				this.#navigateHistory(-1);
+			} else if (this.#historyIndex > -1 && this.#isOnFirstVisualLine()) {
+				this.#navigateHistory(-1);
+			} else {
+				this.#pageScroll(-1);
+			}
+		} else if (matchesKey(data, "pageDown")) {
+			if (this.#historyIndex > -1 && this.#isOnLastVisualLine()) {
+				this.#navigateHistory(1);
+			} else {
+				this.#pageScroll(1);
+			}
+		}
 		// Forward delete (Fn+Backspace or Delete key, including Shift+Delete)
 		else if (matchesKey(data, "delete") || matchesKey(data, "shift+delete")) {
 			this.#handleForwardDelete();
@@ -1122,9 +1156,19 @@ export class Editor implements Component, Focusable {
 		this.#setTextInternal(text);
 	}
 
+	#exitHistoryForEditing(): void {
+		if (this.#historyIndex === -1) return;
+		if (this.#state.cursorLine === 0 && this.#state.cursorCol === 0) {
+			this.#state.cursorLine = this.#state.lines.length - 1;
+			const line = this.#state.lines[this.#state.cursorLine] || "";
+			this.#setCursorCol(line.length);
+		}
+		this.#historyIndex = -1;
+	}
+
 	/** Insert text at the current cursor position */
 	insertText(text: string): void {
-		this.#historyIndex = -1;
+		this.#exitHistoryForEditing();
 		this.#resetKillSequence();
 		this.#recordUndoState();
 
@@ -1142,7 +1186,7 @@ export class Editor implements Component, Focusable {
 
 	// All the editor methods from before...
 	#insertCharacter(char: string): void {
-		this.#historyIndex = -1; // Exit history browsing mode
+		this.#exitHistoryForEditing();
 		this.#resetKillSequence();
 		this.#recordUndoState();
 
@@ -1896,6 +1940,16 @@ export class Editor implements Component, Focusable {
 		}
 	}
 
+	#pageScroll(direction: -1 | 1): void {
+		this.#resetKillSequence();
+		const visualLines = this.#buildVisualLineMap(this.#lastLayoutWidth);
+		const currentVisualLine = this.#findCurrentVisualLine(visualLines);
+		const step = this.#getPageScrollStep(visualLines.length);
+		const targetVisualLine = Math.max(0, Math.min(visualLines.length - 1, currentVisualLine + direction * step));
+		if (targetVisualLine === currentVisualLine) return;
+		this.#moveToVisualLine(visualLines, currentVisualLine, targetVisualLine);
+	}
+
 	#moveWordBackwards(): void {
 		const currentLine = this.#state.lines[this.#state.cursorLine] || "";
 

package/src/components/select-list.ts

@@ -148,6 +148,7 @@ export class SelectList implements Component {
 	}
 
 	handleInput(keyData: string): void {
+		if (this.#filteredItems.length === 0) return;
 		// Up arrow - wrap to bottom when at top
 		if (matchesKey(keyData, "up")) {
 			this.#selectedIndex = this.#selectedIndex === 0 ? this.#filteredItems.length - 1 : this.#selectedIndex - 1;
@@ -158,6 +159,16 @@ export class SelectList implements Component {
 			this.#selectedIndex = this.#selectedIndex === this.#filteredItems.length - 1 ? 0 : this.#selectedIndex + 1;
 			this.#notifySelectionChange();
 		}
+		// PageUp - jump up by one visible page
+		else if (matchesKey(keyData, "pageUp")) {
+			this.#selectedIndex = Math.max(0, this.#selectedIndex - this.maxVisible);
+			this.#notifySelectionChange();
+		}
+		// PageDown - jump down by one visible page
+		else if (matchesKey(keyData, "pageDown")) {
+			this.#selectedIndex = Math.min(this.#filteredItems.length - 1, this.#selectedIndex + this.maxVisible);
+			this.#notifySelectionChange();
+		}
 		// Enter
 		else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
 			const selectedItem = this.#filteredItems[this.#selectedIndex];

package/src/tui.ts

@@ -967,28 +967,24 @@ export class TUI extends Container {
 
 		// All changes are in deleted lines (nothing to render, just clear)
 		if (firstChanged >= newLines.length) {
+			const extraLines = this.#previousLines.length - newLines.length;
+			if (extraLines > height) {
+				logRedraw(`deletedLines > height (${extraLines} > ${height})`);
+				fullRender(true);
+				return;
+			}
 			const targetRow = Math.max(0, newLines.length - 1);
 			let buffer = "\x1b[?2026h";
 			const lineDiff = computeLineDiff(targetRow);
 			if (lineDiff > 0) buffer += `\x1b[${lineDiff}B`;
 			else if (lineDiff < 0) buffer += `\x1b[${-lineDiff}A`;
 			buffer += "\r";
-			// Clear extra lines without scrolling
-			const extraLines = this.#previousLines.length - newLines.length;
-			if (extraLines > height) {
-				logRedraw(`extraLines > height (${extraLines} > ${height})`);
-				fullRender(true);
-				return;
-			}
-			if (extraLines > 0) {
-				buffer += "\x1b[1B";
-			}
-			for (let i = 0; i < extraLines; i++) {
-				buffer += "\r\x1b[2K";
-				if (i < extraLines - 1) buffer += "\x1b[1B";
-			}
-			if (extraLines > 0) {
-				buffer += `\x1b[${extraLines}A`;
+			// Erase all stale lines below the new content
+			if (newLines.length > 0) {
+				buffer += "\x1b[1B\x1b[J\x1b[1A";
+			} else {
+				// Content is completely empty — clear from cursor row
+				buffer += "\x1b[J";
 			}
 			const cursorUpdate = this.#buildHardwareCursorSequence(cursorPos, newLines.length, targetRow);
 			buffer += cursorUpdate.sequence;
@@ -1082,7 +1078,10 @@ export class TUI extends Container {
 		// Track where cursor ended up after rendering
 		let finalCursorRow = renderEnd;
 
-		// If we had more lines before, clear them and move cursor back
+		// If we had more lines before, clear everything below new content.
+		// Uses \x1b[J (erase-below) to atomically clear all stale rows in one
+		// operation instead of clearing line-by-line. This avoids cursor-tracking
+		// drift that can cause stale content to remain visible.
 		if (this.#previousLines.length > newLines.length) {
 			// Move to end of new content first if we stopped before it
 			if (renderEnd < newLines.length - 1) {
@@ -1090,12 +1089,8 @@ export class TUI extends Container {
 				buffer += `\x1b[${moveDown}B`;
 				finalCursorRow = newLines.length - 1;
 			}
-			const extraLines = this.#previousLines.length - newLines.length;
-			for (let i = newLines.length; i < this.#previousLines.length; i++) {
-				buffer += "\r\n\x1b[2K";
-			}
-			// Move cursor back to end of new content
-			buffer += `\x1b[${extraLines}A`;
+			// Move to the first stale line and erase from there to end of screen
+			buffer += "\r\n\x1b[J\x1b[A";
 		}
 
 		const cursorUpdate = this.#buildHardwareCursorSequence(cursorPos, newLines.length, finalCursorRow);