Method positionHardwareCursor

packages/pi-tui/src/tui.ts:1783–1830

* 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 * @param viewportTop Logical row shown on the top screen row after this frame * @param height Terminal he

(
		cursorPos: { row: number; col: number } | null,
		totalLines: number,
		viewportTop: number,
		height: number,
	)

	 * @param height Terminal height (visible viewport size)
	 */
	private positionHardwareCursor(
		cursorPos: { row: number; col: number } | null,
		totalLines: number,
		viewportTop: number,
		height: number,
	): void {
		if (!cursorPos || totalLines <= 0) {
			this.terminal.hideCursor();
			return;
		}

		// Clamp cursor position to valid range
		const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
		const targetCol = Math.max(0, cursorPos.col);

		// The hardware cursor can only sit inside the visible window. A
		// marker outside it (e.g. a tall editor poking above a pinned
		// viewport) must not move the cursor: the ANSI moves would clamp at
		// the screen edge while hardwareCursorRow recorded the unreachable
		// row, desyncing every later differential move. Hide the cursor and
		// keep the bookkeeping on the real cursor row instead.
		if (targetRow < viewportTop || targetRow >= viewportTop + height) {
			this.terminal.hideCursor();
			return;
		}

		// Move cursor from current position to target
		const rowDelta = targetRow - this.hardwareCursorRow;
		let buffer = "";
		if (rowDelta > 0) {
			buffer += `\x1b[${rowDelta}B`; // Move down
		} else if (rowDelta < 0) {
			buffer += `\x1b[${-rowDelta}A`; // Move up
		}
		// Move to absolute column (1-indexed)
		buffer += `\x1b[${targetCol + 1}G`;

		if (buffer) {
			this.terminal.write(buffer);
		}

		this.hardwareCursorRow = targetRow;
		if (this.showHardwareCursor) {
			this.terminal.showCursor();
		} else {
			this.terminal.hideCursor();
		}
	}

	/**
	 * Query the terminal's default background color with OSC 11 (`ESC ] 11 ; ? BEL`).