pi-tui: giao diện terminal vẽ theo vi sai

Vai trò của pi-tui#

Một coding agent chạy trong terminal phải vẽ cùng lúc nhiều thứ thay đổi liên tục: câu trả lời đang stream từng token, các hàng tool với trạng thái đang chạy, ô soạn thảo nơi người dùng vẫn gõ được, footer với số token và phần trăm cửa sổ ngữ cảnh (context window). Terminal không có DOM. Thứ duy nhất chương trình có là một luồng byte ghi ra stdout, gồm chữ xen với các chuỗi điều khiển (escape sequence) để di chuyển con trỏ, xoá dòng, đổi màu. Nếu mỗi token mới lại xoá màn hình rồi vẽ lại tất cả, màn hình nhấp nháy, CPU bận vô ích, và scrollback (phần lịch sử mà terminal giữ phía trên màn hình) bị phá. pi-tui giải quyết đúng việc này: ứng dụng mô tả giao diện bằng một cây component, mỗi component chỉ biết trả về các dòng văn bản cho một độ rộng; pi-tui so khung hình mới với khung trước rồi chỉ ghi phần khác.

Gói là @earendil-works/pi-tui, thư mục packages/tui, khoảng 19.600 dòng TypeScript trong src/. README mô tả nó là “Minimal terminal UI framework with differential rendering and synchronized output for flicker-free interactive CLI applications” (README.md:3). Lúc chạy, gói chỉ phụ thuộc ba thư viện: get-east-asian-width để đo độ rộng ký tự Đông Á, marked và marked-cjk-friendly để phân tích Markdown (package.json:53–57). Phần còn lại, từ phân tích phím, độ rộng grapheme, bố cục, cuộn, chọn văn bản tới ảnh inline, đều tự viết.

Ai dùng gói này:

• Chế độ interactive của coding agent (packages/coding-agent/src/modes/interactive/) là người dùng chính: nó dựng toàn bộ giao diện chat trên pi-tui (mục Interactive mode). Các chế độ print, JSON, RPC và SDK không vẽ TUI; xem chương Các chế độ chạy.
• Lệnh pi config dựng riêng một TuiMainScreen nhỏ cho bộ chọn cấu hình (config-selector.ts:25).
• Extension vẽ hộp thoại, widget, overlay qua ctx.ui bằng chính các component của pi-tui. Bề mặt API đó thuộc chương Extensions; tài liệu dặn rõ “Do not create a second terminal renderer inside an extension” (docs/tui.md:18).

Mô hình tư duy: component, frame và vi sai#

Mọi thứ trong chương xoay quanh một vòng: có sự kiện, component đổi state và xin vẽ lại; TUI gộp các lời xin đó thành một khung hình (frame), dựng khung bằng cách gọi render(width) trên cây, rồi so với khung trước để quyết định ghi byte nào.

sự kiện: token mới, phím bấm, resize, nhịp spinner, màu terminal trả về
   │  component đổi state, gọi tui.requestRender()
   ▼
requestRender()   gộp lại: tối đa một khung mỗi 16 ms; phím bấm thì vẽ ngay ở nextTick
   ▼
