Method repaintViewport

packages/pi-tui/src/tui.ts:1399–1468

(desiredTop: number, reason: string)

		// otherwise nothing scrolls, so scrollback and the user's scroll
		// position stay intact.
		const repaintViewport = (desiredTop: number, reason: string): void => {
			// An advancing anchor must commit the rows it skips: paint from
			// the old anchor and let the paint loop scroll `advance` rows out
			// of the screen top. A pinned or rewound anchor paints the target
			// window in place without scrolling.
			const advance = Math.max(0, desiredTop - prevViewportTop);
			const paintStart = advance > 0 ? prevViewportTop : desiredTop;
			const paintCount = height + advance;
			// Kitty image lines need multi-row placement; fall back to a
			// destructive full render for that rare combination.
			for (let r = 0; r < paintCount; r++) {
				const idx = paintStart + r;
				if (idx < newLines.length && isImageLine(newLines[idx]!)) {
					logRedraw(`viewport repaint hit kitty image at line ${idx}`);
					fullRender(true);
					return;
				}
			}
			logRedraw(`viewport repaint: ${reason}`);
			let repaint = "\x1b[?2026h"; // Begin synchronized output
			// Delete kitty images placed in the old visible viewport; images
			// above it live in scrollback and are left alone. A multi-row
			// image can straddle the viewport top: its id lives on the image
			// line above prevViewportTop while its reserved rows are still
			// visible, so widen the range to include such blocks — otherwise
			// the stale overlay would survive the repaint and its id would
			// drop out of previousKittyImageIds, never to be cleaned up.
			let deleteFrom = prevViewportTop;
			for (let k = 0; k < prevViewportTop; k++) {
				const prevLine = this.previousLines[k] ?? "";
				if (!isImageLine(prevLine)) continue;
				const blockEnd = k + this.getKittyImageReservedRows(this.previousLines, k) - 1;
				if (blockEnd >= prevViewportTop) {
					deleteFrom = k;
					break;
				}
			}
			repaint += this.deleteChangedKittyImages(deleteFrom, this.previousLines.length - 1);
			// Move the cursor to the top of the screen (old anchor still valid).
			const cursorScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));
			if (cursorScreenRow > 0) {
				repaint += `\x1b[${cursorScreenRow}A`;
			}
			repaint += "\r";
			// Rewrite paintCount rows from paintStart. Rows written past the
			// bottom screen row scroll the terminal: with an advancing anchor
			// the first `advance` rows (freshly painted) scroll into
			// scrollback, committing them exactly once. With advance = 0 the
			// last row gets no trailing \r\n, so nothing scrolls.
			for (let r = 0; r < paintCount; r++) {
				if (r > 0) repaint += "\r\n";
				repaint += "\x1b[2K";
				const idx = paintStart + r;
				if (idx < newLines.length) {
					repaint += newLines[idx]!;
				}
			}
			repaint += "\x1b[?2026l"; // End synchronized output