@earendil-works/pi-tui 0.82.1 → 0.84.0

package/dist/tui.js

@@ -1,48 +1,13 @@
 /**
  * Minimal TUI implementation with differential rendering
  */
-import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { isKeyRelease, matchesKey } from "./keys.js";
 import { isOsc11BackgroundColorResponse, parseOsc11BackgroundColor, parseTerminalColorSchemeReport, } from "./terminal-colors.js";
-import { deleteKittyImage, getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
+import { getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
 import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
-const KITTY_SEQUENCE_PREFIX = "\x1b_G";
-function parseKittyImageHeader(line) {
-    const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
-    if (sequenceStart === -1)
-        return undefined;
-    const paramsStart = sequenceStart + KITTY_SEQUENCE_PREFIX.length;
-    const paramsEnd = line.indexOf(";", paramsStart);
-    if (paramsEnd === -1)
-        return undefined;
-    const ids = [];
-    let rows = 1;
-    const params = line.slice(paramsStart, paramsEnd);
-    for (const param of params.split(",")) {
-        const [key, value] = param.split("=", 2);
-        if (value === undefined)
-            continue;
-        const numberValue = Number(value);
-        if (!Number.isInteger(numberValue) || numberValue <= 0 || numberValue > 0xffffffff)
-            continue;
-        if (key === "i") {
-            ids.push(numberValue);
-        }
-        else if (key === "r") {
-            rows = numberValue;
-        }
-    }
-    return { ids, rows };
-}
-function extractKittyImageIds(line) {
-    return parseKittyImageHeader(line)?.ids ?? [];
-}
-function extractKittyImageRows(line) {
-    return parseKittyImageHeader(line)?.rows ?? 1;
-}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -68,9 +33,6 @@ function parseSizeValue(value, referenceSize) {
     }
     return undefined;
 }
-function isTermuxSession() {
-    return Boolean(process.env.TERMUX_VERSION);
-}
 /**
  * Container - a component that contains other components
  */
@@ -107,26 +69,47 @@ export class Container {
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
-export class TUI extends Container {
+const SEGMENT_RESET = "\x1b[0m\x1b]8;;\x07";
+/** Composite overlay content into a terminal line at a fixed column. */
+export function compositeTuiLine(baseLine, overlayLine, startCol, overlayWidth, totalWidth) {
+    if (isImageLine(baseLine))
+        return baseLine;
+    const afterStart = startCol + overlayWidth;
+    const base = extractSegments(baseLine, startCol, afterStart, totalWidth - afterStart, true);
+    const overlay = sliceWithWidth(overlayLine, 0, overlayWidth, true);
+    const beforePad = Math.max(0, startCol - base.beforeWidth);
+    const overlayPad = Math.max(0, overlayWidth - overlay.width);
+    const actualBeforeWidth = Math.max(startCol, base.beforeWidth);
+    const actualOverlayWidth = Math.max(overlayWidth, overlay.width);
+    const afterTarget = Math.max(0, totalWidth - actualBeforeWidth - actualOverlayWidth);
+    const afterPad = Math.max(0, afterTarget - base.afterWidth);
+    const result = base.before +
+        " ".repeat(beforePad) +
+        SEGMENT_RESET +
+        overlay.text +
+        " ".repeat(overlayPad) +
+        SEGMENT_RESET +
+        base.after +
+        " ".repeat(afterPad);
+    return visibleWidth(result) <= totalWidth ? result : sliceByColumn(result, 0, totalWidth, true);
+}
+export const VIEWPORT_TUI = Symbol.for("@earendil-works/pi-tui/viewport");
+export function isViewportTUI(tui) {
+    return tui[VIEWPORT_TUI] === true;
+}
+export class TuiBase extends Container {
     terminal;
-    previousLines = [];
-    previousKittyImageIds = new Set();
-    previousWidth = 0;
-    previousHeight = 0;
     focusedComponent = null;
     inputListeners = new Set();
     /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
     onDebug;
     renderRequested = false;
+    immediateRenderScheduled = false;
     renderTimer;
     lastRenderAt = 0;
     static MIN_RENDER_INTERVAL_MS = 16;
-    cursorRow = 0; // Logical cursor row (end of rendered content)
-    hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
     showHardwareCursor = process.env.PI_HARDWARE_CURSOR === "1";
-    clearOnShrink = process.env.PI_CLEAR_ON_SHRINK === "1"; // Clear empty rows when content shrinks (default: off)
-    maxLinesRendered = 0; // Track terminal's working area (max lines ever rendered)
-    previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
+    clearOnShrink = process.env.PI_CLEAR_ON_SHRINK === "1";
     fullRedrawCount = 0;
     stopped = false;
     pendingOsc11BackgroundReplies = 0;
@@ -137,6 +120,9 @@ export class TUI extends Container {
     // Overlay stack for modal components rendered on top of base content
     focusOrderCounter = 0;
     overlayStack = [];
+    get hasOverlayEntries() {
+        return this.overlayStack.length > 0;
+    }
     overlayFocusRestore = { status: "inactive" };
     constructor(terminal, showHardwareCursor, logDirectory) {
         super();
@@ -146,6 +132,11 @@ export class TUI extends Container {
             this.showHardwareCursor = showHardwareCursor;
         }
     }
+    resetRenderState() { }
+    beforeTerminalStart() { }
+    afterTerminalStart() { }
+    beforeTerminalStop(_options) { }
+    afterTerminalStop(_options) { }
     get fullRedraws() {
         return this.fullRedrawCount;
     }
@@ -172,6 +163,9 @@ export class TUI extends Container {
     setClearOnShrink(enabled) {
         this.clearOnShrink = enabled;
     }
+    getFocusedComponent() {
+        return this.focusedComponent;
+    }
     setFocus(component) {
         this.setFocusInternal({ component, overlayFocusRestore: "clear" });
     }
@@ -272,8 +266,11 @@ export class TUI extends Container {
             }
         }
     }
+    getMountedRoots() {
+        return this.children;
+    }
     isComponentMounted(component) {
-        return this.children.some((child) => this.containsComponent(child, component));
+        return this.getMountedRoots().some((child) => this.containsComponent(child, component));
     }
     containsComponent(root, target) {
         if (root === target)
@@ -426,13 +423,16 @@ export class TUI extends Container {
         return topmost;
     }
     invalidate() {
-        super.invalidate();
+        for (const root of this.getMountedRoots())
+            root.invalidate();
         for (const overlay of this.overlayStack)
-            overlay.component.invalidate?.();
+            overlay.component.invalidate();
     }
     start() {
         this.stopped = false;
-        this.terminal.start((data) => this.handleInput(data), () => this.requestRender());
+        this.beforeTerminalStart();
+        this.terminal.start((data) => this.handleTerminalInput(data), () => this.requestRender());
+        this.afterTerminalStart();
         this.terminal.hideCursor();
         if (this.terminalColorSchemeNotificationsEnabled) {
             this.terminal.write("\x1b[?2031h");
@@ -473,54 +473,29 @@ export class TUI extends Container {
         // Response format: CSI 6 ; height ; width t
         this.terminal.write("\x1b[16t");
     }
-    stop() {
+    stop(options = {}) {
         this.stopped = true;
-        if (this.renderTimer) {
-            clearTimeout(this.renderTimer);
-            this.renderTimer = undefined;
-        }
+        this.cancelRenderTimer();
         if (this.terminalColorSchemeNotificationsEnabled) {
             this.terminal.write("\x1b[?2031l");
         }
-        // Move cursor to the end of the content to prevent overwriting/artifacts on exit
-        if (this.previousLines.length > 0) {
-            // Overwrite the inverted cursor with a normal space to clear the artifact
-            this.terminal.write(" ");
-            const targetRow = this.previousLines.length; // Line after the last content
-            const lineDiff = targetRow - this.hardwareCursorRow;
-            if (lineDiff > 0) {
-                this.terminal.write(`\x1b[${lineDiff}B`);
-            }
-            else if (lineDiff < 0) {
-                this.terminal.write(`\x1b[${-lineDiff}A`);
-            }
-            this.terminal.write("\r\n");
-        }
+        this.beforeTerminalStop(options);
         this.terminal.showCursor();
         this.terminal.stop();
+        this.afterTerminalStop(options);
+    }
+    renderNow(force = false) {
+        if (force)
+            this.resetRenderState();
+        this.renderRequested = false;
+        this.cancelRenderTimer();
+        this.lastRenderAt = performance.now();
+        this.doRender();
     }
     requestRender(force = false) {
         if (force) {
-            this.previousLines = [];
-            this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
-            this.previousHeight = -1; // -1 triggers heightChanged, forcing a full clear
-            this.cursorRow = 0;
-            this.hardwareCursorRow = 0;
-            this.maxLinesRendered = 0;
-            this.previousViewportTop = 0;
-            if (this.renderTimer) {
-                clearTimeout(this.renderTimer);
-                this.renderTimer = undefined;
-            }
-            this.renderRequested = true;
-            process.nextTick(() => {
-                if (this.stopped || !this.renderRequested) {
-                    return;
-                }
-                this.renderRequested = false;
-                this.lastRenderAt = performance.now();
-                this.doRender();
-            });
+            this.resetRenderState();
+            this.requestImmediateRender();
             return;
         }
         if (this.renderRequested)
@@ -528,12 +503,36 @@ export class TUI extends Container {
         this.renderRequested = true;
         process.nextTick(() => this.scheduleRender());
     }
+    requestImmediateRender() {
+        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();
+        });
+    }
+    cancelRenderTimer() {
+        if (!this.renderTimer)
+            return;
+        clearTimeout(this.renderTimer);
+        this.renderTimer = undefined;
+    }
     scheduleRender() {
         if (this.stopped || this.renderTimer || !this.renderRequested) {
             return;
         }
         const elapsed = performance.now() - this.lastRenderAt;
-        const delay = Math.max(0, TUI.MIN_RENDER_INTERVAL_MS - elapsed);
+        const delay = Math.max(0, TuiBase.MIN_RENDER_INTERVAL_MS - elapsed);
         this.renderTimer = setTimeout(() => {
             this.renderTimer = undefined;
             if (this.stopped || !this.renderRequested) {
@@ -547,7 +546,7 @@ export class TUI extends Container {
             }
         }, delay);
     }
-    handleInput(data) {
+    handleTerminalInput(data) {
         if (this.consumeOsc11BackgroundResponse(data)) {
             return;
         }
@@ -616,7 +615,9 @@ export class TUI extends Container {
                 return;
             }
             this.focusedComponent.handleInput(data);
-            this.requestRender();
+            // 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();
         }
     }
     consumeOsc11BackgroundResponse(data) {
@@ -842,9 +843,8 @@ export class TUI extends Container {
         }
         return result;
     }
-    static SEGMENT_RESET = "\x1b[0m\x1b]8;;\x07";
     applyLineResets(lines) {
-        const reset = TUI.SEGMENT_RESET;
+        const reset = SEGMENT_RESET;
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
             if (!isImageLine(line)) {
@@ -853,104 +853,8 @@ export class TUI extends Container {
         }
         return lines;
     }
-    collectKittyImageIds(lines) {
-        const ids = new Set();
-        for (const line of lines) {
-            for (const id of extractKittyImageIds(line)) {
-                ids.add(id);
-            }
-        }
-        return ids;
-    }
-    deleteKittyImages(ids) {
-        let buffer = "";
-        for (const id of ids) {
-            buffer += deleteKittyImage(id);
-        }
-        return buffer;
-    }
-    getKittyImageReservedRows(lines, index, maxIndex = lines.length - 1) {
-        const rows = extractKittyImageRows(lines[index] ?? "");
-        if (rows <= 1)
-            return 1;
-        const maxRows = Math.min(rows, maxIndex - index + 1, lines.length - index);
-        let reservedRows = 1;
-        while (reservedRows < maxRows) {
-            const line = lines[index + reservedRows] ?? "";
-            if (isImageLine(line) || visibleWidth(line) > 0)
-                break;
-            reservedRows++;
-        }
-        return reservedRows;
-    }
-    expandChangedRangeForKittyImages(firstChanged, lastChanged, newLines) {
-        let expandedFirstChanged = firstChanged;
-        let expandedLastChanged = lastChanged;
-        const expandForLines = (lines) => {
-            for (let i = 0; i < lines.length; i++) {
-                if (extractKittyImageIds(lines[i]).length === 0)
-                    continue;
-                const blockEnd = i + this.getKittyImageReservedRows(lines, i) - 1;
-                if (i >= firstChanged || (i <= lastChanged && blockEnd >= firstChanged)) {
-                    expandedFirstChanged = Math.min(expandedFirstChanged, i);
-                    expandedLastChanged = Math.max(expandedLastChanged, blockEnd);
-                }
-            }
-        };
-        expandForLines(this.previousLines);
-        expandForLines(newLines);
-        return { firstChanged: expandedFirstChanged, lastChanged: expandedLastChanged };
-    }
-    deleteChangedKittyImages(firstChanged, lastChanged) {
-        if (firstChanged < 0 || lastChanged < firstChanged)
-            return "";
-        const ids = new Set();
-        const maxLine = Math.min(lastChanged, this.previousLines.length - 1);
-        for (let i = firstChanged; i <= maxLine; i++) {
-            for (const id of extractKittyImageIds(this.previousLines[i] ?? "")) {
-                ids.add(id);
-            }
-        }
-        return this.deleteKittyImages(ids);
-    }
-    /** Splice overlay content into a base line at a specific column. Single-pass optimized. */
     compositeLineAt(baseLine, overlayLine, startCol, overlayWidth, totalWidth) {
-        if (isImageLine(baseLine))
-            return baseLine;
-        // Single pass through baseLine extracts both before and after segments
-        const afterStart = startCol + overlayWidth;
-        const base = extractSegments(baseLine, startCol, afterStart, totalWidth - afterStart, true);
-        // Extract overlay with width tracking (strict=true to exclude wide chars at boundary)
-        const overlay = sliceWithWidth(overlayLine, 0, overlayWidth, true);
-        // Pad segments to target widths
-        const beforePad = Math.max(0, startCol - base.beforeWidth);
-        const overlayPad = Math.max(0, overlayWidth - overlay.width);
-        const actualBeforeWidth = Math.max(startCol, base.beforeWidth);
-        const actualOverlayWidth = Math.max(overlayWidth, overlay.width);
-        const afterTarget = Math.max(0, totalWidth - actualBeforeWidth - actualOverlayWidth);
-        const afterPad = Math.max(0, afterTarget - base.afterWidth);
-        // Compose result
-        const r = TUI.SEGMENT_RESET;
-        const result = base.before +
-            " ".repeat(beforePad) +
-            r +
-            overlay.text +
-            " ".repeat(overlayPad) +
-            r +
-            base.after +
-            " ".repeat(afterPad);
-        // CRITICAL: Always verify and truncate to terminal width.
-        // This is the final safeguard against width overflow which would crash the TUI.
-        // Width tracking can drift from actual visible width due to:
-        // - Complex ANSI/OSC sequences (hyperlinks, colors)
-        // - Wide characters at segment boundaries
-        // - Edge cases in segment extraction
-        const resultWidth = visibleWidth(result);
-        if (resultWidth <= totalWidth) {
-            return result;
-        }
-        // Truncate with strict=true to ensure we don't exceed totalWidth
-        return sliceByColumn(result, 0, totalWidth, true);
+        return compositeTuiLine(baseLine, overlayLine, startCol, overlayWidth, totalWidth);
     }
     /**
      * Find and extract cursor position from rendered lines.
@@ -977,385 +881,6 @@ export class TUI extends Container {
         }
         return null;
     }
-    doRender() {
-        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) => {
-            const currentScreenRow = hardwareCursorRow - prevViewportTop;
-            const targetScreenRow = targetRow - viewportTop;
-            return targetScreenRow - currentScreenRow;
-        };
-        // Render all components to get new lines
-        let newLines = this.render(width);
-        // Composite overlays into the rendered lines (before differential compare)
-        if (this.overlayStack.length > 0) {
-            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);
-        // Helper to clear scrollback and viewport and render all new lines
-        const fullRender = (clear) => {
-            this.fullRedrawCount += 1;
-            let buffer = "\x1b[?2026h"; // Begin synchronized output
-            if (clear) {
-                buffer += this.deleteKittyImages(this.previousKittyImageIds);
-                buffer += "\x1b[2J\x1b[H\x1b[3J"; // Clear screen, home, then clear scrollback
-            }
-            for (let i = 0; i < newLines.length; i++) {
-                if (i > 0)
-                    buffer += "\r\n";
-                const line = newLines[i];
-                const isImage = isImageLine(line);
-                const imageReservedRows = isImage ? this.getKittyImageReservedRows(newLines, i) : 1;
-                if (imageReservedRows > 1 && imageReservedRows <= height) {
-                    for (let row = 1; row < imageReservedRows; row++) {
-                        buffer += "\r\n";
-                    }
-                    buffer += `\x1b[${imageReservedRows - 1}A`;
-                    buffer += line;
-                    buffer += `\x1b[${imageReservedRows - 1}B`;
-                    i += imageReservedRows - 1;
-                    continue;
-                }
-                buffer += line;
-            }
-            buffer += "\x1b[?2026l"; // End synchronized output
-            this.terminal.write(buffer);
-            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;
-        };
-        const debugRedraw = process.env.PI_DEBUG_REDRAW === "1";
-        const logRedraw = (reason) => {
-            if (!debugRedraw)
-                return;
-            const logPath = path.join(this.logDirectory, "pi-debug.log");
-            const msg = `[${new Date().toISOString()}] fullRender: ${reason} (prev=${this.previousLines.length}, new=${newLines.length}, height=${height})\n`;
-            fs.mkdirSync(path.dirname(logPath), { recursive: true });
-            fs.appendFileSync(logPath, msg);
-        };
-        // 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() or PI_CLEAR_ON_SHRINK=0 env var
-        if (this.clearOnShrink && newLines.length < this.maxLinesRendered && this.overlayStack.length === 0) {
-            logRedraw(`clearOnShrink (maxLinesRendered=${this.maxLinesRendered})`);
-            fullRender(true);
-            return;
-        }
-        // Find first and last changed lines
-        let 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;
-        // No changes - but still need to update hardware cursor position if it moved
-        if (firstChanged === -1) {
-            this.positionHardwareCursor(cursorPos, newLines.length);
-            this.previousViewportTop = prevViewportTop;
-            this.previousHeight = height;
-            return;
-        }
-        // All changes are in deleted lines (nothing to render, just clear)
-        if (firstChanged >= newLines.length) {
-            if (this.previousLines.length > newLines.length) {
-                let buffer = "\x1b[?2026h";
-                buffer += this.deleteChangedKittyImages(firstChanged, lastChanged);
-                // Move to end of new content (clamp to 0 for empty content)
-                const targetRow = Math.max(0, newLines.length - 1);
-                if (targetRow < prevViewportTop) {
-                    logRedraw(`deleted lines moved viewport up (${targetRow} < ${prevViewportTop})`);
-                    fullRender(true);
-                    return;
-                }
-                const lineDiff = computeLineDiff(targetRow);
-                if (lineDiff > 0)
-                    buffer += `\x1b[${lineDiff}B`;
-                else if (lineDiff < 0)
-                    buffer += `\x1b[${-lineDiff}A`;
-                buffer += "\r";
-                // Clear extra lines without scrolling
-                const extraLines = this.previousLines.length - newLines.length;
-                if (extraLines > height) {
-                    logRedraw(`extraLines > height (${extraLines} > ${height})`);
-                    fullRender(true);
-                    return;
-                }
-                const clearStartOffset = newLines.length === 0 ? 0 : 1;
-                if (extraLines > 0 && clearStartOffset > 0) {
-                    buffer += `\x1b[${clearStartOffset}B`;
-                }
-                for (let i = 0; i < extraLines; i++) {
-                    buffer += "\r\x1b[2K";
-                    if (i < extraLines - 1)
-                        buffer += "\x1b[1B";
-                }
-                const moveBack = Math.max(0, extraLines - 1 + clearStartOffset);
-                if (moveBack > 0) {
-                    buffer += `\x1b[${moveBack}A`;
-                }
-                buffer += "\x1b[?2026l";
-                this.terminal.write(buffer);
-                this.cursorRow = targetRow;
-                this.hardwareCursorRow = targetRow;
-            }
-            this.positionHardwareCursor(cursorPos, newLines.length);
-            this.previousLines = newLines;
-            this.previousKittyImageIds = this.collectKittyImageIds(newLines);
-            this.previousWidth = width;
-            this.previousHeight = height;
-            this.previousViewportTop = prevViewportTop;
-            return;
-        }
-        // 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;
-        }
-        // Render from first changed line to end
-        // Build buffer with all updates wrapped in synchronized output
-        let buffer = "\x1b[?2026h"; // Begin synchronized output
-        buffer += 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) {
-                buffer += `\x1b[${moveToBottom}B`;
-            }
-            const scroll = moveTargetRow - prevViewportBottom;
-            buffer += "\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) {
-            buffer += `\x1b[${lineDiff}B`; // Move down
-        }
-        else if (lineDiff < 0) {
-            buffer += `\x1b[${-lineDiff}A`; // Move up
-        }
-        buffer += 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)
-                buffer += "\r\n";
-            const line = newLines[i];
-            const isImage = isImageLine(line);
-            const imageReservedRows = isImage ? this.getKittyImageReservedRows(newLines, i, renderEnd) : 1;
-            if (imageReservedRows > 1) {
-                const imageStartScreenRow = i - viewportTop;
-                if (imageStartScreenRow < 0 || imageStartScreenRow + imageReservedRows > height) {
-                    logRedraw(`kitty image pre-clear would scroll (${imageStartScreenRow} + ${imageReservedRows} > ${height})`);
-                    fullRender(true);
-                    return;
-                }
-                buffer += "\x1b[2K";
-                for (let row = 1; row < imageReservedRows; row++) {
-                    buffer += "\r\n\x1b[2K";
-                }
-                buffer += `\x1b[${imageReservedRows - 1}A`;
-                buffer += line;
-                buffer += `\x1b[${imageReservedRows - 1}B`;
-                i += imageReservedRows - 1;
-                continue;
-            }
-            buffer += "\x1b[2K"; // Clear current line
-            if (!isImage && visibleWidth(line) > width) {
-                // Log all lines to crash file for debugging
-                const crashLogPath = path.join(this.logDirectory, "pi-crash.log");
-                const crashData = [
-                    `Crash at ${new Date().toISOString()}`,
-                    `Terminal width: ${width}`,
-                    `Line ${i} visible width: ${visibleWidth(line)}`,
-                    "",
-                    "=== All rendered lines ===",
-                    ...newLines.map((l, idx) => `[${idx}] (w=${visibleWidth(l)}) ${l}`),
-                    "",
-                ].join("\n");
-                fs.mkdirSync(path.dirname(crashLogPath), { recursive: true });
-                fs.writeFileSync(crashLogPath, crashData);
-                // Clean up terminal state before throwing
-                this.stop();
-                const errorMsg = [
-                    `Rendered line ${i} exceeds terminal width (${visibleWidth(line)} > ${width}).`,
-                    "",
-                    "This is likely caused by a custom TUI component not truncating its output.",
-                    "Use visibleWidth() to measure and truncateToWidth() to truncate lines.",
-                    "",
-                    `Debug log written to: ${crashLogPath}`,
-                ].join("\n");
-                throw new Error(errorMsg);
-            }
-            buffer += line;
-        }
-        // Track where cursor ended up after rendering
-        let finalCursorRow = renderEnd;
-        // If we had more lines before, clear them and move cursor back
-        if (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;
-                buffer += `\x1b[${moveDown}B`;
-                finalCursorRow = newLines.length - 1;
-            }
-            const extraLines = this.previousLines.length - newLines.length;
-            for (let i = newLines.length; i < this.previousLines.length; i++) {
-                buffer += "\r\n\x1b[2K";
-            }
-            // Move cursor back to end of new content
-            buffer += `\x1b[${extraLines}A`;
-        }
-        buffer += "\x1b[?2026l"; // End synchronized output
-        if (process.env.PI_TUI_DEBUG === "1") {
-            const debugDir = "/tmp/tui";
-            fs.mkdirSync(debugDir, { recursive: true });
-            const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
-            const debugData = [
-                `firstChanged: ${firstChanged}`,
-                `viewportTop: ${viewportTop}`,
-                `cursorRow: ${this.cursorRow}`,
-                `height: ${height}`,
-                `lineDiff: ${lineDiff}`,
-                `hardwareCursorRow: ${hardwareCursorRow}`,
-                `renderEnd: ${renderEnd}`,
-                `finalCursorRow: ${finalCursorRow}`,
-                `cursorPos: ${JSON.stringify(cursorPos)}`,
-                `newLines.length: ${newLines.length}`,
-                `previousLines.length: ${this.previousLines.length}`,
-                "",
-                "=== newLines ===",
-                JSON.stringify(newLines, null, 2),
-                "",
-                "=== previousLines ===",
-                JSON.stringify(this.previousLines, null, 2),
-                "",
-                "=== buffer ===",
-                JSON.stringify(buffer),
-            ].join("\n");
-            fs.writeFileSync(debugPath, debugData);
-        }
-        // Write entire buffer at once
-        this.terminal.write(buffer);
-        // 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 IME
-        this.positionHardwareCursor(cursorPos, newLines.length);
-        this.previousLines = newLines;
-        this.previousKittyImageIds = this.collectKittyImageIds(newLines);
-        this.previousWidth = width;
-        this.previousHeight = height;
-    }
-    /**
-     * Position the hardware cursor for IME candidate window.
-     * @param cursorPos The cursor position extracted from rendered output, or null
-     * @param totalLines Total number of rendered lines
-     */
-    positionHardwareCursor(cursorPos, totalLines) {
-        if (!cursorPos || totalLines <= 0) {
-            this.terminal.hideCursor();
-            return;
-        }
-        // Clamp cursor position to valid range
-        const targetRow = Math.max(0, Math.min(cursorPos.row, totalLines - 1));
-        const targetCol = Math.max(0, cursorPos.col);
-        // Move cursor from current position to target
-        const rowDelta = targetRow - this.hardwareCursorRow;
-        let buffer = "";
-        if (rowDelta > 0) {
-            buffer += `\x1b[${rowDelta}B`; // Move down
-        }
-        else if (rowDelta < 0) {
-            buffer += `\x1b[${-rowDelta}A`; // Move up
-        }
-        // Move to absolute column (1-indexed)
-        buffer += `\x1b[${targetCol + 1}G`;
-        if (buffer) {
-            this.terminal.write(buffer);
-        }
-        this.hardwareCursorRow = targetRow;
-        if (this.showHardwareCursor) {
-            this.terminal.showCursor();
-        }
-        else {
-            this.terminal.hideCursor();
-        }
-    }
     /**
      * Query the terminal's default background color with OSC 11 (`ESC ] 11 ; ? BEL`).
      * @param timeoutMs Query timeout in milliseconds.