doRender()
   1. lines = root.render(width)        mỗi phần tử một dòng, rộng không quá width
   2. resolveFakeCursors(lines)         con trỏ giả thành video đảo (SGR 7 / 27)
   3. compositeOverlays(lines)          chồng overlay lên các dòng nền
   4. extractCursorPosition(lines)      tìm và gỡ CURSOR_MARKER, nhớ hàng/cột
   5. applyLineResets(lines)            nối \x1b[0m\x1b]8;;\x07 vào cuối mỗi dòng
   6. so với khung trước
        ├─ TuiMainScreen (regular):    từ dòng đầu tiên khác, ghi đè tới hết;
        │                               dòng dư ở đáy đẩy dòng cũ lên scrollback
        └─ TuiAltScreen  (fullscreen): so từng hàng của viewport, hàng khác thì ghi
   7. bọc trong \x1b[?2026h … \x1b[?2026l, ghi ra stdout, lưu làm khung trước

Từ vựng dùng trong phần còn lại:

Component

Đối tượng có render(width): string[]. Mỗi chuỗi là một dòng terminal, có thể chứa mã ANSI, và độ rộng hiển thị không được vượt width.

Retained mode (giữ cây)

Ứng dụng giữ một cây đối tượng component sống lâu, đổi state của chúng, còn TUI gọi lại render() trên cả cây mỗi khung. Ngược với immediate mode, nơi ứng dụng tự vẽ lại từ đầu mỗi khung. Component tự cache kết quả nên phần lớn lời gọi render() chỉ trả về mảng cũ.

Khung hình (frame)

Mảng dòng TUI có được sau bước 5. Khung trước được giữ trong previousLines (regular) hoặc previousScreen (fullscreen).

Viewport, scrollback

Viewport là phần đang hiện trên màn hình, cao bằng số hàng của terminal. Scrollback là lịch sử phía trên viewport mà terminal tự giữ; chương trình không sửa lại được những gì đã trôi vào đó.

Main screen, alternate screen

Terminal có hai bộ đệm. Main screen có scrollback. Alternate screen (bật bằng \x1b[?1049h) là một tấm cố định đúng bằng màn hình, không có scrollback, và khi tắt thì main screen hiện lại nguyên vẹn; vim và less dùng nó.

Synchronized output

Cặp CSI ?2026h / CSI ?2026l (\x1b[?2026h … \x1b[?2026l): terminal hỗ trợ sẽ gom mọi thay đổi ở giữa rồi hiện một lần, nên người dùng không thấy trạng thái vẽ dở. Terminal không hỗ trợ thì bỏ qua cặp mã này.

Vi sai (differential rendering)

Chỉ ghi những dòng (hoặc hàng) khác với khung trước, thay vì vẽ lại toàn bộ.

Các chuỗi điều khiển xuất hiện nhiều nhất trong code:

Data model: Component, Container và TUI#

Component: hợp đồng duy nhất#

Toàn bộ thư viện dựa trên một interface rất nhỏ:

export interface Component {	/**	 * Render the component to lines for the given viewport width	 * @param width - Current viewport width	 * @returns Array of strings, each representing a line	 */	render(width: number): string[];	/** Optional handler for keyboard input when component has focus. */	handleInput?(data: string): void;	/** Optional normalized mouse handler. */	handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;	/**	 * If true, component receives key release events (Kitty protocol).	 * Default is false - release events are filtered out.	 */	wantsKeyRelease?: boolean;	/**	 * Invalidate any cached rendering state.	 * Called when theme changes or when component needs to re-render from scratch.	 */	invalidate(): void;}

• render(width) là bắt buộc và thuần: nhận độ rộng, trả về các dòng. Component không biết mình nằm ở hàng nào trên màn hình, cũng không tự ghi ra terminal. README nhấn mạnh mỗi dòng “must not exceed width or the TUI will error” và khuyên dùng truncateToWidth() (README.md:260). “Độ rộng” ở đây là số cột hiển thị, không phải string.length: visibleWidth() bỏ qua mã ANSI, OSC, APC và tính ký tự CJK, emoji là hai cột (utils.ts:250).
• handleInput(data) nhận dữ liệu thô từ terminal (có thể là một chuỗi escape), chỉ khi component đang giữ focus.
• handleMouse(event) nhận sự kiện chuột đã chuẩn hoá, chỉ ở chế độ fullscreen (mục Overlay, focus và định tuyến input).
• wantsKeyRelease: với giao thức Kitty, terminal báo cả lúc nhả phím; mặc định TUI lọc bỏ các sự kiện này.
• invalidate() bắt buộc: xoá cache để lần render() sau dựng lại từ đầu. Ứng dụng gọi tui.invalidate() (lan xuống cả cây) khi đổi theme; chính TUI gọi khi terminal báo kích thước ô ảnh mới.

Vì sao invalidate() bắt buộc mà không tuỳ chọn? Vì cache là mặc định. Mẫu chuẩn trong README là giữ cachedWidth và cachedLines, trả mảng cũ nếu độ rộng không đổi (README.md:888–915). Một component đã cache chuỗi có mã màu thì khi theme đổi sẽ vẽ màu cũ mãi mãi nếu không có đường xoá cache; tài liệu của coding agent cảnh báo đúng điều này (docs/tui.md:170).

Một hợp đồng ngầm nữa: style không được kéo sang dòng sau. TUI nối \x1b[0m (reset SGR) và \x1b]8;;\x07 (đóng hyperlink OSC 8) vào cuối mọi dòng (tui.ts:1450–1459, README.md:265). Nhờ vậy mỗi dòng độc lập: thuật toán vi sai ghi lại dòng 23 mà không cần biết dòng 22 đã để lại màu gì.

Con trỏ: CURSOR_MARKER và con trỏ giả#

Component trả về chuỗi, không trả về toạ độ. Vậy làm sao TUI biết đặt con trỏ phần cứng ở đâu? Vị trí đó cần cho bộ gõ IME (tiếng Trung, Nhật, Hàn...), vì cửa sổ gợi ý của bộ gõ hiện cạnh con trỏ của terminal. Component chèn một dấu vô hình vào đúng vị trí:

export interface Focusable {	/** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */	focused: boolean;}/** Type guard to check if a component implements Focusable */export function isFocusable(component: Component | null): component is Component & Focusable {	return component !== null && "focused" in component;}/** * Cursor position marker - APC (Application Program Command) sequence. * This is a zero-width escape sequence that terminals ignore. * Components emit this at the cursor position when focused. * TUI finds and strips this marker, then positions the hardware cursor there. */export const CURSOR_MARKER = "\x1b_pi:c\x07";/** Fake cursor markers - zero-width APC sequences around the text drawn as the cursor. See resolveFakeCursors(). */export const FAKE_CURSOR_START = "\x1b_pi:fc\x07";export const FAKE_CURSOR_END = "\x1b_pi:/fc\x07";// CURSOR_MARKER + FAKE_CURSOR_START + text + FAKE_CURSOR_END. Truncating the line right after the cursor cell drops the end.const FOCUSED_FAKE_CURSOR = /(\x1b_pi:c\x07)\x1b_pi:fc\x07(.*?)(?:\x1b_pi:\/fc\x07|$)/s;/** Wrap text in fake cursor markers. */export function renderFakeCursor(text: string): string {	return `${FAKE_CURSOR_START}${text}${FAKE_CURSOR_END}`;}

CURSOR_MARKER là một chuỗi APC (ESC _ … BEL) mà terminal bỏ qua. Mỗi khung, TUI quét dấu này trong các dòng thuộc viewport, tính cột bằng visibleWidth của phần trước dấu, gỡ dấu đi, rồi đặt con trỏ phần cứng ở đó (tui.ts:1479–1497). Con trỏ phần cứng mặc định vẫn ẩn; thứ người dùng thấy là con trỏ giả: ô dưới con trỏ được bọc bởi hai dấu APC khác và TUI đổi chúng thành \x1b[7m/\x1b[27m (video đảo). Khi bật showHardwareCursor, con trỏ giả ngay sau CURSOR_MARKER bị bỏ để chỉ còn con trỏ thật (tui.ts:1504–1510). Cơ chế dấu APC thay cho việc component tự ghi \x1b[7m là thay đổi phá vỡ tương thích của 1.2.0 (CHANGELOG.md:22).

Container: ghép cây#

export class Container implements Component {	children: Component[] = [];	private mouseLayout?: { width: number; children: Array<{ component: Component; height: number }> };	addChild(component: Component): void {		this.children.push(component);	}	removeChild(component: Component): void {		const index = this.children.indexOf(component);		if (index !== -1) {			this.children.splice(index, 1);		}	}	clear(): void {		this.children = [];	}	invalidate(): void {		for (const child of this.children) {			child.invalidate?.();		}	}⋯ lược bớt dòng 382–404	render(width: number): string[] {		const lines: string[] = [];		const mouseChildren: Array<{ component: Component; height: number }> = [];		for (const child of this.children) {			const childLines = child.render(width);			mouseChildren.push({ component: child, height: childLines.length });			for (const line of childLines) {				lines.push(line);			}		}		this.mouseLayout = { width, children: mouseChildren };		return lines;	}}

Đây là toàn bộ “bố cục” ở chế độ regular: xếp dọc, nối mảng. Không có toạ độ, không có lề, không có z-index. Một Container chứa Text, Spacer(1) và Markdown trả về các dòng của Text, rồi một dòng rỗng, rồi các dòng của Markdown. Vòng for thay cho push(...childLines) là có chủ ý: spread một mảng quá dài vượt giới hạn đối số của V8 và gây tràn ngăn xếp ở session dài (CHANGELOG.md:616). Bố cục có chiều cao ràng buộc (VStack, HStack, ScrollView) chỉ có nghĩa ở fullscreen; mục TuiAltScreen giải thích.

TUI: một interface, hai renderer#

export type TuiMode = "regular" | "fullscreen";export interface TuiStopOptions {	/** Leave renderer output in place for another TUI taking over the same terminal. */	preserveScreen?: boolean;}export interface TUI extends Component {	readonly mode: TuiMode;	children: Component[];	terminal: Terminal;	onDebug?: () => void;	readonly fullRedraws: number;	addChild(component: Component): void;	removeChild(component: Component): void;	clear(): void;	getShowHardwareCursor(): boolean;	setShowHardwareCursor(enabled: boolean): void;	getClearOnShrink(): boolean;	setClearOnShrink(enabled: boolean): void;	setFocus(component: Component | null): void;	showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;	hideOverlay(): void;	hasOverlay(): boolean;	start(): void;	stop(options?: TuiStopOptions): void;	renderNow(force?: boolean): void;	requestRender(force?: boolean): void;	addInputListener(listener: TuiInputListener): () => void;	removeInputListener(listener: TuiInputListener): void;	onTerminalColorSchemeChange(listener: (scheme: TerminalColorScheme) => void): () => void;	setTerminalColorSchemeNotifications(enabled: boolean): void;	queryTerminalColors(options: {		timeoutMs: number;		onLateReply?: (colors: TerminalColors) => void;	}): Promise<TerminalColors>;}export const VIEWPORT_TUI = Symbol.for("@earendil-works/pi-tui/viewport");export interface ViewportTUI extends TUI {	readonly [VIEWPORT_TUI]: true;	setLayoutRoot(component: Component | undefined): void;}export function isViewportTUI(tui: TUI): tui is ViewportTUI {	return (tui as Partial<ViewportTUI>)[VIEWPORT_TUI] === true;}

TUI mở rộng Component: bản thân TUI là container gốc (children, addChild). Ngoài ra nó gom các trách nhiệm toàn cục: focus (setFocus), overlay, lắng nghe input thô (addInputListener trả về hàm huỷ), vòng đời (start/stop), lịch render (requestRender/renderNow), và hỏi màu terminal. fullRedraws là bộ đếm số lần vẽ lại toàn bộ, tiện cho test và cho việc đo đạc. ViewportTUI chỉ thêm setLayoutRoot(); hàm isViewportTUI() nhận ra nó qua một khoá Symbol.for(...), tức một symbol trong bảng đăng ký toàn cục, nên phép kiểm tra vẫn đúng với đối tượng tạo từ một bản sao khác của gói.

Hai cài đặt cùng kế thừa một lớp trừu tượng nội bộ, TuiBase (không export). Nó giữ focus, overlay, danh sách input listener và lịch render, còn việc ghi ra terminal được để lại cho lớp con theo kiểu template method:

export abstract class TuiBase extends Container implements TUI {	abstract readonly mode: TuiMode;	public terminal: Terminal;	private focusedComponent: Component | null = null;	private inputListeners = new Set<TuiInputListener>();	/** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */	public onDebug?: () => void;	private renderRequested = false;	private immediateRenderScheduled = false;	private renderTimer: NodeJS.Timeout | undefined;	private lastRenderAt = 0;	private static readonly MIN_RENDER_INTERVAL_MS = 16;	private showHardwareCursor = false;	private clearOnShrink = false;	protected fullRedrawCount = 0;	protected stopped = false;⋯ lược bớt dòng 523–551	protected abstract doRender(): void;	protected resetRenderState(): void {}	protected beforeTerminalStart(): void {}	protected afterTerminalStart(): void {}	protected beforeTerminalStop(_options: TuiStopOptions): void {}	protected afterTerminalStop(_options: TuiStopOptions): void {}

Terminal: thứ duy nhất TUI nói chuyện#

TUI không đụng trực tiếp process.stdout; nó nhận một Terminal:

export interface Terminal {	// Start the terminal with input and resize handlers	start(onInput: (data: string) => void, onResize: () => void): void;	// Stop the terminal and restore state	stop(): void;	/**	 * Synchronously restore terminal modes from a process `exit` handler when stop() did not run.	 * Writes `before`, then this terminal's own mode resets, then `after`.	 */	restoreOnExit?(before: string, after: string): void;	/**	 * Drain stdin before exiting to prevent Kitty key release events from	 * leaking to the parent shell over slow SSH connections.	 * @param maxMs - Maximum time to drain (default: 1000ms)	 * @param idleMs - Exit early if no input arrives within this time (default: 50ms)	 */	drainInput(maxMs?: number, idleMs?: number): Promise<void>;	// Write output to terminal	write(data: string): void;	// Get terminal dimensions	get columns(): number;	get rows(): number;	// Whether Kitty keyboard protocol is active	get kittyProtocolActive(): boolean;	// Cursor positioning (relative to current position)	moveBy(lines: number): void; // Move cursor up (negative) or down (positive) by N lines	// Cursor visibility	hideCursor(): void; // Hide the cursor	showCursor(): void; // Show the cursor	// Clear operations	clearLine(): void; // Clear current line	clearFromCursor(): void; // Clear from cursor to end of screen	clearScreen(): void; // Clear entire screen and move cursor to (0,0)	// Title operations	setTitle(title: string): void; // Set terminal window title	// Progress indicator (OSC 9;4)	setProgress(active: boolean): void;	/**	 * Report what the program is doing (OSC 7501). Sent only to terminals that support it; the latest	 * status is re-sent when support is confirmed or the terminal restarts.	 */	setProgramStatus(status: ProgramStatus): void;}

Interface thật lớn hơn bản trong README: README chỉ liệt kê start, stop, write, kích thước và vài lệnh con trỏ (README.md:757–773), còn code ở v1.4.0 đòi thêm drainInput, kittyProtocolActive, setTitle, setProgress (thanh tiến trình OSC 9;4 trên tab terminal), setProgramStatus (OSC 7501, bắt buộc từ 1.1.0, CHANGELOG.md:44) và restoreOnExit tuỳ chọn. Cài đặt thật là ProcessTerminal; các test dùng một VirtualTerminal dựng trên @xterm/headless (packages/tui/test/virtual-terminal.ts), nhờ đó kiểm tra được chính xác màn hình sau mỗi khung mà không cần terminal thật.

Vòng render: requestRender, nhịp 16 ms và renderNow#

Vấn đề. Khi mô hình stream, các sự kiện message_update tới dồn dập, mỗi sự kiện chỉ mang vài token. Interactive mode gọi ui.requestRender() sau mỗi sự kiện. Nếu mỗi lời gọi là một lần vẽ, phần lớn công sức là vẽ những khung không ai kịp thấy. Ngược lại, khi người dùng gõ phím, độ trễ dù 16 ms cũng cảm nhận được.

Giải pháp. TuiBase có ba lối vào và một bộ hẹn giờ:

renderNow(force = false): void {	if (force) this.resetRenderState();	this.renderRequested = false;	this.cancelRenderTimer();	this.lastRenderAt = performance.now();	this.doRender();}requestRender(force = false): void {	if (force) {		this.resetRenderState();		this.requestImmediateRender();		return;	}	if (this.renderRequested) return;	this.renderRequested = true;	process.nextTick(() => this.scheduleRender());}private requestImmediateRender(): void {	this.cancelRenderTimer();	this.renderRequested = true;	if (this.immediateRenderScheduled) return;	this.immediateRenderScheduled = true;	process.nextTick(() => {		this.immediateRenderScheduled = false;		if (this.stopped || !this.renderRequested) return;		// A previously queued scheduleRender() can create a timer before this		// callback runs. User input must preempt that throttled frame.		this.cancelRenderTimer();		this.renderRequested = false;		this.lastRenderAt = performance.now();		this.doRender();	});}

private scheduleRender(): void {	if (this.stopped || this.renderTimer || !this.renderRequested) {		return;	}	const elapsed = performance.now() - this.lastRenderAt;	const delay = Math.max(0, TuiBase.MIN_RENDER_INTERVAL_MS - elapsed);	this.renderTimer = setTimeout(() => {		this.renderTimer = undefined;		if (this.stopped || !this.renderRequested) {			return;		}		this.renderRequested = false;		this.lastRenderAt = performance.now();		this.doRender();		if (this.renderRequested) {			this.scheduleRender();		}	}, delay);}

1. requestRender()Đặt cờ renderRequested; nếu cờ đã bật thì không làm gì. Lời xin đầu tiên hẹn scheduleRender() ở process.nextTick, nên mọi lời xin trong cùng một lượt xử lý đồng bộ gộp thành một.
2. scheduleRender()Tính thời gian từ khung trước; nếu chưa đủ 16 ms thì setTimeout cho phần còn thiếu, đủ rồi thì hẹn 0 ms. Trong lúc chờ, mọi requestRender() đều rơi vào cờ đã bật. Sau khi vẽ, nếu trong lúc vẽ có ai xin thêm, nó tự hẹn khung tiếp theo.
3. requestImmediateRender()Đường nhanh cho input: huỷ bộ hẹn giờ đang chờ và vẽ ở nextTick. handleTerminalInput() gọi nó ngay sau khi component đang focus xử lý phím (tui.ts:1145–1156). Chú thích ghi lý do: trên Windows ngay cả setTimeout(0) có thể mất trọn một nhịp 16 ms (CHANGELOG 0.84.0, CHANGELOG.md:268).
4. renderNow() và forcerenderNow() vẽ đồng bộ ngay. force = true gọi resetRenderState() trước, xoá khung trước nên khung kế tiếp là vẽ lại toàn bộ. Interactive mode dùng requestRender(true) sau khi quay lại từ Ctrl+Z (SIGCONT) và từ trình soạn thảo ngoài, vì lúc đó không còn biết màn hình đang hiện gì (interactive-mode.ts:4424–4428).

Cách gộp theo nhịp 16 ms (khoảng 60 khung mỗi giây) có từ 0.65.2, để sửa việc vẽ dồn dập khi stream nhiều (CHANGELOG.md:628). Hệ quả cho người viết component: gọi requestRender() thoải mái, nó rẻ; đừng tự gọi renderNow() trong vòng lặp nóng.

start() và stop()#

start() (tui.ts:950–966) đăng ký một handler cho sự kiện exit của tiến trình, gọi hook beforeTerminalStart() (fullscreen vào alternate screen ở đây), bật terminal với hai callback: input đi vào handleTerminalInput(), resize chỉ là một requestRender(). Rồi nó ẩn con trỏ, hỏi kích thước ô bằng pixel nếu terminal vẽ được ảnh (CSI 16 t), và xin khung đầu tiên. Handler exit là lưới an toàn của 1.4.0: nếu tiến trình gọi thẳng process.exit() mà không qua stop(), nó vẫn ghi đồng bộ các mã tắt chế độ chuột, bàn phím Kitty, bracketed paste và alternate screen, để shell của người dùng không bị kẹt (tui.ts:574–585, CHANGELOG.md:13). stop() làm ngược lại theo cùng khung: gỡ handler, huỷ bộ hẹn giờ render, gọi beforeTerminalStop(), hiện con trỏ, dừng terminal, rồi afterTerminalStop() (tui.ts:1006–1017).

Phía terminal, ProcessTerminal.start() làm phần việc với hệ điều hành:

start(onInput: (data: string) => void, onResize: () => void): void {	this.inputHandler = onInput;	this.resizeHandler = onResize;	// Save previous state and enable raw mode	this.wasRaw = process.stdin.isRaw || false;	if (process.stdin.setRawMode) {		process.stdin.setRawMode(true);	}	process.stdin.setEncoding("utf8");	process.stdin.resume();	// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~	process.stdout.write("\x1b[?2004h");	// Set up resize handler immediately	process.stdout.on("resize", this.resizeHandler);	// Refresh terminal dimensions - they may be stale after suspend/resume	// (SIGWINCH is lost while process is stopped). Unix only, best-effort.	refreshTerminalDimensions();	// On Windows, enable ENABLE_VIRTUAL_TERMINAL_INPUT so the console sends	// VT escape sequences (e.g. \x1b[Z for Shift+Tab) instead of raw console	// events that lose modifier information. Must run AFTER setRawMode(true)	// since that resets console mode flags.	this.enableWindowsVTInput();	// Query Kitty keyboard protocol and fall back to modifyOtherKeys when DA confirms no Kitty response.	// See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/	this.queryAndEnableKittyProtocol();}

Raw mode tắt việc terminal tự xử lý dòng: mỗi phím tới ngay, và Ctrl+C không còn phát SIGINT mà thành byte \x03 cho ứng dụng tự quyết (README nhắc điều này trong ví dụ đầu tiên, README.md:43). Bracketed paste (\x1b[?2004h) bảo terminal bọc nội dung dán trong \x1b[200~ … \x1b[201~, nhờ đó editor phân biệt được dán với gõ. Lệnh gửi SIGWINCH cho chính mình làm mới kích thước sau khi tiến trình bị tạm dừng rồi chạy lại, vì tín hiệu resize bị mất trong lúc dừng. Thương lượng bàn phím được trình bày ở mục Phân tích phím.

Thuật toán vi sai của TuiMainScreen#

Vấn đề. Ở chế độ regular, pi viết vào main screen như mọi chương trình dòng lệnh: nội dung cũ trôi lên scrollback, người dùng cuộn bằng con lăn của terminal và chọn chữ bằng chuột của terminal. TUI chỉ thật sự kiểm soát phần đuôi tài liệu đang nằm trong viewport. Nó phải tự nhớ con trỏ đang đứng ở dòng nào của tài liệu và viewport bắt đầu từ dòng nào, rồi di chuyển con trỏ một cách tương đối (lên, xuống n dòng), vì trên main screen hàng màn hình của một dòng tài liệu thay đổi mỗi khi nội dung cuộn.

export interface TuiMainScreenRenderState {	previousLines: string[];	previousWidth: number;	previousHeight: number;	cursorRow: number;	hardwareCursorRow: number;	maxLinesRendered: number;	previousViewportTop: number;}/** TUI implementation that renders into the terminal's main screen and scrollback. */export class TuiMainScreen extends TuiBase implements TUI {	readonly mode = "regular" as const;	private previousLines: string[] = [];	private previousKittyImageIds = new Set<number>();	private previousWidth = 0;	private previousHeight = 0;	private cursorRow = 0;	private hardwareCursorRow = 0;	private maxLinesRendered = 0;	private previousViewportTop = 0;

• previousLines: khung trước, gồm cả tài liệu chứ không chỉ phần đang hiện, ở dạng đã nối reset.
• previousViewportTop: chỉ số của dòng tài liệu đang nằm ở hàng trên cùng màn hình.
• hardwareCursorRow: dòng tài liệu mà con trỏ terminal đang thật sự đứng; mọi lệnh di chuyển tính từ đây. cursorRow là dòng cuối của nội dung.
• maxLinesRendered: mức cao nhất của “vùng làm việc”, chỉ dùng cho tuỳ chọn clearOnShrink.
• previousKittyImageIds: id các ảnh Kitty đang hiện, để xoá khi dòng chứa chúng đổi.

Cặp captureRenderState()/restoreRenderState() chuyển state này sang một renderer mới khi interactive mode đổi qua lại giữa regular và fullscreen lúc đang chạy (tui-main-screen.ts:135–156; mục Interactive mode).

Chuẩn bị khung#

protected doRender(): void {	if (this.stopped) return;	const width = this.terminal.columns;	const height = this.terminal.rows;	const widthChanged = this.previousWidth !== 0 && this.previousWidth !== width;	const heightChanged = this.previousHeight !== 0 && this.previousHeight !== height;	const previousBufferLength = this.previousHeight > 0 ? this.previousViewportTop + this.previousHeight : height;	let prevViewportTop = heightChanged ? Math.max(0, previousBufferLength - height) : this.previousViewportTop;	let viewportTop = prevViewportTop;	let hardwareCursorRow = this.hardwareCursorRow;	const computeLineDiff = (targetRow: number): number => {		const currentScreenRow = hardwareCursorRow - prevViewportTop;		const targetScreenRow = targetRow - viewportTop;		return targetScreenRow - currentScreenRow;	};	// Render all components to get new lines	// Resolve fake cursors before compositing so overlays and line slicing see plain SGR codes	let newLines = this.resolveFakeCursors(this.render(width));	// Composite overlays into the rendered lines (before differential compare)	if (this.hasOverlayEntries) {		newLines = this.compositeOverlays(newLines, width, height);	}	// Extract cursor position before applying line resets (marker must be found first)	const cursorPos = this.extractCursorPosition(newLines, height);	newLines = this.applyLineResets(newLines);

computeLineDiff(targetRow) đổi cả hai đầu sang toạ độ màn hình (dòng tài liệu trừ dòng đầu viewport) rồi lấy hiệu: con trỏ đang ở hàng màn hình 8, cần tới hàng 5, thì kết quả là −3 và TUI ghi \x1b[3A. Thứ tự chuẩn bị có ý nghĩa. Overlay được ghép vào trước khi so sánh, nên với thuật toán, một hộp thoại nổi chỉ là vài dòng đổi nội dung. Dấu con trỏ phải được tìm trước khi nối reset, vì sau bước đó vị trí của nó trong chuỗi không còn ý nghĩa.

Chuỗi quyết định#

// First render - just output everything without clearing (assumes clean screen)if (this.previousLines.length === 0 && !widthChanged && !heightChanged) {	logRedraw("first render");	fullRender(false);	return;}// Width changes always need a full re-render because wrapping changes.if (widthChanged) {	logRedraw(`terminal width changed (${this.previousWidth} -> ${width})`);	fullRender(true);	return;}// Height changes normally need a full re-render to keep the visible viewport aligned,// but Termux changes height when the software keyboard shows or hides.// In that environment, a full redraw causes the entire history to replay on every toggle.if (heightChanged && !isTermuxSession()) {	logRedraw(`terminal height changed (${this.previousHeight} -> ${height})`);	fullRender(true);	return;}// Content shrunk below the working area and no overlays - re-render to clear empty rows// (overlays need the padding, so only do this when no overlays are active)// Configurable via setClearOnShrink()if (this.getClearOnShrink() && newLines.length < this.maxLinesRendered && !this.hasOverlayEntries) {	logRedraw(`clearOnShrink (maxLinesRendered=${this.maxLinesRendered})`);	fullRender(true);	return;}

Lịch sử của dòng “chiều cao đổi” cho thấy đây là thoả hiệp chứ không phải chân lý. Ở 0.51.1, đổi chiều cao thôi không vẽ lại toàn bộ để bớt nhấp nháy (CHANGELOG.md:904); ở 0.62.0 lại bật lại vì editor và footer bị lệch khi resize (CHANGELOG.md:778); ngoại lệ Termux có sau đó.

Vẽ lại toàn bộ#

const fullRender = (clear: boolean): void => {	this.fullRedrawCount += 1;	const output = new BoundedTerminalWriter((data) => this.terminal.write(data));	output.append("\x1b[?2026h"); // Begin synchronized output	if (clear) {		output.append(this.deleteKittyImages(this.previousKittyImageIds));		output.append("\x1b[2J\x1b[H\x1b[3J"); // Clear screen, home, then clear scrollback	}	for (let i = 0; i < newLines.length; i++) {		if (i > 0) output.append("\r\n");		const line = newLines[i];⋯ lược bớt dòng 289–300		output.append(line);	}	output.append("\x1b[?2026l"); // End synchronized output	output.flush();	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;	} else {		this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);	}	const bufferLength = Math.max(height, newLines.length);	this.previousViewportTop = Math.max(0, bufferLength - height);	this.positionHardwareCursor(cursorPos, newLines.length);	this.previousLines = newLines;	this.previousKittyImageIds = this.collectKittyImageIds(newLines);	this.previousWidth = width;	this.previousHeight = height;};

\x1b[2J\x1b[H\x1b[3J xoá màn hình, đưa con trỏ về góc trên trái, rồi xoá scrollback; sau đó toàn bộ tài liệu được in lại. Ở một session dài, đó là hàng nghìn dòng. BoundedTerminalWriter chia đầu ra thành từng khúc 1 MiB và không cắt đôi cặp surrogate UTF-16, để một lần vẽ lớn không bao giờ dựng ra một chuỗi vượt giới hạn độ dài chuỗi của V8 (tui-main-screen.ts:9–17).

Một chi tiết nhỏ quyết định nhánh nào được chọn: resetRenderState() đặt previousWidth = -1 chứ không phải 0 (tui-main-screen.ts:158–166). TUI mới tạo có previousWidth = 0, được hiểu là “chưa vẽ lần nào” và đi vào nhánh khung đầu tiên không xoá màn hình. Còn sau requestRender(true), giá trị −1 khác mọi độ rộng thật nên được hiểu là “độ rộng đổi”, đi vào nhánh có xoá.

Tìm vùng thay đổi#

// Find first and last changed lineslet firstChanged = -1;let lastChanged = -1;const maxLines = Math.max(newLines.length, this.previousLines.length);for (let i = 0; i < maxLines; i++) {	const oldLine = i < this.previousLines.length ? this.previousLines[i] : "";	const newLine = i < newLines.length ? newLines[i] : "";	if (oldLine !== newLine) {		if (firstChanged === -1) {			firstChanged = i;		}		lastChanged = i;	}}const appendedLines = newLines.length > this.previousLines.length;if (appendedLines) {	if (firstChanged === -1) {		firstChanged = this.previousLines.length;	}	lastChanged = newLines.length - 1;}if (firstChanged !== -1) {	const expandedRange = this.expandChangedRangeForKittyImages(firstChanged, lastChanged, newLines);	firstChanged = expandedRange.firstChanged;	lastChanged = expandedRange.lastChanged;}const appendStart = appendedLines && firstChanged === this.previousLines.length && firstChanged > 0;

Phép so sánh là so chuỗi tại cùng chỉ số, không có thuật toán dãy con chung dài nhất kiểu diff. Nếu một dòng được chèn vào giữa, mọi dòng bên dưới lệch đi một chỉ số và đều bị coi là đổi. Cách đơn giản này chấp nhận được nhờ quy tắc ở mục sau: firstChanged không được nằm trên viewport, nên đoạn phải ghi lại không bao giờ dài hơn một màn hình cộng số dòng mới. appendStart đánh dấu trường hợp chỉ có dòng nối thêm ở cuối, không dòng cũ nào đổi.

Hai lối tắt và một lối ra#

// No changes - but still need to update hardware cursor position if it movedif (firstChanged === -1) {	this.positionHardwareCursor(cursorPos, newLines.length);	this.previousViewportTop = prevViewportTop;	this.previousHeight = height;	return;}⋯ lược bớt dòng 399–449// Differential rendering can only touch what was actually visible.// If the first changed line is above the previous viewport, we need a full redraw.if (firstChanged < prevViewportTop) {	logRedraw(`firstChanged < viewportTop (${firstChanged} < ${prevViewportTop})`);	fullRender(true);	return;}

Kiểm tra ở dòng 452 là giới hạn căn bản của chế độ regular. Những dòng đã trôi vào scrollback thuộc về terminal. Không có lệnh di chuyển tương đối nào với tới chúng, và nếu có cũng không an toàn vì người dùng có thể đang cuộn xem. Cách duy nhất để sửa là xoá sạch và in lại.

Ghi phần thay đổi#

// Render from first changed line to end// Keep updates wrapped in synchronized output while writing bounded chunks.const output = new BoundedTerminalWriter((data) => this.terminal.write(data));output.append("\x1b[?2026h"); // Begin synchronized outputoutput.append(this.deleteChangedKittyImages(firstChanged, lastChanged));const prevViewportBottom = prevViewportTop + height - 1;const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;if (moveTargetRow > prevViewportBottom) {	const currentScreenRow = Math.max(0, Math.min(height - 1, hardwareCursorRow - prevViewportTop));	const moveToBottom = height - 1 - currentScreenRow;	if (moveToBottom > 0) {		output.append(`\x1b[${moveToBottom}B`);	}	const scroll = moveTargetRow - prevViewportBottom;	output.append("\r\n".repeat(scroll));	prevViewportTop += scroll;	viewportTop += scroll;	hardwareCursorRow = moveTargetRow;}// Move cursor to first changed line (use hardwareCursorRow for actual position)const lineDiff = computeLineDiff(moveTargetRow);if (lineDiff > 0) {	output.append(`\x1b[${lineDiff}B`); // Move down} else if (lineDiff < 0) {	output.append(`\x1b[${-lineDiff}A`); // Move up}output.append(appendStart ? "\r\n" : "\r"); // Move to column 0// Only render changed lines (firstChanged to lastChanged), not all lines to end// This reduces flicker when only a single line changes (e.g., spinner animation)const renderEnd = Math.min(lastChanged, newLines.length - 1);for (let i = firstChanged; i <= renderEnd; i++) {	if (i > firstChanged) output.append("\r\n");	const line = newLines[i];	const isImage = isImageLine(line);⋯ lược bớt dòng 495–516	output.append("\x1b[2K"); // Clear current line⋯ lược bớt dòng 518–545	output.append(line);}

• Cuộn trước nếu cần (465–476). Nếu dòng đích nằm dưới đáy viewport cũ, TUI xuống hàng cuối rồi ghi đủ số \r\n để terminal cuộn. Lệnh CSI n B không làm màn hình cuộn khi con trỏ đã ở hàng cuối; chỉ ký tự xuống dòng mới làm được.
• Dòng nối thêm (464, 486). Cùng lý do: khi chỉ có dòng mới ở cuối, TUI đứng ở dòng ngay trước rồi ghi \r\n, chứ không “di chuyển xuống” một dòng chưa tồn tại.
• Ghi đè (517, 546). Mỗi dòng: \x1b[2K xoá cả hàng, rồi in nội dung mới. Nhờ xoá trước, TUI không cần biết dòng cũ dài bao nhiêu.
• Dừng ở lastChanged (488–490). Chú thích trong code ghi rõ: chỉ ghi các dòng đổi để giảm nhấp nháy khi chỉ một dòng giữa màn hình đổi, ví dụ spinner.

Dọn dòng thừa và ghi sổ#

// Track where cursor ended up after renderinglet finalCursorRow = renderEnd;// If we had more lines before, clear them and move cursor backif (this.previousLines.length > newLines.length) {	// Move to end of new content first if we stopped before it	if (renderEnd < newLines.length - 1) {		const moveDown = newLines.length - 1 - renderEnd;		output.append(`\x1b[${moveDown}B`);		finalCursorRow = newLines.length - 1;	}	const extraLines = this.previousLines.length - newLines.length;	for (let i = newLines.length; i < this.previousLines.length; i++) {		output.append("\r\n\x1b[2K");	}	// Move cursor back to end of new content	output.append(`\x1b[${extraLines}A`);}output.append("\x1b[?2026l"); // End synchronized output⋯ lược bớt dòng 569–600// Track cursor position for next render// cursorRow tracks end of content (for viewport calculation)// hardwareCursorRow tracks actual terminal cursor position (for movement)this.cursorRow = Math.max(0, newLines.length - 1);this.hardwareCursorRow = finalCursorRow;// Track terminal's working area (grows but doesn't shrink unless cleared)this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);this.previousViewportTop = Math.max(prevViewportTop, finalCursorRow - height + 1);// Position hardware cursor for IMEthis.positionHardwareCursor(cursorPos, newLines.length);this.previousLines = newLines;this.previousKittyImageIds = this.collectKittyImageIds(newLines);this.previousWidth = width;this.previousHeight = height;

Dòng 608 là chỗ TUI “theo dõi” cú cuộn mà chính nó gây ra: nếu con trỏ đã xuống quá đáy viewport cũ thì terminal đã cuộn, nên dòng đầu viewport mới là finalCursorRow - height + 1. Cuối cùng positionHardwareCursor() đưa con trỏ terminal tới chỗ CURSOR_MARKER, bằng CSI A/B cho hàng và CSI G (cột tuyệt đối) cho cột, rồi ghi lại hardwareCursorRow (tui-main-screen.ts:624–655). Lệnh này được ghi sau khi đã đóng synchronized output. Vì vậy sau mỗi khung, con trỏ terminal đứng ở ô soạn thảo chứ không ở cuối nội dung, và khung tiếp theo bắt đầu tính đường đi từ đó.

Trace: tin nhắn đang stream dài thêm một dòng#

Giờ ghép các mảnh lại trong một kịch bản cụ thể ở chế độ regular. Terminal rộng 40 cột, cao 12 hàng. Session đã có hơn một màn hình nội dung; mô hình đang stream một đoạn văn, và token vừa tới làm đoạn văn xuống thêm một dòng. Các con số bên dưới là ví dụ minh hoạ, nhưng mỗi bước đi đúng nhánh code đã trích ở mục trước.

1. Từ token tới requestRender()#

1. message_updateAgentSession phát sự kiện mang assistant message từng phần (xem chương AgentSession). InteractiveMode.handleEvent() lưu message và gọi streamingComponent.updateContent(message, true) (interactive-mode.ts:3481–3484).
2. updateContent()AssistantMessageComponent xoá container nội dung rồi dựng lại: một Spacer(1), rồi một Markdown mới cho mỗi khối text (assistant-message.ts:95–117). Chưa có byte nào ra terminal; chỉ có cây đổi.
3. requestRender()handleEvent() gọi ui.requestRender() (:3513). Giả sử khung trước mới vẽ cách đây 5 ms: scheduleRender() hẹn 11 ms. Những message_update tới trong 11 ms đó chỉ thay cây, không thêm khung nào.
4. doRender()Bộ hẹn giờ chạy; TuiMainScreen.doRender() gọi render(40) trên cả cây.

2. render() trả về gì#

Gốc là chính TUI, một container với bảy con: tài liệu (header, danh sách tài nguyên, chat), tin nhắn chờ, trạng thái, widget phía trên, editor, widget phía dưới, footer (mục Interactive mode). Khi đang stream, tin nhắn chờ và trạng thái rỗng (chỉ báo “working” được nhúng vào viền trên của editor), widget phía trên là một Spacer(1), editor ba dòng, footer hai dòng. AssistantMessageComponent.render() còn gắn dấu OSC 133 vào dòng đầu (A) và dòng cuối (B, C) của tin nhắn không có tool call (assistant-message.ts:80–89). Đuôi của hai khung:

Ví dụ minh hoạ: đuôi khung trước (30 dòng) và khung mới (31 dòng), 40 × 12

dòng   khung trước                         khung mới
 18    nội dung cũ   (hàng 0 màn hình)     nội dung cũ
 ..    ...                                 ...
 21    [A] dòng trống đầu tin nhắn         [A] dòng trống đầu tin nhắn
 22    " Hàm render() trả về một mảng"     " Hàm render() trả về một mảng"
 23    [B][C] " chuỗi, mỗi chuỗi là"       " chuỗi, mỗi chuỗi là một dòng"    đổi
 24    Spacer của widget                   [B][C] " đã cắt vừa độ rộng."      đổi
 25    viền trên editor ── ⠋ Working       Spacer của widget                  đổi
 26    ‸ dòng nhập (CURSOR_MARKER)         viền trên editor ── ⠙ Working      đổi
 27    viền dưới editor                    ‸ dòng nhập (CURSOR_MARKER)        đổi
 28    footer: thư mục, nhánh git          viền dưới editor                   đổi
 29    footer: token, ngữ cảnh (hàng 11)  footer: thư mục, nhánh git         đổi
 30                                        footer: token, ngữ cảnh            mới

[A] = \x1b]133;A\x07      [B][C] = \x1b]133;B\x07\x1b]133;C\x07
mỗi dòng Markdown được đệm dấu cách đủ 40 cột; mỗi dòng kết thúc bằng \x1b[0m\x1b]8;;\x07

3. Thuật toán quyết định#

4. Byte ghi ra#

Ví dụ minh hoạ: ba lần ghi ra stdout (ESC viết là \x1b, R = \x1b[0m\x1b]8;;\x07)

lần 1: BoundedTerminalWriter, một khúc
\x1b[?2026h                                bắt đầu synchronized output
\x1b[3A\r                                  từ dòng 26 lên dòng 23, cột 0
\x1b[2K" chuỗi, mỗi chuỗi là một dòng"…R    dòng 23 ở hàng màn hình 5
\r\n\x1b[2K[B][C]" đã cắt vừa độ rộng."…R   dòng 24, hàng 6
\r\n\x1b[2KR                               dòng 25, Spacer
\r\n\x1b[2K── ⠙ Working ───…R                dòng 26, hàng 8
\r\n\x1b[2K\x1b[7m \x1b[27m + 39 dấu cách R   dòng 27, con trỏ giả
\r\n\x1b[2K────…R                           dòng 28
\r\n\x1b[2K(footer: thư mục)R               dòng 29, hàng 11, hàng cuối
\r\n\x1b[2K(footer: token)R                 dòng 30: \r\n ở hàng cuối làm terminal
                                           cuộn lên một hàng; dòng 18 vào scrollback
\x1b[?2026l                                kết thúc synchronized output

lần 2: positionHardwareCursor()
\x1b[3A\x1b[1G                              từ dòng 30 lên dòng 27, cột 1
lần 3
\x1b[?25l                                  con trỏ phần cứng vẫn ẩn

5. Sau khung#

Giả sử trong cùng khung đó còn có một thay đổi ở dòng 10, ví dụ người dùng vừa bấm phím mở rộng output của tool, hay một hàng tool đã trôi lên trên viewport đổi nội dung. Khi đó firstChanged = 10 < 18 và TUI đi nhánh vẽ lại toàn bộ: \x1b[?2026h, \x1b[2J\x1b[H\x1b[3J, cả 31 dòng nối bằng \r\n, \x1b[?2026l. Với 31 dòng thì rẻ; với một session năm nghìn dòng thì terminal phải nhận lại cả năm nghìn dòng, và trên terminal không hỗ trợ synchronized output người dùng thấy lịch sử chạy lại.

TuiAltScreen: chế độ toàn màn hình#

Từ 1.0.0, interactive mode chạy fullscreen mặc định; muốn giữ scrollback như cũ thì đặt tuiMode là "regular" hoặc chạy --tui-mode regular (coding-agent CHANGELOG.md:328, :345). Chế độ này dùng TuiAltScreen, và khác TuiMainScreen ở ba điểm căn bản. Khung hình không còn là cả tài liệu mà đúng height hàng. Màn hình được vẽ bằng toạ độ tuyệt đối. Và vì alternate screen không có scrollback, không có gì bị “đóng băng”: dòng nào của tài liệu cũng vẽ lại được bất cứ lúc nào.

Vào và ra alternate screen#

const term = process.env.TERM?.toLowerCase() ?? "";// Multiplexers can lag when every pointer movement is forwarded. Button-motion// tracking preserves clicks, wheel events, selections, and scrollbar dragging.const mouseSequence =	process.env.TMUX !== undefined ||	process.env.ZELLIJ !== undefined ||	process.env.STY !== undefined ||	term.startsWith("tmux") ||	term.startsWith("screen")		? ENABLE_BUTTON_MOTION_MOUSE		: ENABLE_ALL_MOTION_MOUSE;this.terminal.write(	`${ENTER_ALT_SCREEN}${DISABLE_AUTOWRAP}${this.mouseEnabled ? mouseSequence : ""}\x1b[2J\x1b[H\x1b[?25l`,);

Giá trị của các hằng nằm ở đầu file (tui-alt-screen.ts:63–77). Mã chuột gồm 1000 (nhấn và nhả), 1002 (kéo khi giữ nút), 1003 (mọi chuyển động), 1004 (terminal báo được hay mất focus bằng \x1b[I/\x1b[O) và 1006 (toạ độ dạng SGR, không giới hạn 223 cột như dạng cũ). Dưới tmux, Zellij hay GNU Screen, TUI bỏ 1003 vì chuyển tiếp mọi chuyển động chuột làm các multiplexer này chậm (CHANGELOG.md:233). Tắt autowrap (\x1b[?7l) để việc ghi kín cột cuối không làm terminal tự xuống dòng và cuộn. Cũng trong hook này, nếu terminal là iTerm2 thì khả năng vẽ ảnh bị tạm tắt: giao thức ảnh của iTerm2 không xoá hay cắt được một ảnh đã đặt, nên khi viewport cuộn ảnh cũ sẽ đè lên chữ mới (tui-alt-screen.ts:356–360, README.md:688).

protected override afterTerminalStop(options: TuiStopOptions): void {	if (!this.altScreenActive) return;	this.altScreenActive = false;	if (options.preserveScreen) {		this.terminal.write(`${BEGIN_SYNCHRONIZED_OUTPUT}${EXIT_ALT_SCREEN}\x1b[?25h${END_SYNCHRONIZED_OUTPUT}`);	} else {		const width = Math.max(1, this.terminal.columns);		const documentLines = this.resolveFakeCursors(this.render(width)).map((line) =>			line.replace(OSC133_ZONE_PREFIX, ""),		);		this.lastDocument = this.applyLineResets(documentLines.map((line) => line.replaceAll(CURSOR_MARKER, ""))).map(			(line) => (isImageLine(line) || visibleWidth(line) <= width ? line : sliceByColumn(line, 0, width, true)),		);		let buffer = `${BEGIN_SYNCHRONIZED_OUTPUT}${EXIT_ALT_SCREEN}${DISABLE_AUTOWRAP}`;		for (let row = 0; row < this.lastDocument.length; row++) {			if (row > 0) buffer += "\r\n";			buffer += `\r\x1b[2K${this.lastDocument[row] ?? ""}`;		}		buffer += `\x1b[0m${ENABLE_AUTOWRAP}\r\n\x1b[?25h${END_SYNCHRONIZED_OUTPUT}`;		this.terminal.write(buffer);	}

Khi thoát, alternate screen biến mất cùng nội dung của nó. Để nội dung không mất khỏi terminal, mặc định TuiAltScreen render cả cây một lần nữa ở dạng tài liệu không giới hạn chiều cao (gỡ dấu OSC 133 và dấu con trỏ), rồi in vào main screen (README.md:62); gọi stop({ preserveScreen: true }) thì bỏ bước này. Coding agent dùng đúng lựa chọn đó: nó dừng TuiAltScreen mà giữ màn hình, chuyển hẳn sang một TuiMainScreen, và để renderer này in transcript; nếu phiên từng chạy ở regular rồi mới chuyển sang fullscreen, state vi sai đã chụp giúp phần in trước đó ở main screen không bị in lặp (mục Interactive mode).

Bố cục: VStack, HStack, ScrollView#

Ở chế độ regular, bố cục là phép nối dọc vô hạn và terminal lo việc cuộn. Ở fullscreen, ứng dụng phải nói vùng nào được bao nhiêu hàng, vùng nào cuộn được. pi-tui có ba component bố cục, chỉ có nghĩa đầy đủ trên ViewportTUI (README.md:121). Chúng tự khai báo bằng một phương thức đặt tên bằng symbol LAYOUT_NODE, trả về một nút bố cục: vstack/hstack với danh sách mục, hoặc scroll với một con duy nhất (layout-node.ts:10–42). Mỗi mục của stack có basis, grow, shrink, minSize, maxSize và visible, như flexbox thu gọn; allocateStackSizes() chia chỗ theo trọng số (stack.ts:135–154). Bố cục của coding agent:

export function createChatViewport(options: ChatViewportOptions): ChatViewport {	const transcript = new ScrollView(options.document, {		follow: "end",		primary: true,		overscroll: "chain",		scrollbar: options.scrollbar ?? "auto",		...(options.scrollbarTrackStyle === undefined ? {} : { scrollbarTrackStyle: options.scrollbarTrackStyle }),		...(options.scrollbarThumbStyle === undefined ? {} : { scrollbarThumbStyle: options.scrollbarThumbStyle }),	});	const dock = new VStack([		{ component: options.pendingMessages, shrink: 1, minSize: 0 },		{ component: options.status, shrink: 1, minSize: 0 },		...(options.widgetsAbove === undefined ? [] : [{ component: options.widgetsAbove, shrink: 1, minSize: 0 }]),		{ component: options.editor, shrink: 1, minSize: 3 },		...(options.widgetsBelow === undefined ? [] : [{ component: options.widgetsBelow, shrink: 1, minSize: 0 }]),		{ component: options.footer, shrink: 1, minSize: 0 },	]);	return {		transcript,		root: new VStack([			{ component: transcript, basis: 0, grow: 1, shrink: 1, minSize: 1 },			{ component: dock, basis: "auto", grow: 0, shrink: 1, minSize: 1 },		]),	};}

Transcript có basis: 0, grow: 1: nó lấy mọi hàng còn lại. Dock (tin nhắn chờ, trạng thái, widget, editor, footer) có basis: "auto": nó cao đúng bằng nội dung, và mỗi phần có thể co lại, riêng editor không dưới ba hàng. ScrollView của transcript là primary, tức là nơi nhận phím cuộn và con lăn khi con trỏ chuột không nằm trên vùng cuộn nào khác, với follow: "end": dính đáy khi đang ở đáy.

if (node.type === "scroll") {	const previousScrollTop = node.state.scrollTop;	const contentWidth = node.state.getContentWidth(safeWidth);	const childBox = layoutComponent(		context,		node.component,		x,		y - previousScrollTop,		contentWidth,		undefined,		clip,	);	const contentHeight = childBox.rect.height;	const viewportHeight = height === undefined ? contentHeight : Math.max(0, Math.floor(height));	node.state.updateLayout(contentHeight, viewportHeight, context.requestRender);	translateBox(childBox, previousScrollTop - node.state.scrollTop);	const scrollView = node.state as ScrollView;	if (node.state.primary || !context.primaryScrollView) context.primaryScrollView = scrollView;	const rect = { x, y, width: safeWidth, height: viewportHeight };	const childClip = intersect(clip, rect);	const box: LayoutBox = {		component,		rect,		clip: childClip,		children: [childBox],		scrollView,		scrollContentLines: renderCached(context, node.component, contentWidth),		layer: 0,	};	childBox.parent = box;	updateClips(childBox, childClip);	return box;

Con của ScrollView được bố trí với chiều cao không giới hạn tại toạ độ y - scrollTop. Biết chiều cao nội dung rồi, updateLayout() quyết định scrollTop mới, và cây con được dịch theo độ chênh:

updateLayout(contentHeight: number, viewportHeight: number, requestRender: () => void): void {	this.contentHeight = Math.max(0, Math.floor(contentHeight));	this.currentViewportHeight = Math.max(0, Math.floor(viewportHeight));	this.requestRenderCallback = requestRender;	const maxScrollTop = Math.max(0, this.contentHeight - this.currentViewportHeight);	if (this.followingEnd) this.currentScrollTop = maxScrollTop;	else this.currentScrollTop = Math.max(0, Math.min(this.currentScrollTop, maxScrollTop));	if (this.currentScrollTop < maxScrollTop) this.followSuppressedAtEnd = false;	if (this.followEnd && this.currentScrollTop === maxScrollTop && !this.followSuppressedAtEnd) {		this.followingEnd = true;	}	if (this.contentHeight <= this.currentViewportHeight) this.hideTransientScrollbar();}

Đây là toàn bộ cơ chế “tự cuộn theo output khi đang ở đáy, giữ nguyên chỗ khi người dùng đã cuộn lên” mà README mô tả (README.md:751). Cuộn lên bằng con lăn gọi scrollBy(), hàm này tắt followingEnd nếu vị trí mới không phải đáy, và trả về phần delta chưa dùng để chuyển tiếp cho ScrollView bao ngoài (scroll-view.ts:148–162).

renderLayoutFrame() dựng một cây LayoutBox (toạ độ, vùng cắt, các dòng của từng component) rồi sơn nó vào đúng height chuỗi (layout.ts:379–408). Mỗi khung có một cache render riêng, nên mỗi component được render tối đa một lần cho mỗi độ rộng (layout.ts:68–81); cache dài hạn vẫn là cache bên trong component. Khi sơn, một hộp rộng kín màn hình lên một hàng chưa có gì thì gán thẳng tham chiếu chuỗi thay vì ghép lại qua phân tích ANSI và grapheme (layout.ts:345–354), một thay đổi giảm lượng cấp phát mỗi khung khoảng 9 tới 18 lần (CHANGELOG.md:209). Không có layout root thì TUI tự bọc các con trong một ScrollView ngầm, theo đáy và primary (tui-alt-screen.ts:262–269).

doRender(): so từng hàng#

protected override doRender(): void {	if (this.stopped || !this.altScreenActive) return;	const width = Math.max(1, this.terminal.columns);	const height = Math.max(1, this.terminal.rows);	const root = this.layoutRoot ?? this.implicitScrollView;	let nextLayout = renderLayoutFrame(root, width, height, () => this.requestRender());	if (this.refreshSearch(nextLayout)) {		nextLayout = renderLayoutFrame(root, width, height, () => this.requestRender());	}	// Resolve fake cursors before highlighting and compositing, which only track SGR codes	let screen = this.resolveFakeCursors(nextLayout.lines.map((line) => line.replace(OSC133_ZONE_PREFIX, "")));	screen = this.applySearchHighlights(screen, nextLayout);	screen = this.compositeScrollToEndIndicator(screen, nextLayout, width);	screen = this.compositeOverlays(screen, width, height);	if (screen.length > height) screen = screen.slice(screen.length - height);	screen = this.applySelection(screen, nextLayout);	screen = this.compositeFlashes(screen, width, height);	const cursorPos = this.extractCursorPosition(screen, height);	screen = this.applyLineResets(screen).map((line) => {		if (isImageLine(line) || visibleWidth(line) <= width) return line;		return sliceByColumn(line, 0, width, true);	});	const fullRedraw =		this.previousScreen.length === 0 || this.previousScreenWidth !== width || this.previousScreenHeight !== height;	const changedRows = screen.map((line, row) => line !== this.previousScreen[row]);⋯ lược bớt dòng 1717–1741	let buffer = BEGIN_SYNCHRONIZED_OUTPUT;	if (fullRedraw) {		this.fullRedrawCount += 1;		const clearImages =			this.imageProtocol === "kitty" && hadUploadedKittyImages				? deleteAllKittyPlacements()				: this.deleteKittyImages();		buffer += `${clearImages}\x1b[2J`;⋯ lược bớt dòng 1750–1775	} else {		for (let row = 0; row < height; row++) {			if (!fullRedraw && !imagesNeedRedraw && screen[row] === this.previousScreen[row]) continue;			buffer += `\x1b[${row + 1};1H\x1b[2K${preparedKittyScreen.lines[row] ?? ""}`;		}	}	if (cursorPos) {		buffer += `\x1b[${cursorPos.row + 1};${Math.min(width, cursorPos.col) + 1}H`;		buffer += this.getShowHardwareCursor() ? "\x1b[?25h" : "\x1b[?25l";	} else {		buffer += "\x1b[?25l";	}	buffer += END_SYNCHRONIZED_OUTPUT;	this.terminal.write(buffer);

1. Dựng màn hìnhrenderLayoutFrame(root, width, height) trả về đúng height dòng. Nếu đang tìm kiếm và kết quả cần cuộn để lộ ra, khung được dựng lại lần hai.
2. Trang tríGỡ dấu OSC 133 ở đầu dòng, đổi con trỏ giả, tô kết quả tìm kiếm, ghép nhãn “nhảy tới cuối”, ghép overlay, cắt về height hàng, tô vùng chọn, ghép thông báo nổi (flash).
3. Chuẩn hoáLấy vị trí con trỏ, nối reset, và cắt dòng quá rộng. Chế độ regular ném lỗi ở tình huống này; fullscreen thì im lặng cắt bớt.
4. So và ghiKhung đầu hoặc đổi kích thước thì \x1b[2J và vẽ mọi hàng. Nếu không, chỉ những hàng có chuỗi khác previousScreen[row], mỗi hàng bằng \x1b[r;1H\x1b[2K rồi nội dung. Cuối cùng đặt con trỏ tuyệt đối và đóng synchronized output, tất cả trong một lần ghi.

Cùng sự kiện ở fullscreen#

Chạy lại kịch bản của mục Trace trên TuiAltScreen, vẫn 40 × 12. Dock cao 6 hàng (Spacer, ba hàng editor, hai hàng footer), nên allocateStackSizes() cho transcript basis 0 nâng lên minSize 1, rồi chia phần dư 5 hàng cho mục duy nhất có grow: transcript được 6 hàng, dock 6 hàng. Tài liệu bây giờ chỉ gồm header, danh sách tài nguyên và chat, tức 24 dòng cũ (0–23) và 25 dòng mới. Đang theo đáy, nên scrollTop đi từ 24 − 6 = 18 lên 25 − 6 = 19.

Ví dụ minh hoạ: cùng khung đó ở TuiAltScreen, 40 × 12

hàng   trước (scrollTop 18)        sau (scrollTop 19)
  0    tài liệu 18                 tài liệu 19                ghi
  1    tài liệu 19                 tài liệu 20                ghi
  2    tài liệu 20                 tài liệu 21 (dòng trống)   ghi
  3    tài liệu 21 (dòng trống)    tài liệu 22                ghi
  4    tài liệu 22                 tài liệu 23                ghi
  5    tài liệu 23                 tài liệu 24                ghi
  6    Spacer                      Spacer                     giữ
  7    ── ⠋ Working ──             ── ⠙ Working ──            ghi, vì spinner đổi khung
  8    ‸ dòng nhập                 ‸ dòng nhập                giữ
  9    viền dưới editor            viền dưới editor           giữ
 10    footer: thư mục             footer: thư mục            giữ
 11    footer: token               footer: token              giữ

\x1b[?2026h
\x1b[1;1H\x1b[2K(tài liệu 19)R  \x1b[2;1H\x1b[2K(tài liệu 20)R  …  \x1b[6;1H\x1b[2K(tài liệu 24)R
\x1b[8;1H\x1b[2K── ⠙ Working ───…R
\x1b[9;1H\x1b[?25l                         con trỏ về dòng nhập (hàng 8), vẫn ẩn
\x1b[?2026l

Ở kịch bản này hai chế độ tốn gần như nhau: tám dòng so với bảy hàng. Khác biệt lộ ra ở các trường hợp khác. Khi người dùng đã cuộn lên đọc lại, scrollTop đứng yên, không hàng nào của transcript đổi, và thứ được ghi ra chỉ còn lệnh đặt con trỏ, cộng hàng spinner nếu nó vừa đổi khung. Một thay đổi ở bất kỳ đâu trong tài liệu tốn tối đa height hàng, không bao giờ là phát lại cả lịch sử. Đổi kích thước cửa sổ cũng chỉ vẽ lại một màn hình.

Bàn phím của viewport#

Constructor đăng ký handleViewportInput() làm input listener đầu tiên (tui-alt-screen.ts:281), nên nó thấy mọi byte trước component đang focus. Báo focus và sự kiện chuột bị nuốt ở đây; phần còn lại là các phím của viewport (tìm kiếm, cuộn trang, nửa trang, từng dòng, lời nhắc trước và sau, đầu và cuối), mỗi phím khớp thì trả về { consume: true } để editor không nhận nữa (tui-alt-screen.ts:739–805).

Các phím này cố ý che phím cùng tên của editor ở fullscreen (keybindings.ts:159): PageUp cuộn transcript chứ không cuộn ô soạn thảo; editor vẫn còn Ctrl+PageUp. Khi một overlay khác ô tìm kiếm đang giữ focus, các phím cuộn được nhường cho overlay (:680–682). Hai phím “lời nhắc trước/sau” dò dấu \x1b]133;A mà tin nhắn của người dùng và của assistant gắn vào dòng đầu, và nhảy tới đó (:517–529). Ở chế độ regular, chính các dấu đó được ghi thẳng ra terminal, nên terminal nào hỗ trợ OSC 133 tự có phím nhảy giữa các lời nhắc. Ctrl+Shift+F mở ô tìm kiếm, bản thân nó là một overlay neo góc trên phải, rộng 40% (:531–556); chỉ mục tìm kiếm giữ kết quả cũ chừng nào các dòng của transcript chưa đổi (alt-screen-search.ts:155).

Chuột: cuộn, chọn, copy, mở link#

Khi bắt chuột, ứng dụng nhận lại mọi việc terminal vốn tự làm. handleMouseEvent() xét theo thứ tự: component đang “bắt” chuỗi kéo thả; nút của ô tìm kiếm; overlay trên cùng dưới con trỏ; nhãn “nhảy tới cuối”; thanh cuộn (kéo, bấm vào rãnh, phóng to khi rê qua); component trong bố cục (handleMouse); dán bằng chuột phải trên Windows; cuối cùng là chọn văn bản (:912–973). Con lăn đi đường riêng: phần delta chưa dùng chuyển từ ScrollView trong ra ScrollView ngoài, trừ khi vùng trong đặt overscroll: "contain" (:1004–1016); Alt cộng con lăn cuộn gấp năm.

Vùng chọn được neo bằng toạ độ trong nội dung của ScrollView chứ không phải toạ độ màn hình, nên nó đúng cả khi transcript cuộn. Kéo tới mép trên hay dưới thì tự cuộn mỗi 50 ms. Bấm đúp chọn một từ và giữ nguyên đường dẫn hay từ nối bằng gạch ngang, vì / và - được coi là phần của từ (:83–85); bấm ba lần chọn cả dòng. Nhả chuột sau một cú bấm (không kéo) lên một hyperlink OSC 8 thì mở link; còn lại thì copy nếu copyOnSelect bật. copyTextToClipboard() ưu tiên hàm clipboard do ứng dụng truyền vào và chỉ báo “Copied!” khi hàm đó thành công; không có hàm nào thì ghi OSC 52 (tui-alt-screen.ts:1480–1497).

Chú thích giải thích vì sao không tin OSC 52: một lần ghi \x1b]52;c;… có thể hiện “Copied!” trong khi clipboard hệ thống không đổi, ví dụ trên Terminal.app của macOS hay tmux không chuyển tiếp OSC 52. Coding agent vì thế truyền vào một copySelection dùng clipboard native và các công cụ của hệ điều hành (tui-renderer.ts:39–46).

Overlay, focus và định tuyến input#

Overlay: vẽ đè lên dòng, không có lớp#

Vấn đề. Hộp thoại, menu, ô tìm kiếm cần nổi lên trên nội dung mà không đẩy nội dung đi chỗ khác. Trong một mô hình chỉ có dòng, không có lớp (layer) hay z-index. Overlay vì thế phải được ghép vào chính các dòng của khung: cắt dòng nền tại cột bắt đầu, chèn dòng của overlay, nối phần còn lại của dòng nền.

type OverlayStackEntry = {	component: Component;	options?: OverlayOptions;	preFocus: Component | null;	hidden: boolean;	focusOrder: number;	bounds?: OverlayBounds;};⋯ lược bớt dòng 334–751	showOverlay(component: Component, options?: OverlayOptions): OverlayHandle {		const entry: OverlayStackEntry = {			component,			...(options === undefined ? {} : { options }),			preFocus: this.focusedComponent,			hidden: false,			focusOrder: ++this.focusOrderCounter,		};		this.overlayStack.push(entry);		// Only focus if overlay is actually visible		if (!options?.nonCapturing && this.isOverlayVisible(entry)) {			this.setFocus(component);		}		this.hideTerminalCursor();		this.requestRender();

Mỗi overlay nhớ preFocus, component đang giữ focus lúc nó hiện ra, để trả focus khi nó đóng; và focusOrder, một bộ đếm tăng dần quyết định overlay nào nằm trên. Tuỳ chọn vị trí và kích thước (width, maxHeight, anchor, row/col tuyệt đối hoặc phần trăm, margin, visible(w, h), nonCapturing) nằm trong OverlayOptions (tui.ts:254–290); thứ tự ưu tiên khi chúng xung đột được README ghi rõ (README.md:239–243). Ghép vào khung diễn ra trong compositeOverlays():

const visibleEntries = this.overlayStack.filter((e) => this.isOverlayVisible(e));visibleEntries.sort((a, b) => a.focusOrder - b.focusOrder);for (const entry of visibleEntries) {	const { component, options } = entry;	// Get layout with height=0 first to determine width and maxHeight	// (width and maxHeight don't depend on overlay height)	const { width, maxHeight } = this.resolveOverlayLayout(options, 0, termWidth, termHeight);	// Render component at calculated width	let overlayLines = this.resolveFakeCursors(component.render(width));	// Apply maxHeight if specified	if (maxHeight !== undefined && overlayLines.length > maxHeight) {		overlayLines = overlayLines.slice(0, maxHeight);	}	// Get final row/col with actual overlay height	const { row, col } = this.resolveOverlayLayout(options, overlayLines.length, termWidth, termHeight);	entry.bounds = { row, col, width, height: overlayLines.length };	rendered.push({ entry, overlayLines, row, col, w: width });	minLinesNeeded = Math.max(minLinesNeeded, row + overlayLines.length);⋯ lược bớt dòng 1412–1420// Pad to at least terminal height so overlays have screen-relative positions.// Excludes maxLinesRendered: the historical high-water mark caused self-reinforcing// inflation that pushed content into scrollback on terminal widen.const workingHeight = Math.max(result.length, termHeight, minLinesNeeded);// Extend result with empty lines if content is too short for overlay placement or working areawhile (result.length < workingHeight) {	result.push("");}const viewportStart = Math.max(0, workingHeight - termHeight);// Composite each overlayfor (const { overlayLines, row, col, w } of rendered) {	for (let i = 0; i < overlayLines.length; i++) {		const idx = viewportStart + row + i;		if (idx >= 0 && idx < result.length) {			// Defensive: truncate overlay line to declared width before compositing			// (components should already respect width, but this ensures it)			const truncatedOverlayLine =				visibleWidth(overlayLines[i]) > w ? sliceByColumn(overlayLines[i], 0, w, true) : overlayLines[i];			result[idx] = this.compositeLineAt(result[idx], truncatedOverlayLine, col, w, termWidth);		}	}}return result;

• Overlay được sắp theo focusOrder, overlay sau đè overlay trước. Độ rộng được giải trước (không phụ thuộc chiều cao), component render ở đúng độ rộng đó, bị cắt theo maxHeight, rồi mới giải toạ độ với chiều cao thật. Hình chữ nhật cuối cùng được lưu lại cho getBounds() và cho việc dò chuột.
• Khung được đệm dòng trống cho đủ ít nhất một màn hình, và toạ độ của overlay tính từ viewportStart, tức tương đối với màn hình chứ không với đầu tài liệu. Chú thích ở dòng 1421–1423 ghi lại một lỗi cũ: từng dùng mức cao nhất maxLinesRendered để đệm, và nó tự phình ra, đẩy nội dung vào scrollback mỗi khi terminal rộng ra.
• Mỗi dòng được ghép bằng compositeTuiLine(): tách dòng nền thành phần trước và phần sau theo cột, có giữ trạng thái ANSI, rồi chèn \x1b[0m\x1b]8;;\x07 trước và sau đoạn overlay để màu của nền không loang vào hộp thoại và ngược lại. Dòng chứa ảnh thì không ghép (tui.ts:426–455).

Ở chế độ regular, overlay được ghép trước khi so khung, nên với thuật toán vi sai nó chỉ là vài dòng đổi nội dung: hiện ra thì ghi các dòng đó, đóng lại thì các dòng nền khác với khung trước và được ghi lại. Ở fullscreen, overlay được ghép vào màn hình sau bước tô kết quả tìm kiếm và trước bước cắt về height hàng.

Focus#

Mỗi lúc có đúng một component giữ focus. setFocus() bật cờ focused của component mới nếu nó là Focusable và tắt cờ của component cũ; cờ này quyết định component có phát CURSOR_MARKER hay không. Overlay giành focus khi hiện ra, trừ khi nonCapturing hoặc đang bị visible() ẩn; khi bị đóng, focus về overlay hiển thị cao nhất còn lại hoặc về preFocus (tui.ts:770–784). Phần phức tạp nhất của TuiBase là một máy trạng thái nhỏ, overlayFocusRestore, với các trạng thái inactive, eligible và blocked (tui.ts:343–353, :625–688). Nó cài đặt một hứa hẹn của README: một overlay đang hiện và đang giữ focus sẽ lấy lại bàn phím sau khi một giao diện thay thế tạm thời trả focus (README.md:226–228). Muốn chủ động nhường bàn phím cho component khác trong lúc overlay vẫn hiện thì gọi handle.unfocus({ target }).

Một container chứa Input hay Editor bên trong phải tự cài Focusable và chuyển cờ focused xuống con. Nếu không, TUI bật cờ trên container, ô nhập bên trong không phát CURSOR_MARKER, và cửa sổ gợi ý của bộ gõ IME hiện sai chỗ (README.md:336–360).

Đường đi của một chuỗi input#

Một phím bấm đi qua nhiều tầng trước khi tới component:

1. StdinBufferGom các mảnh data của stdin thành từng chuỗi hoàn chỉnh; nội dung dán được gom thành một sự kiện và bọc lại bằng \x1b[200~ … \x1b[201~ (terminal.ts:265–270). Mục Phân tích phím giải thích vì sao cần.
2. ProcessTerminalNuốt các câu trả lời thương lượng bàn phím Kitty và trạng thái chương trình; còn lại chuyển cho TuiBase.handleTerminalInput() (terminal.ts:244–263).
3. Câu trả lời của terminalCâu trả lời màu (OSC 10, 11, 4 và DA1) khi có truy vấn màu đang chờ, và báo đổi sáng/tối (\x1b[?997;1n hoặc 2n), bị nuốt ở TuiBase trước mọi thứ khác, không tới component nào.
4. Input listenerChạy theo thứ tự đăng ký; mỗi listener có thể nuốt chuỗi (consume) hoặc thay nó (data). Viewport của fullscreen là listener đầu tiên; listener của extension cũng ở đây (xem chương Extensions).
5. FocusCâu trả lời kích thước ô ảnh (\x1b[6;h;wt) bị nuốt. Shift+Ctrl+D gọi onDebug. Nếu overlay đang giữ focus vừa bị ẩn (resize, visible()) thì chuyển focus; nếu có overlay chờ lấy lại focus thì trả cho nó.
6. ComponentBỏ sự kiện nhả phím trừ khi component đặt wantsKeyRelease, gọi handleInput(data), rồi vẽ khung ngay.

private handleTerminalInput(data: string): void {	if (this.consumeTerminalColorResponse(data)) {		return;	}	if (this.consumeTerminalColorSchemeReport(data)) {		return;	}	if (this.inputListeners.size > 0) {		let current = data;		for (const listener of this.inputListeners) {			const result = listener(current);			if (result?.consume) {				return;			}			if (result?.data !== undefined) {				current = result.data;			}		}		if (current.length === 0) {			return;		}		data = current;	}	// Consume terminal cell size responses without blocking unrelated input.	if (this.consumeCellSizeResponse(data)) {		return;	}	// Global debug key handler (Shift+Ctrl+D)	if (matchesKey(data, "shift+ctrl+d") && this.onDebug) {		this.onDebug();		return;	}⋯ lược bớt dòng 1116–1144	// Pass input to focused component (including Ctrl+C)	// The focused component can decide how to handle Ctrl+C	if (this.focusedComponent?.handleInput) {		// Filter out key release events unless component opts in		if (isKeyRelease(data) && !this.focusedComponent.wantsKeyRelease) {			return;		}		this.focusedComponent.handleInput(data);		// Keyboard input is latency-sensitive. Avoid the throttled timer path,		// where even setTimeout(0) can take a full 16 ms tick on Windows.		this.requestImmediateRender();	}

Ctrl+C cũng chỉ là một chuỗi input như mọi phím khác. TUI không xử lý nó; component đang focus quyết định. Trong coding agent, CustomEditor chuyển nó cho hành động app.clear (xoá editor, bấm lần hai thì thoát).

Chuột, chỉ ở fullscreen#

TuiMainScreen không bắt chuột, vì terminal sở hữu scrollback và cần chuột để cuộn và chọn chữ (README.md:269). TuiAltScreen chuẩn hoá chuỗi SGR thành TuiMouseEvent có toạ độ cục bộ của component, toạ độ màn hình, kích thước, nút, phím bổ trợ, số lần bấm và delta con lăn (tui.ts:25–44), và component trả lời bằng:

export interface TuiMouseEventResult {	/** Stop propagation and suppress renderer-level fallback behavior. */	handled?: boolean;	/** Route subsequent drag/release events to this component. Implies handled. */	capture?: boolean;	/** Give keyboard focus to this component. Implies handled. */	focus?: boolean;	/**	 * Explicitly request or suppress a render. Move and release default to false;	 * press, click, drag, and wheel default to true.	 */	render?: boolean;}

handled chặn hành vi mặc định của renderer (cuộn, chọn chữ); capture giữ các sự kiện kéo và nhả tiếp theo cho cùng component; focus xin focus bàn phím; render ghi đè quy tắc mặc định là nhấn, bấm, kéo, con lăn thì vẽ lại còn di chuột và nhả thì không (README.md:290). Để dò trúng con nào, Container.handleMouse() dùng chiều cao từng con ghi lại ở lần render trước, nên di chuột không làm cả cây render lại chỉ để dò (tui.ts:383–403). MouseRegion bọc một component bất kỳ để thêm hành vi chuột mà không đổi cách nó vẽ; coding agent dùng nó cho việc bấm vào khối thinking để ẩn hay hiện (assistant-message.ts:163–170). Từ 1.2.0, con lăn không được component nào xử lý thì cuộn transcript, kể cả khi một overlay đang giữ focus; overlay muốn cuộn bằng con lăn phải cài handleMouse (CHANGELOG.md:35).

Phân tích phím và keybinding#

Vấn đề: terminal mã hoá phím rất mơ hồ#

Terminal truyền thống gửi phím dưới dạng byte. Chữ a là 0x61, Ctrl+A là 0x01, Enter là \r, Tab là 0x09 và trùng với Ctrl+I, Esc là 0x1b và trùng với Ctrl+[, Alt+x là ESC rồi x, mũi tên lên là ESC [ A. Chú thích đầu keys.ts nhắc đúng những chỗ trùng này (keys.ts:8–11). Với một coding agent, ba hệ quả gây khó chịu nhất là: Shift+Enter thường gửi y hệt Enter, nên không phân biệt được “xuống dòng” với “gửi prompt”; một byte ESC đơn lẻ có thể là phím Esc hoặc là đầu của một chuỗi chưa tới hết; và một lần đọc stdin có thể chứa vài phím, hoặc chỉ nửa chuỗi.

Thương lượng giao thức: Kitty trước, modifyOtherKeys sau#

/** * Query terminal for Kitty keyboard protocol support and enable it if available. * * Kitty's progressive enhancement detection requires requesting the desired * flags before querying them. The trailing DA query is a sentinel supported by * terminals that do not know Kitty keyboard protocol; receiving DA before a * Kitty response enables modifyOtherKeys fallback without a startup timeout. * * The requested flags are: * - 1 = disambiguate escape codes * - 2 = report event types (press/repeat/release) * - 4 = report alternate keys (shifted key, base layout key) * * The OSC 7501 program status query shares the DA sentinel: a terminal that supports it replies * before DA. `PI_PROGRAM_STATUS=1` or `0` skips the query. */private queryAndEnableKittyProtocol(): void {	this.setupStdinBuffer();	process.stdin.on("data", this.stdinDataHandler!);	this.keyboardProtocolPushed = true;	this.pendingKeyboardProtocolDeviceAttributes += 1;	this.clearKeyboardProtocolNegotiationBuffer();	const programStatusOverride = process.env.PI_PROGRAM_STATUS;	this.programStatusSupported = programStatusOverride === "1";	this.programStatusQueryPending = programStatusOverride !== "1" && programStatusOverride !== "0";	const programStatusQuery = this.programStatusQueryPending ? PROGRAM_STATUS_QUERY : "";	process.stdout.write(`${KITTY_KEYBOARD_PROTOCOL_QUERY}${programStatusQuery}${DEVICE_ATTRIBUTES_QUERY}`);	this.writeProgramStatus();}

Giao thức bàn phím Kitty cho phép chương trình xin terminal mã hoá phím rõ ràng. \x1b[>7u đẩy cờ 7 = 1 | 2 | 4: phân biệt mã escape, báo loại sự kiện (nhấn, giữ lặp, nhả), báo phím thay thế. \x1b[?u hỏi cờ đang bật. \x1b[c (DA1) là câu hỏi mà mọi terminal đều trả lời, và terminal trả lời theo thứ tự; nên nếu câu trả lời DA1 tới mà chưa thấy câu trả lời Kitty, terminal không biết giao thức Kitty, và không cần một bộ hẹn giờ chờ đoán. Khi nhận được cờ khác 0, ProcessTerminal bật cờ toàn cục setKittyProtocolActive(true) mà bộ khớp phím tra cứu; nếu không, nó bật modifyOtherKeys của xterm bằng \x1b[>4;2m (terminal.ts:308–336, :408–412). Lúc dừng, \x1b[<u gỡ cờ Kitty và \x1b[>4;0m tắt modifyOtherKeys.

function parseKittySequence(data: string): ParsedKittySequence | null {	// CSI u format with alternate keys (flag 4):	// \x1b[<codepoint>u	// \x1b[<codepoint>;<mod>u	// \x1b[<codepoint>;<mod>:<event>u	// \x1b[<codepoint>:<shifted>;<mod>u	// \x1b[<codepoint>:<shifted>:<base>;<mod>u	// \x1b[<codepoint>::<base>;<mod>u (no shifted key, only base)	//	// With flag 2, event type is appended after modifier colon: 1=press, 2=repeat, 3=release	// With flag 4, alternate keys are appended after codepoint with colons	const csiUMatch = data.match(/^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/);	if (csiUMatch) {		const codepoint = parseInt(csiUMatch[1]!, 10);		const shiftedKey = csiUMatch[2] && csiUMatch[2].length > 0 ? parseInt(csiUMatch[2], 10) : undefined;		const baseLayoutKey = csiUMatch[3] ? parseInt(csiUMatch[3], 10) : undefined;		const modValue = csiUMatch[4] ? parseInt(csiUMatch[4], 10) : 1;		const eventType = parseEventType(csiUMatch[5]);		_lastEventType = eventType;		return { codepoint, shiftedKey, baseLayoutKey, modifier: modValue - 1, eventType };	}

Giá trị phím bổ trợ trên dây lớn hơn bitmask một đơn vị; bitmask là Shift 1, Alt 2, Ctrl 4, Super 8, còn Caps Lock 64 và Num Lock 128 bị bỏ qua khi so (keys.ts:296–303). Tài liệu cấu hình terminal của Pi dùng đúng các chuỗi này khi hướng dẫn người dùng tự map phím:

modifyOtherKeys mã hoá cùng thông tin theo dạng CSI 27 ; mod ; code ~, ví dụ \x1b[27;2;13~ cho Shift+Enter (keys.ts:722–728). Đây là dạng mà tmux 3.2 tới 3.4 chuyển tiếp; tmux từ 3.5 chuyển tiếp được CSI u nếu bật extended-keys-format csi-u (tmux.md:13–22).

StdinBuffer: cắt luồng byte thành từng chuỗi#

Một sự kiện data của stdin không phải một phím. Chú thích của StdinBuffer đưa ví dụ chuỗi chuột \x1b[<35;20;5m tới thành ba mảnh \x1b, [<35, ;20;5m (stdin-buffer.ts:1–18). Bộ đệm nhận biết điểm kết thúc của từng loại chuỗi (CSI kết thúc bằng một byte trong khoảng 0x40–0x7e, OSC bằng BEL hoặc ESC \, DCS và APC bằng ESC \), phát từng chuỗi hoàn chỉnh, và giữ phần dở dang lại, xả nó ra như phím sau một thời gian chờ có hạn (stdin-buffer.ts:411–432).

Một ESC đơn lẻ chờ escapeTimeout, mặc định 10 ms; qua SSH (có SSH_CONNECTION hoặc SSH_TTY) là 100 ms, vì Alt+phím kiểu cũ là ESC cộng một byte và trên đường truyền chậm hai byte đó có thể tới cách xa nhau; biến PI_TUI_ESC_TIMEOUT ghi đè cả hai (terminal.ts:142–151). Chuỗi dở khác chờ 50 ms. Riêng câu trả lời của terminal có phần đầu nhận ra được (màu, trạng thái chương trình, XTVersion, ảnh Kitty) thì chờ tới khi có ký tự kết thúc, không xả theo thời gian (dòng 416). Lý do được ghi ngay trong chú thích: xả ra thì phần đuôi bị gõ vào prompt như chữ thường, và ký tự BEL kết thúc của OSC thành Ctrl+G, phím mở trình soạn thảo ngoài. Đó là lỗi đã sửa ở 1.2.0 (CHANGELOG.md:36). Bộ đệm cũng gom nội dung dán giữa \x1b[200~ và \x1b[201~ thành một sự kiện paste, nên một lần dán dài không bị phân tích thành hàng nghìn phím.

matchesKey(): một tên phím, nhiều cách mã hoá#

Tên phím có kiểu KeyId, một hợp của các template literal như "ctrl+shift+p", nên viết sai tên là lỗi biên dịch (keys.ts:141–152). matchesKey(data, keyId) chấp nhận mọi cách mà một terminal có thể đã gửi phím đó. Trường hợp Shift+Enter cho thấy rõ nhất:

case "enter":case "return":	if (modifier === MODIFIERS.shift) {		// CSI u sequences (standard Kitty protocol)		if (			matchesKittySequence(data, CODEPOINTS.enter, MODIFIERS.shift) ||			matchesKittySequence(data, CODEPOINTS.kpEnter, MODIFIERS.shift)		) {			return true;		}		// xterm modifyOtherKeys format (fallback when Kitty protocol not enabled)		if (matchesModifyOtherKeys(data, CODEPOINTS.enter, MODIFIERS.shift)) {			return true;		}		// When Kitty protocol is active, legacy sequences are custom terminal mappings		// \x1b\r = Kitty's "map shift+enter send_text all \e\r"		// \n = Ghostty's "keybind = shift+enter=text:\n"		if (_kittyProtocolActive) {			return data === "\x1b\r" || data === "\n";		}		return false;	}

Hai chuỗi ở dòng 935 là map người dùng hay tự đặt trong terminal (chú thích ghi map shift+enter send_text all \e\r của Kitty và keybind = shift+enter=text:\n của Ghostty). Chúng chỉ được hiểu là Shift+Enter khi giao thức Kitty đang bật; nếu không, \x1b\r là Alt+Enter kiểu cũ và \n là Ctrl+J. Tài liệu khuyên gỡ map Ghostty kiểu này vì Pi không phân biệt nó với Ctrl+J (terminal-setup.md:57–63). Vài chi tiết khác của bộ khớp:

• Bố cục bàn phím không phải Latin. Với tiếng Nga, Ctrl+С (chữ Cyrillic) vẫn khớp ctrl+c nhờ “phím theo bố cục gốc” mà Kitty báo kèm. Nhưng bộ khớp chỉ dùng phím gốc khi mã phím không phải chữ Latin hay ký hiệu đã biết, để bố cục Dvorak hay Colemak không khớp nhầm Ctrl+K thành Ctrl+V (keys.ts:700–717).
• Nhả phím. isKeyRelease() nhận ra sự kiện nhả bằng hậu tố :3u, :3~, :3A... và bỏ qua nội dung dán, vì một địa chỉ MAC như 90:62:3F chứa đúng chuỗi đó (keys.ts:542–566).
• Gõ chữ. Khi bật cờ phân biệt, terminal có thể gửi cả chữ thường dưới dạng CSI u. Ô nhập dùng decodePrintableKey() để lấy lại ký tự, và chỉ nhận chữ không kèm Ctrl hay Alt (keys.ts:1404–1437).
• Backspace mơ hồ. Byte 0x08 là Ctrl+Backspace trên Windows Terminal nhưng là Backspace thường ở vài terminal và cấu hình tmux; bộ khớp đoán theo WT_SESSION (keys.ts:747–760).

Keybinding: gọi phím bằng tên hành động#

Component không nên viết cứng matchesKey(data, "ctrl+k"); nó hỏi theo tên hành động, và người dùng đổi được phím cho hành động đó. Danh sách hành động là một interface mở rộng được bằng declaration merging:

/** * Global keybinding registry. * Downstream packages can add keybindings via declaration merging. */export interface Keybindings {	// Editor navigation and editing	"tui.editor.cursorUp": true;	"tui.editor.cursorDown": true;	"tui.editor.historyPrevious": true;	"tui.editor.historyNext": true;⋯ lược bớt dòng 13–56	"tui.altScreen.top": true;	"tui.altScreen.bottom": true;}export type Keybinding = keyof Keybindings;export interface KeybindingDefinition {	defaultKeys: KeyId | KeyId[];	description?: string;}export type KeybindingDefinitions = Record<string, KeybindingDefinition>;export type KeybindingsConfig = Record<string, KeyId | KeyId[] | undefined>;

pi-tui định nghĩa các hành động tui.editor.*, tui.input.*, tui.select.*, tui.altScreen.* cùng phím mặc định trong TUI_KEYBINDINGS (keybindings.ts:71–210). KeybindingsManager.rebuild() dựng một bảng tra từ tên hành động tới danh sách phím, và matches(data, action) chỉ là thử matchesKey() với từng phím trong danh sách (keybindings.ts:243–276).

Cấu hình người dùng thay thế danh sách phím của một hành động chứ không cộng thêm, và một mảng rỗng tắt hành động đó (keybindings.md:21–27). Xung đột chỉ được ghi nhận giữa các phím do người dùng gán, không giữa phím người dùng với phím mặc định. Bảng tra là một biến toàn cục (setKeybindings/getKeybindings, keybindings.ts:309–320), nên editor và viewport của fullscreen đọc chung một bản mà không phải truyền qua constructor. Coding agent mở rộng sổ đăng ký với các hành động app.* và đổi vài mặc định theo nền tảng:

declare module "@earendil-works/pi-tui" {	interface Keybindings extends AppKeybindings {}}export const KEYBINDINGS = {	...TUI_KEYBINDINGS,	"tui.editor.undo": {		...TUI_KEYBINDINGS["tui.editor.undo"],		defaultKeys: process.platform === "win32" ? "ctrl+z" : windowsKeybindings ? "alt+z" : "ctrl+-",	},	"tui.altScreen.previousPrompt": {		...TUI_KEYBINDINGS["tui.altScreen.previousPrompt"],		defaultKeys: windowsKeybindings ? "ctrl+up" : ["ctrl+shift+up", "ctrl+up"],	},	"tui.altScreen.nextPrompt": {		...TUI_KEYBINDINGS["tui.altScreen.nextPrompt"],		defaultKeys: windowsKeybindings ? "ctrl+down" : ["ctrl+shift+down", "ctrl+down"],	},	"tui.altScreen.search": {		...TUI_KEYBINDINGS["tui.altScreen.search"],		defaultKeys: windowsKeybindings ? "ctrl+f" : "ctrl+shift+f",	},	...APP_KEYBINDINGS,} as const satisfies KeybindingDefinitions;

Trên Windows và WSL, tìm kiếm trong transcript mặc định là Ctrl+F. Undo thì tuỳ: Windows gốc không có job control nên Ctrl+Z rảnh và được dùng cho undo (keybindings.md:131); WSL vẫn dùng Ctrl+Z để tạm dừng tiến trình nên undo chuyển sang Alt+Z; các nền tảng khác dùng Ctrl+-. KeybindingsManager.create() của coding agent đọc <agent-dir>/keybindings.json, mặc định ~/.pi/agent/keybindings.json (keybindings.ts:337–341), và interactive mode cài nó làm bảng toàn cục ngay trong constructor (interactive-mode.ts:646–647).

Editor: soạn nhiều dòng, autocomplete, paste, undo#

Editor (components/editor.ts, 2.473 dòng) là component lớn nhất của gói, và là nơi người dùng ở lâu nhất. State cốt lõi rất nhỏ:

interface EditorState {	lines: string[];	cursorLine: number;	cursorCol: number;}/** Undo snapshot: editor text state plus the paste registry. */interface EditorSnapshot {	state: EditorState;	pastes: Map<number, string>;	pasteCounter: number;}

Văn bản là một mảng dòng logic, con trỏ là cặp (dòng, cột) với cột là chỉ số trong chuỗi của dòng đó. Ngắt dòng không nằm trong state: mỗi lần render, layoutText() ngắt các dòng logic thành dòng hiển thị theo độ rộng hiện tại (editor.ts:998). Di chuyển lên xuống đi theo dòng hiển thị và nhớ một “cột ưa thích” (preferredVisualCol) để con trỏ không trôi dần sang trái khi đi qua các dòng ngắn. Ngoài ra editor giữ bảng nội dung dán, lịch sử prompt (tối đa 100 mục), kill ring kiểu Emacs, ngăn xếp undo và trạng thái autocomplete (editor.ts:337–372).

render(): chiều cao có trần, cuộn bên trong#

// Calculate max visible lines: 30% of terminal height, minimum 5 linesconst terminalRows = this.tui.terminal.rows;const maxVisibleLines = Math.max(5, Math.floor(terminalRows * 0.3));// Find the cursor line index in layoutLineslet cursorLineIndex = layoutLines.findIndex((line) => line.hasCursor);if (cursorLineIndex === -1) cursorLineIndex = 0;// Adjust scroll offset to keep cursor visibleif (cursorLineIndex < this.scrollOffset) {	this.scrollOffset = cursorLineIndex;} else if (cursorLineIndex >= this.scrollOffset + maxVisibleLines) {	this.scrollOffset = cursorLineIndex - maxVisibleLines + 1;}// Clamp scroll offset to valid rangeconst maxScrollOffset = Math.max(0, layoutLines.length - maxVisibleLines);this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, maxScrollOffset));// Get visible lines sliceconst visibleLines = layoutLines.slice(this.scrollOffset, this.scrollOffset + maxVisibleLines);this.renderedVisibleLineCount = visibleLines.length;

Editor đọc tui.terminal.rows, đó là lý do constructor bắt buộc nhận tui. Trần chiều cao có từ khi một prompt dài hơn màn hình làm hỏng hiển thị của terminal (CHANGELOG.md:1068). Phần còn lại của render() vẽ viền trên và viền dưới (kèm “↑ N more” khi có phần bị che), chèn CURSOR_MARKER và con trỏ giả vào đúng grapheme dưới con trỏ, đệm mỗi dòng đủ độ rộng, và nối danh sách autocomplete bên dưới viền dưới (editor.ts:559–630). Khi không có padding ngang, độ rộng bố trí chừa một cột cho con trỏ đứng cuối dòng (dòng 526–528).

handleInput(): thứ tự ưu tiên#

Một chuỗi input được thử lần lượt (editor.ts:696–996), và cách đầu tiên khớp thắng:

1. Chế độ nhảySau Ctrl+], phím in được tiếp theo là ký tự đích để nhảy tới.
2. Bracketed pasteTừ \x1b[200~, mọi thứ được gom cho tới \x1b[201~ rồi chuyển cho handlePaste(); phần sau dấu đóng được xử lý tiếp như input thường.
3. Ctrl+C và undotui.input.copy trả về ngay để component cha quyết định; tui.editor.undo hoàn tác.
4. Autocomplete đang mởEsc huỷ, lên xuống chọn, Tab áp dụng, Enter áp dụng; với lệnh slash, Enter áp dụng rồi đi tiếp xuống bước gửi.
5. Soạn thảoTab gọi completion; các phím xoá; yank và yank-pop của kill ring; lịch sử; di chuyển con trỏ.
6. Xuống dòng hay gửitui.input.newLine (Shift+Enter, Ctrl+J) chèn dòng. Enter gửi, trừ khi ký tự ngay trước con trỏ là \: khi đó dấu \ bị xoá và một dòng mới được chèn, một cách lách cho terminal không gửi được Shift+Enter (dòng 912–919).
7. Lên, xuốngỞ dòng hiển thị đầu tiên, phím lên duyệt lịch sử nếu editor rỗng, đang duyệt dở, hoặc con trỏ ở cột 0; nếu không thì nhảy về đầu dòng (dòng 926–939).
8. Ký tựThử decodePrintableKey() cho chữ đến dưới dạng CSI u, rồi tới byte thường từ 0x20 trở lên.

Dán: marker thay cho cả khối#

// Split into lines to check for large pasteconst pastedLines = filteredText.split("\n");// Check if this is a large paste (> 10 lines or > 1000 characters)const totalChars = filteredText.length;if (pastedLines.length > 10 || totalChars > 1000) {	// Store the paste and insert a marker	this.pasteCounter++;	const pasteId = this.pasteCounter;	this.pastes.set(pasteId, filteredText);	// Insert marker like "[paste #1 +123 lines]" or "[paste #1 1234 chars]"	const marker =		pastedLines.length > 10			? `[paste #${pasteId} +${pastedLines.length} lines]`			: `[paste #${pasteId} ${totalChars} chars]`;	this.insertTextAtCursorInternal(marker);	return;}

Trước đó, handlePaste() chuẩn hoá xuống dòng, đổi tab thành bốn dấu cách, lọc ký tự điều khiển, và giải mã các Ctrl+chữ mà vài terminal (ví dụ popup của tmux với extended-keys-format=csi-u) mã hoá lại thành CSI u bên trong nội dung dán (editor.ts:1267–1277). Một đường dẫn dán dính vào sau một chữ được thêm dấu cách phía trước. Nội dung lớn được cất vào bảng pastes, còn editor chỉ chứa marker như [paste #1 +123 lines]. segmentWithMarkers() gộp mọi grapheme của một marker hợp lệ thành một đơn vị, nên di chuyển, xoá và ngắt dòng coi marker như một ký tự (editor.ts:41–105). Marker chỉ được thay lại bằng nội dung thật ở hai chỗ. Khi gửi, submitValue() mở mọi marker, xoá state, bảng nội dung dán và ngăn xếp undo, rồi gọi onSubmit (editor.ts:1364–1378). Khi mở trình soạn thảo ngoài, getExpandedText() đưa ra văn bản đầy đủ (editor.ts:1099–1105).

README chỉ nói về ngưỡng “hơn 10 dòng” (README.md:467); code còn tạo marker cho một lần dán một dòng dài hơn 1.000 ký tự, với dạng [paste #2 1234 chars].

Undo kiểu fish#

private insertCharacter(char: string, skipUndoCoalescing?: boolean): void {	this.exitHistoryBrowsing();	// Undo coalescing (fish-style):	// - Consecutive word chars coalesce into one undo unit	// - Space captures state before itself (so undo removes space+following word together)	// - Each space is separately undoable	// Skip coalescing when called from atomic operations (e.g., handlePaste)	if (!skipUndoCoalescing) {		if (isWhitespaceChar(char) || this.lastAction !== "type-word") {			this.pushUndoSnapshot();		}		this.lastAction = "type-word";	}⋯ lược bớt dòng 1215–2115private pushUndoSnapshot(): void {	this.undoStack.push({ state: this.state, pastes: this.pastes, pasteCounter: this.pasteCounter });}private undo(): void {	this.exitHistoryBrowsing();	const snapshot = this.undoStack.pop();	if (!snapshot) return;	Object.assign(this.state, snapshot.state);	this.pastes = snapshot.pastes;	this.pasteCounter = snapshot.pasteCounter;	this.lastAction = null;	this.preferredVisualCol = null;	if (this.onChange) {		this.onChange(this.getText());	}}

Gõ liên tiếp các ký tự trong một từ chỉ tạo một snapshot ở đầu từ; mỗi khoảng trắng tạo snapshot ngay trước nó. Undo vì vậy xoá từng từ chứ không từng ký tự, giống shell fish như chú thích ghi. UndoStack.push() lưu một bản sao sâu bằng structuredClone, nên snapshot không bị sửa ngầm khi state đổi sau đó (undo-stack.ts:1–13). Snapshot gồm cả bảng pastes và bộ đếm, nên undo một lần dán xoá luôn nội dung đã cất. Kill ring là một vòng chuỗi riêng: các lần xoá liên tiếp được nối vào cùng một mục, Ctrl+Y dán mục mới nhất, Alt+Y xoay vòng (kill-ring.ts:1–28).

Autocomplete bất đồng bộ#

export interface AutocompleteProvider {	/** Characters that should naturally trigger this provider at token boundaries. */	triggerCharacters?: string[];	// Get autocomplete suggestions for current text/cursor position	// Returns null if no suggestions available	getSuggestions(		lines: string[],		cursorLine: number,		cursorCol: number,		options: { signal: AbortSignal; force?: boolean },	): Promise<AutocompleteSuggestions | null>;	// Apply the selected item	// Returns the new text and cursor position	applyCompletion(		lines: string[],		cursorLine: number,		cursorCol: number,		item: AutocompleteItem,		prefix: string,	): {		lines: string[];		cursorLine: number;		cursorCol: number;	};	// Check if file completion should trigger for explicit Tab completion	shouldTriggerFileCompletion?(lines: string[], cursorLine: number, cursorCol: number): boolean;}

Editor tự gọi gợi ý khi gõ / ở đầu tin nhắn (lệnh slash), khi gõ @, # hoặc ký tự kích hoạt riêng của provider ở đầu một token, và khi gõ tiếp chữ trong một ngữ cảnh như vậy; ngoài ngữ cảnh lệnh slash, Tab ép gợi ý đường dẫn file (editor.ts:1228–1257). Vì getSuggestions() có thể chậm (tìm file qua fd, gọi completion của extension), editor xếp các yêu cầu nối tiếp nhau, huỷ yêu cầu cũ bằng AbortController, hoãn 20 ms với các token bắt đầu bằng ký tự kích hoạt như @ hay #, và bỏ kết quả tới muộn:

private isAutocompleteRequestCurrent(	requestId: number,	controller: AbortController,	snapshotText: string,	snapshotLine: number,	snapshotCol: number,): boolean {	return (		!controller.signal.aborted &&		requestId === this.autocompleteRequestId &&		this.getText() === snapshotText &&		this.state.cursorLine === snapshotLine &&		this.state.cursorCol === snapshotCol	);}

Khi Tab ép gợi ý và chỉ có đúng một kết quả, nó được áp dụng luôn mà không mở danh sách (editor.ts:2393–2410). CombinedAutocompleteProvider của pi-tui ghép lệnh slash với đường dẫn file; với tiền tố @, nó tìm mờ qua fd, có theo .gitignore, gồm file ẩn, bỏ thư mục .git (autocomplete.ts:145–175). Coding agent dựng provider từ lệnh có sẵn, prompt template, lệnh của extension và skill, rồi cho extension bọc thêm (interactive-mode.ts:827–843).

CustomEditor: phím của ứng dụng đứng trước#

Coding agent không sửa Editor; nó kế thừa. CustomEditor.handleInput() (custom-editor.ts:88–147) thử phím tắt do extension đăng ký, phím dán ảnh, Esc (chỉ ngắt agent khi danh sách autocomplete không mở, nếu không thì để Esc đóng danh sách), Ctrl+D (chỉ thoát khi editor rỗng), rồi mọi hành động app.* đã đăng ký, cuối cùng mới tới super.handleInput(). Nó cũng vẽ chỉ báo “working” ngay trong viền trên (custom-editor.ts:36–79), lý do status container trống trong trace.

Markdown và hình ảnh#

Markdown#

Câu trả lời của mô hình là Markdown, nên Markdown là component được render nhiều nhất. Nó dùng lexer của marked với ba phần tuỳ biến: gạch ngang chỉ nhận ~~ chặt chẽ, nhấn mạnh thân thiện với chữ CJK (marked-cjk-friendly), và hai extension LaTeX cho công thức inline và dạng khối, được vẽ thành ký tự Unicode bởi latex.ts (markdown.ts:190–197). Mỗi token thành các dòng có mã ANSI theo MarkdownTheme, một tập hàm tô màu do ứng dụng cung cấp, kể cả highlightCode cho khối code (markdown.ts:222–240). Hai lớp cache:

render(width: number): string[] {	// Check cache	if (this.cachedLines && this.cachedText === this.text && this.cachedWidth === width) {		return this.cachedLines;	}	// Calculate available width for content (subtract horizontal padding)	const contentWidth = Math.max(1, width - this.paddingX * 2);	const text = this.options.transform?.(this.text, contentWidth) ?? this.text;	// Don't render anything if there's no actual text	if (!text || text.trim() === "") {		const result: string[] = [];		// Update cache		this.cachedText = this.text;		this.cachedWidth = width;		this.cachedLines = result;		return result;	}	// Replace tabs with 3 spaces for consistent rendering	const normalizedText = text.replace(/\t/g, "   ");	// Parse markdown to HTML-like tokens	const cached = this.cachedTokens?.deref();	let tokens = cached?.source === normalizedText ? cached.tokens : undefined;	if (!tokens) {		tokens = markdownParser.lexer(normalizedText);		trimPartialClosingFences(tokens);		this.cachedTokens = new WeakRef({ source: normalizedText, tokens });	}

Cache dòng trúng khi văn bản và độ rộng không đổi, tức là với mọi tin nhắn đã xong. Cache token chỉ phụ thuộc mã nguồn Markdown, nên sống qua được việc đổi theme hay đổi độ rộng; nó được giữ bằng WeakRef vì theo chú thích, cây token lớn khoảng mười lần mã nguồn và mỗi tin nhắn của một transcript dài đều giữ một Markdown (markdown.ts:271–274). Cuối render(), flattenLines() ép V8 làm phẳng các chuỗi được ghép từ nhiều mảnh, vốn giữ cây các mảnh con và tốn gấp mấy lần kích thước thật (utils.ts:891–898). Hai thay đổi này của 1.0.0 làm một tin nhắn dài chỉ còn giữ khoảng một phần năm bộ nhớ so với trước (CHANGELOG.md:86).

Tin nhắn đang stream thì khác. AssistantMessageComponent.updateContent() tạo một Markdown mới mỗi lần cập nhật, nên cả hai cache của nó không giúp gì: mỗi khung, đoạn văn đang stream được lex và ngắt dòng lại từ đầu. Chi phí đó tỷ lệ với độ dài của một tin nhắn, không phải của cả transcript, và bị chặn bởi nhịp 16 ms. Vài chỗ trong Markdown có mặt chỉ vì streaming: trimPartialClosingFences() bỏ dấu đóng khối code đang tới dở (dòng cuối chỉ gồm vài dấu backtick hay dấu ngã, ngắn hơn dấu mở), để khối code không co lại rồi giãn ra khi ký tự cuối tới (markdown.ts:165–188); công thức $$ chưa đóng được giữ ở dạng thô cho tới khi đóng, và từ 1.4.0 không còn nuốt bảng phía sau (CHANGELOG.md:11).

Ảnh inline: Kitty và iTerm2#

Terminal có hai giao thức ảnh phổ biến. pi-tui đoán terminal hỗ trợ cái nào từ biến môi trường: Kitty, Ghostty, WezTerm, Warp, Herdr, Rex dùng giao thức Kitty; iTerm2 dùng giao thức riêng; dưới tmux hay screen thì tắt ảnh vì không đáng tin (terminal-image.ts:70–146). Người dùng ghi đè được bằng PI_IMAGE_PROTOCOL, PI_TRUE_COLOR, PI_HYPERLINKS hoặc setting terminal.* (terminal-setup.md:207–219).

Giao thức Kitty truyền ảnh PNG đã mã hoá base64 trong các chuỗi APC \x1b_G…;…\x1b\\, chia khúc 4.096 ký tự với cờ m=1 cho khúc còn tiếp; tham số a=T,f=100,q=2 nghĩa là truyền và hiện ngay, định dạng PNG, không trả lời; c/r là số cột và hàng ô chữ ảnh chiếm, i là id ảnh, C=1 bảo terminal không dời con trỏ (terminal-image.ts:232–276). Ảnh JPEG, GIF, WebP cần một hàm chuyển sang PNG do ứng dụng đăng ký; thiếu nó thì hiện chữ thay thế (image.ts:24–31). iTerm2 dùng OSC 1337 với inline=1 và kích thước byte (terminal-image.ts:299–325). Điều quan trọng với TUI là ảnh phải khớp vào mô hình dòng:

if (caps.images && data) {	if (caps.images === "kitty" && this.imageId === undefined) {		this.imageId = allocateImageId();	}	const result = renderImage(data, dimensions, {		maxWidthCells: maxWidth,		maxHeightCells: maxHeight,		imageId: this.imageId,		moveCursor: false,	});	if (result) {		// Store the image ID for later cleanup		if (result.imageId) {			this.imageId = result.imageId;		}		if (caps.images === "kitty") {			// For Kitty: C=1 prevents cursor movement.			// Don't need the cursor movement.			lines = [result.sequence];			// Return `rows` lines so TUI accounts for image height.			for (let i = 0; i < result.rows - 1; i++) {				lines.push("");			}		} else {			// Return `rows` lines so TUI accounts for image height.			// First (rows-1) lines are empty and cleared before the image is drawn.			// Last line: move cursor back up, draw the image, then move back down			// so TUI cursor accounting stays inside the scroll area.			lines = [];			for (let i = 0; i < result.rows - 1; i++) {				lines.push("");			}			const rowOffset = result.rows - 1;			const moveUp = rowOffset > 0 ? `\x1b[${rowOffset}A` : "";			lines.push(moveUp + result.sequence);		}

Ảnh cao N hàng ô chữ trả về đúng N dòng, nên phép đếm dòng của cả hai renderer vẫn đúng. Với Kitty, chuỗi ảnh nằm ở dòng đầu và N − 1 dòng rỗng giữ chỗ. Với iTerm2, N − 1 dòng đầu rỗng, còn dòng cuối là lệnh lên N − 1 dòng rồi tới chuỗi ảnh; theo chú thích trong code, việc vẽ ảnh đưa con trỏ trở xuống, nên phép đếm dòng của TUI vẫn nằm trong vùng cuộn. Kích thước ô theo pixel, cần để tính N, được hỏi bằng CSI 16 t lúc khởi động; khi có câu trả lời, TUI gọi invalidate() cho cả cây để ảnh tính lại (tui.ts:1217–1235).

Dòng ảnh không bị nối reset và không bị ghép overlay. TuiMainScreen mở rộng vùng thay đổi để bao trọn các hàng một ảnh chiếm, xoá ảnh cũ theo id bằng a=d,d=I trước khi vẽ, và vẽ lại toàn bộ nếu việc chừa hàng cho ảnh sẽ làm màn hình cuộn (tui-main-screen.ts:210–245). TuiAltScreen còn làm thêm hai việc. Ảnh đã tải lên terminal được dùng lại bằng lệnh đặt chỗ a=p thay vì truyền lại cả dữ liệu, với giới hạn 16 ảnh, 32 MiB dữ liệu truyền và 64 MiB ước tính sau giải mã cho các ảnh đang khuất (tui-alt-screen.ts:445–493). Và ảnh bị cuộn khuất một phần được cắt bằng tham số y, h, r để chỉ hiện phần nằm trong viewport (terminal-image.ts:464–476).

Phần native#

Phần lớn những gì TUI cần đều đi qua terminal bằng chuỗi điều khiển. Ba thứ thì không: đọc clipboard của hệ điều hành (văn bản, ảnh, danh sách file, cho phím dán ảnh), biết phím bổ trợ nào đang được giữ ngay lúc này, và bật chế độ nhập VT của console Windows. packages/tui/native/ chứa ba addon nhỏ viết bằng C và Objective-C cho đúng ba việc đó, kèm bản dựng sẵn cho x64 và arm64:

export interface NativeClipboard {	/** Undefined means unavailable, null means no text; transfer failures reject. */	getText(): Promise<string | null | undefined>;	/** Undefined means unavailable, null means no image; transfer failures reject. */	getImage(): Promise<Uint8Array | null | undefined>;	/** POSIX paths of file URLs on the clipboard. Undefined means unsupported, null means no files. */	getFilePaths?(): Promise<string[] | null | undefined>;	/** Linux uses command-line tools to retain clipboard ownership instead. */	setText?(text: string): Promise<void>;}type NativePlatformHelper = NativeClipboard & {	enableVirtualTerminalInput?: () => boolean;	isModifierPressed?: (name: ModifierKey) => boolean;};⋯ lược bớt dòng 24–54export function getNativePlatformHelper(): NativePlatformHelper | undefined {	if (process.platform !== "darwin" && process.platform !== "win32") return undefined;	return loadNativePlatformHelper(process.platform);}/** Load a clipboard helper without opening the display until a read is requested. */export function getNativeClipboard(): NativeClipboard | undefined {	if (process.platform !== "linux") return getNativePlatformHelper();	if (!process.env.DISPLAY) return undefined;	return loadNativePlatformHelper("linux", "-x11");}

Mỗi hàm clipboard trả về một Promise và phân biệt ba trường hợp: undefined nghĩa là không dùng được, null nghĩa là clipboard không có loại dữ liệu đó, còn lỗi truyền dữ liệu thì reject. Trên Linux, helper chỉ được nạp khi có DISPLAY, và theo chú thích ở dòng 25 chỉ việc nạp module được cache, không phải tình trạng của màn hình, vì một display bị ngắt có thể kết nối lại. Addon không cần header của Node: napi.h tự tìm một tập nhỏ hàm N-API lúc chạy, “from Node or Bun, without Node headers or a link-time dependency on a particular runtime” (napi.h:4–5). File .node được tìm ở vài chỗ: cạnh gói đã cài, cạnh module đang chạy, và cạnh file thực thi, để bản binary đóng gói một file cũng tìm thấy (native-module-path.ts:14–31). Không tìm thấy thì hàm trả về undefined và người gọi đi đường lui; coding agent khi đó đọc clipboard bằng các lệnh như wl-paste hay xclip (clipboard-image.ts:173).

Trạng thái phím bổ trợ giải quyết một vấn đề cụ thể của bàn phím: Terminal.app của macOS và console Windows có thể gửi Enter trần (\r) cho cả Shift+Enter. Khi nhận đúng một \r trên hai nền tảng đó, ProcessTerminal hỏi helper xem Shift có đang được giữ không, và nếu có thì đổi chuỗi thành Shift+Enter dạng CSI u:

private forwardInputSequence(sequence: string): void {	if (!this.inputHandler) return;	const shouldDetectNativeShiftEnter =		sequence === "\r" && (isAppleTerminalSession() || process.platform === "win32");	const input = normalizeNativeShiftEnterInput(		sequence,		shouldDetectNativeShiftEnter,		shouldDetectNativeShiftEnter && isNativeModifierPressed("shift"),	);	this.inputHandler(input);}