@gajae-code/tui 0.12.4 → 0.12.6

package/CHANGELOG.md

@@ -2,12 +2,38 @@
 
 ## [Unreleased]
 
+## [0.12.6] - 2026-07-31
+### Fixed
+
+- Select-list no-match rows now stay within the requested render width instead of wrapping into extra terminal lines after narrow resizes (#3600).
+
+## [0.12.5] - 2026-07-30
+
+## [0.12.5] - 2026-07-30
+
 ## [0.12.4] - 2026-07-30
 
 ## [0.12.3] - 2026-07-30
 
 ## [0.12.2] - 2026-07-30
 
+## [0.12.1] - 2026-07-29
+### Added
+
+- `Tui` now exposes renderer-owned viewport observations so tests and evidence capture can assert against committed paint state instead of re-deriving geometry: `getViewportObservation()` (returns a defensive copy of the latest committed observation), `getViewportAnchorSnapshot()`, `getViewportAnchorComponent()`, `getFocusedComponent()`, and `setViewportSelection()`, plus the `TuiViewportObservation` and `MouseSelectionPoint` types.
+
+### Changed
+
+- Alternate-scroll mode (`DECSET 1007`) is now explicitly disabled at startup, on every mouse-capture toggle, at stop, and during emergency restore, so no host translates wheel input into cursor keys. While mouse capture is off this leaves wheel scrollback to the host terminal or multiplexer; while capture is on GJC consumes SGR wheel reports itself, and the reset removes a conflicting second translation path. Hosts that never answer a `DECRQM ?1007$p` query (Apple Terminal among them) cannot report this mode, so it is reset unconditionally rather than conditionally on a reported state.
+
+### Fixed
+
+- The renderer's reported cursor column is now clamped to the last real cell, so it always names a column that exists in the current terminal width. On the wire this is unchanged (a terminal already clamps `CHA` to the last column), but the reported value is now truthful for callers reading it through the viewport observation.
+
+## [0.12.3] - 2026-07-30
+
+## [0.12.2] - 2026-07-30
+
 ## [0.12.1] - 2026-07-29
 
 ### Fixed

package/dist/types/tui.d.ts

@@ -29,6 +29,10 @@ type OverlayMouseBounds = {
     termWidth: number;
     termHeight: number;
 };
+export type MouseSelectionPoint = {
+    line: number;
+    column: number;
+};
 /** Parse xterm SGR mouse reports for wheel, left-click, drag, and release events. */
 export declare function parseSgrMouseEvent(data: string): MouseEvent | undefined;
 export interface Component {
@@ -84,6 +88,30 @@ export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
 export { visibleWidth };
 /** Durable source identifier for a semantically anchored viewport row. */
 export type ViewportAnchorId = string;
+/** Immutable renderer-owned details of the most recently rendered viewport. */
+export interface TuiViewportObservation {
+    transcriptCapacity: number;
+    pinBoundary: {
+        row: number;
+        pinned: boolean;
+    };
+    manualHistory: boolean;
+    newOutputNoticeVisible: boolean;
+    outputRevision: string | null;
+    focused: boolean;
+    cursor: {
+        row: number;
+        col: number;
+        visible: boolean;
+    } | null;
+    selection: {
+        start: MouseSelectionPoint;
+        end: MouseSelectionPoint;
+    } | null;
+    semanticAnchor: (ViewportAnchorRow & {
+        frameRow: number;
+    }) | null;
+}
 export interface ViewportAnchorRow {
     id: ViewportAnchorId;
     graphemeStart: number;
@@ -258,6 +286,17 @@ export declare class TUI extends Container {
      */
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
+    /** Returns the currently focused component without exposing mutable focus state. */
+    getFocusedComponent(): Component | null;
+    /** Returns a defensive snapshot of the latest renderer-owned viewport anchors. */
+    getViewportAnchorSnapshot(): {
+        startRow: number;
+        anchors: Array<ViewportAnchorRow | null>;
+    } | null;
+    /** Returns a defensive snapshot of renderer-owned viewport geometry. */
+    getViewportObservation(): TuiViewportObservation | null;
+    /** Selects a zero-based painted viewport cell range using the same renderer path as mouse dragging. */
+    setViewportSelection(start: MouseSelectionPoint, end: MouseSelectionPoint): void;
     removeChild(component: Component): void;
     clear(): void;
     setBottomPinnedComponent(component: Component | null): void;
@@ -265,6 +304,8 @@ export declare class TUI extends Container {
     setViewportOutputSource(source: ViewportOutputSource | null): void;
     /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
     setViewportAnchorComponent(component: Component | null): void;
+    /** Returns the direct component registered as the semantic viewport anchor source. */
+    getViewportAnchorComponent(): Component | null;
     /** Clear manual viewport ownership before replacing the transcript identity namespace. */
     resetViewportAnchorIntent(): void;
     /** Allow one semantic-neighbor reconciliation after a definitive same-transcript rebuild. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.12.4",
+	"version": "0.12.6",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.12.4",
-		"@gajae-code/utils": "0.12.4",
+		"@gajae-code/natives": "0.12.6",
+		"@gajae-code/utils": "0.12.6",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},

package/src/components/select-list.ts

@@ -118,7 +118,7 @@ export class SelectList implements Component {
 
 		// If no items match filter, show message
 		if (this.#filteredItems.length === 0) {
-			lines.push(this.theme.noMatch("  No matching commands"));
+			lines.push(truncateToWidth(this.theme.noMatch("  No matching commands"), Math.max(0, width), Ellipsis.Omit));
 			return lines;
 		}
 

package/src/terminal.ts

@@ -80,6 +80,7 @@ export function emergencyTerminalRestore(): void {
 					"\x1b[?1000l" + // Disable normal mouse reporting
 					"\x1b[?1002l" + // Disable button-event mouse reporting
 					"\x1b[?1006l" + // Disable SGR extended mouse reporting
+					"\x1b[?1007l" + // Disable alternate-scroll wheel-to-cursor translation
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
 					"\x1b[>4;0m" + // Disable modifyOtherKeys fallback
@@ -278,7 +279,9 @@ export class ProcessTerminal implements Terminal {
 		this.#mouseEnabled = enabled;
 		if (this.#started)
 			this.#safeWrite(
-				this.#mouseEnabled ? "\x1b[?1000l\x1b[?1002h\x1b[?1006h" : "\x1b[?1000l\x1b[?1002l\x1b[?1006l",
+				this.#mouseEnabled
+					? "\x1b[?1000l\x1b[?1002h\x1b[?1006h\x1b[?1007l"
+					: "\x1b[?1000l\x1b[?1002l\x1b[?1006l\x1b[?1007l",
 			);
 	}
 
@@ -306,8 +309,14 @@ export class ProcessTerminal implements Terminal {
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
 		// Button-event reporting preserves wheel input while also letting the TUI implement drag selection.
+		// Alternate-scroll must stay disabled: otherwise Windows Terminal/tmux can translate wheel notches
+		// into cursor Up/Down input, which the focused composer interprets as prompt history.
 		// Clear both tracking variants first so stale modes from another application cannot leak across startup.
-		this.#safeWrite(this.#mouseEnabled ? "\x1b[?1000l\x1b[?1002h\x1b[?1006h" : "\x1b[?1000l\x1b[?1002l\x1b[?1006l");
+		this.#safeWrite(
+			this.#mouseEnabled
+				? "\x1b[?1000l\x1b[?1002h\x1b[?1006h\x1b[?1007l"
+				: "\x1b[?1000l\x1b[?1002l\x1b[?1006l\x1b[?1007l",
+		);
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.#resizeHandler);
@@ -801,6 +810,7 @@ export class ProcessTerminal implements Terminal {
 		this.#safeWrite("\x1b[?1000l");
 		this.#safeWrite("\x1b[?1002l");
 		this.#safeWrite("\x1b[?1006l");
+		this.#safeWrite("\x1b[?1007l");
 
 		// Disable Mode 2031 appearance change notifications
 		this.#safeWrite("\x1b[?2031l");

package/src/tui.ts

@@ -83,7 +83,7 @@ type OverlayMouseBounds = {
 	termHeight: number;
 };
 
-type MouseSelectionPoint = {
+export type MouseSelectionPoint = {
 	line: number;
 	column: number;
 };
@@ -176,6 +176,18 @@ export { visibleWidth };
 
 /** Durable source identifier for a semantically anchored viewport row. */
 export type ViewportAnchorId = string;
+/** Immutable renderer-owned details of the most recently rendered viewport. */
+export interface TuiViewportObservation {
+	transcriptCapacity: number;
+	pinBoundary: { row: number; pinned: boolean };
+	manualHistory: boolean;
+	newOutputNoticeVisible: boolean;
+	outputRevision: string | null;
+	focused: boolean;
+	cursor: { row: number; col: number; visible: boolean } | null;
+	selection: { start: MouseSelectionPoint; end: MouseSelectionPoint } | null;
+	semanticAnchor: (ViewportAnchorRow & { frameRow: number }) | null;
+}
 
 export interface ViewportAnchorRow {
 	id: ViewportAnchorId;
@@ -731,6 +743,7 @@ export class TUI extends Container {
 	#manualViewportFallbackAnchors: ManualViewportAnchor[] = [];
 	#reconcileMissingViewportAnchor = false;
 	#lastCursorPosition: { row: number; col: number } | null = null;
+	#latestViewportObservation: TuiViewportObservation | null = null;
 	#sixelProbePendingDa = false;
 	#sixelProbePendingGraphics = false;
 	#sixelProbeBuffer = "";
@@ -890,6 +903,61 @@ export class TUI extends Container {
 			component.focused = true;
 		}
 	}
+	/** Returns the currently focused component without exposing mutable focus state. */
+	getFocusedComponent(): Component | null {
+		return this.#focusedComponent;
+	}
+
+	/** Returns a defensive snapshot of the latest renderer-owned viewport anchors. */
+	getViewportAnchorSnapshot(): { startRow: number; anchors: Array<ViewportAnchorRow | null> } | null {
+		if (this.#viewportAnchorFrame === null) return null;
+		return {
+			startRow: this.#viewportAnchorFrame.startRow,
+			anchors: this.#viewportAnchorFrame.anchors.map(anchor => (anchor ? { ...anchor } : null)),
+		};
+	}
+
+	/** Returns a defensive snapshot of renderer-owned viewport geometry. */
+	getViewportObservation(): TuiViewportObservation | null {
+		const observation = this.#latestViewportObservation;
+		return observation
+			? {
+					...observation,
+					pinBoundary: { ...observation.pinBoundary },
+					cursor: observation.cursor ? { ...observation.cursor } : null,
+					selection: observation.selection
+						? { start: { ...observation.selection.start }, end: { ...observation.selection.end } }
+						: null,
+					semanticAnchor: observation.semanticAnchor ? { ...observation.semanticAnchor } : null,
+				}
+			: null;
+	}
+
+	/** Selects a zero-based painted viewport cell range using the same renderer path as mouse dragging. */
+	setViewportSelection(start: MouseSelectionPoint, end: MouseSelectionPoint): void {
+		if (!this.options.copySelection) return;
+		// Non-finite coordinates would survive the clamp below as NaN, latch
+		// #mouseSelectionDragged, and force a repaint every frame while reporting a
+		// NaN selection through getViewportObservation(). Reject them the same way
+		// scrollViewportBy does rather than storing an unpaintable selection.
+		if (![start.line, start.column, end.line, end.column].every(value => Number.isFinite(value))) return;
+		const map = (point: MouseSelectionPoint): MouseSelectionPoint | null => {
+			const row = Math.max(0, Math.min(this.terminal.rows - 1, point.line));
+			const column = Math.max(0, Math.min(this.terminal.columns - 1, point.column));
+			return this.#mouseSelectionPoint({ x: column + 1, y: row + 1, kind: "drag" });
+		};
+		const mappedStart = map(start);
+		const mappedEnd = map(end);
+		if (mappedStart === null || mappedEnd === null) {
+			this.#clearMouseSelection();
+			this.requestRender(false, "selection");
+			return;
+		}
+		this.#mouseSelectionStart = mappedStart;
+		this.#mouseSelectionEnd = mappedEnd;
+		this.#mouseSelectionDragged = true;
+		this.requestRender(false, "selection");
+	}
 
 	override removeChild(component: Component): void {
 		this.#invalidateFocusForRemovedTree(component);
@@ -952,6 +1020,10 @@ export class TUI extends Container {
 		this.#viewportAnchorComponent = component;
 		this.#viewportAnchorFrame = null;
 	}
+	/** Returns the direct component registered as the semantic viewport anchor source. */
+	getViewportAnchorComponent(): Component | null {
+		return this.#viewportAnchorComponent;
+	}
 
 	/** Clear manual viewport ownership before replacing the transcript identity namespace. */
 	resetViewportAnchorIntent(): void {
@@ -2439,7 +2511,7 @@ export class TUI extends Container {
 			if (markerIndex !== -1) {
 				// Calculate visual column (width of text before marker)
 				const beforeMarker = line.slice(0, markerIndex);
-				const col = visibleWidth(beforeMarker);
+				const col = Math.max(0, Math.min(Math.max(0, this.terminal.columns - 1), visibleWidth(beforeMarker)));
 
 				// Strip marker from the line
 				lines[row] = line.slice(0, markerIndex) + line.slice(markerIndex + CURSOR_MARKER.length);
@@ -2909,6 +2981,8 @@ export class TUI extends Container {
 				emittedRegions,
 			);
 			onPainted?.();
+			this.#paintedManualOutputNotice = paintManual && this.#manualOutputNotice;
+			this.#recordPaintedViewportObservation(nextViewportTop, height, paintManual);
 		});
 		if (!contentWritten) return false;
 
@@ -2918,6 +2992,63 @@ export class TUI extends Container {
 		}
 		return writeSucceeded;
 	}
+	#recordPaintedViewportObservation(viewportTop: number, height: number, paintManual: boolean): void {
+		const transcriptCapacity = this.#manualTranscriptCapacity(height);
+		const anchorFrame = this.#viewportAnchorFrame;
+		const semanticAnchor =
+			anchorFrame === null
+				? null
+				: (this.#committedTranscriptRows
+						.map((transcriptRow, screenRow) => {
+							if (transcriptRow === null) return null;
+							const anchor = anchorFrame.anchors[transcriptRow - anchorFrame.startRow];
+							return anchor ? { ...anchor, frameRow: screenRow } : null;
+						})
+						.find(anchor => anchor !== null) ?? null);
+		const cursor = this.#lastCursorPosition;
+		let cursorRow: number | null = null;
+		if (cursor !== null) {
+			if (paintManual && cursor.row >= this.#manualTranscriptLineCount) {
+				const noticeRows = this.#manualOutputNotice && height > this.#manualSuffixLineCount ? 1 : 0;
+				cursorRow = transcriptCapacity + noticeRows + (cursor.row - this.#manualTranscriptLineCount);
+			} else if (paintManual) {
+				cursorRow = this.#committedTranscriptRows.indexOf(cursor.row);
+			} else {
+				cursorRow = cursor.row - viewportTop;
+			}
+		}
+		const cursorVisible = cursorRow !== null && cursorRow >= 0 && cursorRow < height;
+		const selectedRange = this.#mouseSelectionDragged ? this.#orderedMouseSelection() : null;
+		const paintedSelection =
+			selectedRange === null
+				? null
+				: {
+						start: { line: selectedRange.start.line - viewportTop, column: selectedRange.start.column },
+						end: { line: selectedRange.end.line - viewportTop, column: selectedRange.end.column },
+					};
+		this.#latestViewportObservation = {
+			transcriptCapacity,
+			pinBoundary: { row: transcriptCapacity, pinned: this.#bottomPinnedComponent !== null },
+			manualHistory: paintManual,
+			newOutputNoticeVisible: paintManual && this.#paintedManualOutputNotice,
+			outputRevision: this.#viewportOutputSource?.revision.toString() ?? null,
+			focused: this.#focusedComponent !== null,
+			cursor: cursor
+				? { row: cursorVisible ? cursorRow! : cursor.row, col: cursor.col, visible: cursorVisible }
+				: null,
+			selection: paintedSelection,
+			semanticAnchor,
+		};
+	}
+
+	#refreshPaintedLiveViewportObservation(height: number): void {
+		this.#committedTranscriptRows = Array.from({ length: height }, (_, screenRow) => {
+			const transcriptRow = this.#viewportTopRow + screenRow;
+			return transcriptRow < this.#manualTranscriptLineCount ? transcriptRow : null;
+		});
+		this.#paintedManualOutputNotice = false;
+		this.#recordPaintedViewportObservation(this.#viewportTopRow, height, false);
+	}
 
 	#doRender(): void {
 		if (this.#stopped || !this.terminalAvailable) return;
@@ -3147,6 +3278,7 @@ export class TUI extends Container {
 			}
 			const nextViewportTop = resolvedAnchorTop ?? this.#manualViewportTop;
 			if (
+				!this.#mouseSelectionDragged &&
 				this.#previousWidth === width &&
 				this.#previousHeight === height &&
 				nextViewportTop === this.#manualViewportTop &&
@@ -3248,6 +3380,7 @@ export class TUI extends Container {
 					);
 					this.#manualTranscriptLineCount = nextTranscriptLineCount;
 					this.#manualSuffixLineCount = nextSuffixLineCount;
+					this.#refreshPaintedLiveViewportObservation(height);
 				})
 			)
 				return;
@@ -3310,6 +3443,7 @@ export class TUI extends Container {
 				);
 				this.#manualTranscriptLineCount = nextTranscriptLineCount;
 				this.#manualSuffixLineCount = nextSuffixLineCount;
+				this.#refreshPaintedLiveViewportObservation(height);
 			});
 			if (!contentWritten) return false;
 
@@ -3436,8 +3570,8 @@ export class TUI extends Container {
 
 		// No changes - but still need to update hardware cursor position if it moved
 		if (firstChanged === -1) {
-			this.#writeCursorPosition(cursorPos, newLines.length);
 			this.#viewportTopRow = Math.max(0, this.#maxLinesRendered - height);
+			if (this.#writeCursorPosition(cursorPos, newLines.length)) this.#refreshPaintedLiveViewportObservation(height);
 			return;
 		}
 
@@ -3548,6 +3682,7 @@ export class TUI extends Container {
 						);
 						this.#manualTranscriptLineCount = nextTranscriptLineCount;
 						this.#manualSuffixLineCount = nextSuffixLineCount;
+						this.#refreshPaintedLiveViewportObservation(height);
 					})
 				)
 					return;
@@ -3559,6 +3694,7 @@ export class TUI extends Container {
 			this.#viewportTopRow = Math.max(0, newLines.length - height);
 			this.#manualTranscriptLineCount = nextTranscriptLineCount;
 			this.#manualSuffixLineCount = nextSuffixLineCount;
+			this.#refreshPaintedLiveViewportObservation(height);
 			return;
 		}
 
@@ -3724,6 +3860,7 @@ export class TUI extends Container {
 				);
 				this.#manualTranscriptLineCount = nextTranscriptLineCount;
 				this.#manualSuffixLineCount = nextSuffixLineCount;
+				this.#refreshPaintedLiveViewportObservation(height);
 			})
 		)
 			return;