@jecruz/merc-tui 0.1.3 → 0.1.6

package/dist/tui.js

@@ -2,13 +2,70 @@
  * 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 { deleteKittyImage, getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
 import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
 const KITTY_SEQUENCE_PREFIX = "\x1b_G";
+const MAX_RENDER_WRITE_CHARS = 1024 * 1024;
+/**
+ * Streams terminal output in 1 MiB chunks so a full render never forms one string large enough to exceed V8's limit.
+ *
+ * `append()` fills the current chunk and flushes it when full. Oversized input is split at chunk boundaries, preserving
+ * surrogate pairs so each write remains valid UTF-16. Callers append synchronized-output begin/end sequences themselves;
+ * the final `flush()` writes any remainder, including the end sequence.
+ */
+class BoundedTerminalWriter {
+    buffer = "";
+    writtenChars = 0;
+    write;
+    constructor(write) {
+        this.write = write;
+    }
+    /**
+     * Append terminal data, flushing full chunks as needed. Callers must call `flush()` after the final append.
+     * @param value Terminal data to write in order; oversized values are split without splitting surrogate pairs.
+     */
+    append(value) {
+        let offset = 0;
+        while (offset < value.length) {
+            const capacity = MAX_RENDER_WRITE_CHARS - this.buffer.length;
+            if (capacity === 0) {
+                this.flush();
+                continue;
+            }
+            let end = Math.min(value.length, offset + capacity);
+            if (end < value.length &&
+                value.charCodeAt(end - 1) >= 0xd800 &&
+                value.charCodeAt(end - 1) <= 0xdbff &&
+                value.charCodeAt(end) >= 0xdc00 &&
+                value.charCodeAt(end) <= 0xdfff) {
+                end--;
+            }
+            if (end === offset) {
+                this.flush();
+                continue;
+            }
+            this.buffer += value.slice(offset, end);
+            offset = end;
+            if (this.buffer.length === MAX_RENDER_WRITE_CHARS) {
+                this.flush();
+            }
+        }
+    }
+    /** Write the current chunk, if any, and retain only its character count for debug output. */
+    flush() {
+        if (!this.buffer)
+            return;
+        this.write(this.buffer);
+        this.writtenChars += this.buffer.length;
+        this.buffer = "";
+    }
+    get length() {
+        return this.writtenChars + this.buffer.length;
+    }
+}
 function parseKittyImageHeader(line) {
     const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
     if (sequenceStart === -1)
@@ -120,6 +177,7 @@ export class TUI extends Container {
     /** 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;
@@ -131,13 +189,20 @@ export class TUI extends Container {
     previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
     skippedOffscreenChangeRange;
     fullRedrawCount = 0;
+    logDirectory;
     stopped = false;
     // Overlay stack for modal components rendered on top of base content
     focusOrderCounter = 0;
     overlayStack = [];
-    constructor(terminal, showHardwareCursor) {
+    overlayFocusRestore = { status: "inactive" };
+    /**
+     * @param logDirectory Private directory for redraw debug logs and render crash dumps. Without one,
+     * neither is written.
+     */
+    constructor(terminal, showHardwareCursor, logDirectory) {
         super();
         this.terminal = terminal;
+        this.logDirectory = logDirectory;
         if (showHardwareCursor !== undefined) {
             this.showHardwareCursor = showHardwareCursor;
         }
@@ -153,7 +218,7 @@ export class TUI extends Container {
             return;
         this.showHardwareCursor = enabled;
         if (!enabled) {
-            this.terminal.hideCursor();
+            this.hideTerminalCursor();
         }
         this.requestRender();
     }
@@ -169,31 +234,54 @@ export class TUI extends Container {
         this.clearOnShrink = enabled;
     }
     setFocus(component) {
+        this.setFocusInternal({ component, overlayFocusRestore: "clear" });
+    }
+    setFocusInternal({ component, overlayFocusRestore, }) {
         const previousFocus = this.focusedComponent;
         let nextFocus = component;
         const previousFocusedOverlay = previousFocus
             ? this.overlayStack.find((entry) => entry.component === previousFocus && this.isOverlayVisible(entry))
             : undefined;
         const nextFocusIsOverlay = nextFocus ? this.overlayStack.some((entry) => entry.component === nextFocus) : false;
+        const restoreState = this.getVisibleOverlayFocusRestore();
         if (nextFocus && !nextFocusIsOverlay) {
-            const restoreOverlay = this.getRestoreFocusOverlay();
-            if (restoreOverlay?.restoreFocus.status === "blocked" &&
-                restoreOverlay.restoreFocus.blockedBy === previousFocus) {
-                restoreOverlay.restoreFocus = { status: "eligible" };
-                nextFocus = restoreOverlay.component;
+            if (restoreState.status === "blocked" && restoreState.blockedBy === previousFocus) {
+                if (restoreState.resume.status === "focus-target" || !this.isComponentMounted(restoreState.blockedBy)) {
+                    nextFocus = this.resolveBlockedOverlayFocusResume(restoreState);
+                }
+                else {
+                    this.overlayFocusRestore = {
+                        status: "blocked",
+                        overlay: restoreState.overlay,
+                        blockedBy: nextFocus,
+                        resume: restoreState.resume,
+                    };
+                }
             }
             else if (previousFocusedOverlay &&
-                previousFocusedOverlay.restoreFocus.status !== "inactive" &&
+                restoreState.status !== "inactive" &&
+                restoreState.overlay === previousFocusedOverlay &&
                 !this.isOverlayFocusAncestor(previousFocusedOverlay, nextFocus)) {
-                previousFocusedOverlay.restoreFocus = { status: "blocked", blockedBy: nextFocus };
+                this.overlayFocusRestore = {
+                    status: "blocked",
+                    overlay: previousFocusedOverlay,
+                    blockedBy: nextFocus,
+                    resume: { status: "restore-overlay" },
+                };
+            }
+        }
+        else if (nextFocus === null) {
+            if (restoreState.status === "blocked" && restoreState.blockedBy === previousFocus) {
+                nextFocus = this.resolveBlockedOverlayFocusResume(restoreState);
+            }
+            else if (overlayFocusRestore === "clear") {
+                this.clearOverlayFocusRestore();
             }
         }
-        // Clear focused flag on old component
         if (isFocusable(this.focusedComponent)) {
             this.focusedComponent.focused = false;
         }
         this.focusedComponent = nextFocus;
-        // Set focused flag on new component
         if (isFocusable(nextFocus)) {
             nextFocus.focused = true;
         }
@@ -201,20 +289,31 @@ export class TUI extends Container {
             ? this.overlayStack.find((entry) => entry.component === nextFocus && this.isOverlayVisible(entry))
             : undefined;
         if (focusedOverlay) {
-            this.markOverlayRestoreFocusEligible(focusedOverlay);
+            this.overlayFocusRestore = { status: "eligible", overlay: focusedOverlay };
         }
     }
-    markOverlayRestoreFocusEligible(entry) {
-        for (const overlay of this.overlayStack) {
-            this.clearOverlayRestoreFocus(overlay);
+    clearOverlayFocusRestore() {
+        this.overlayFocusRestore = { status: "inactive" };
+    }
+    clearOverlayFocusRestoreFor(overlay) {
+        if (this.overlayFocusRestore.status !== "inactive" && this.overlayFocusRestore.overlay === overlay) {
+            this.clearOverlayFocusRestore();
         }
-        entry.restoreFocus = { status: "eligible" };
     }
-    clearOverlayRestoreFocus(entry) {
-        entry.restoreFocus = { status: "inactive" };
+    resolveBlockedOverlayFocusResume(restoreState) {
+        if (restoreState.resume.status === "restore-overlay")
+            return restoreState.overlay.component;
+        this.clearOverlayFocusRestore();
+        return restoreState.resume.target;
     }
-    getRestoreFocusOverlay() {
-        return this.overlayStack.find((overlay) => overlay.restoreFocus.status !== "inactive" && this.isOverlayVisible(overlay));
+    getVisibleOverlayFocusRestore() {
+        const restoreState = this.overlayFocusRestore;
+        if (restoreState.status === "inactive")
+            return restoreState;
+        if (!this.overlayStack.includes(restoreState.overlay) || !this.isOverlayVisible(restoreState.overlay)) {
+            return { status: "inactive" };
+        }
+        return restoreState;
     }
     isOverlayFocusAncestor(entry, component) {
         const visited = new Set();
@@ -227,6 +326,23 @@ export class TUI extends Container {
         }
         return false;
     }
+    retargetOverlayPreFocus(removed) {
+        for (const overlay of this.overlayStack) {
+            if (overlay !== removed && overlay.preFocus === removed.component) {
+                overlay.preFocus = removed.preFocus;
+            }
+        }
+    }
+    isComponentMounted(component) {
+        return this.children.some((child) => this.containsComponent(child, component));
+    }
+    containsComponent(root, target) {
+        if (root === target)
+            return true;
+        if (!(root instanceof Container))
+            return false;
+        return root.children.some((child) => this.containsComponent(child, target));
+    }
     /**
      * Show an overlay component with configurable positioning and sizing.
      * Returns a handle to control the overlay's visibility.
@@ -234,25 +350,25 @@ export class TUI extends Container {
     showOverlay(component, options) {
         const entry = {
             component,
-            options,
+            ...(options === undefined ? {} : { options }),
             preFocus: this.focusedComponent,
             hidden: false,
             focusOrder: ++this.focusOrderCounter,
-            restoreFocus: { status: "inactive" },
         };
         this.overlayStack.push(entry);
         // Only focus if overlay is actually visible
         if (!options?.nonCapturing && this.isOverlayVisible(entry)) {
             this.setFocus(component);
         }
-        this.terminal.hideCursor();
+        this.hideTerminalCursor();
         this.requestRender();
         // Return handle for controlling this overlay
         return {
             hide: () => {
                 const index = this.overlayStack.indexOf(entry);
                 if (index !== -1) {
-                    this.clearOverlayRestoreFocus(entry);
+                    this.clearOverlayFocusRestoreFor(entry);
+                    this.retargetOverlayPreFocus(entry);
                     this.overlayStack.splice(index, 1);
                     // Restore focus if this overlay had focus
                     if (this.focusedComponent === component) {
@@ -260,7 +376,7 @@ export class TUI extends Container {
                         this.setFocus(topVisible?.component ?? entry.preFocus);
                     }
                     if (this.overlayStack.length === 0)
-                        this.terminal.hideCursor();
+                        this.hideTerminalCursor();
                     this.requestRender();
                 }
             },
@@ -270,7 +386,7 @@ export class TUI extends Container {
                 entry.hidden = hidden;
                 // Update focus when hiding/showing
                 if (hidden) {
-                    this.clearOverlayRestoreFocus(entry);
+                    this.clearOverlayFocusRestoreFor(entry);
                     // If this overlay had focus, move focus to next visible or preFocus
                     if (this.focusedComponent === component) {
                         const topVisible = this.getTopmostVisibleOverlay();
@@ -294,12 +410,35 @@ export class TUI extends Container {
                 this.setFocus(component);
                 this.requestRender();
             },
-            unfocus: () => {
-                if (this.focusedComponent !== component)
+            unfocus: (unfocusOptions) => {
+                const isFocused = this.focusedComponent === component;
+                const restoreState = this.overlayFocusRestore;
+                const hasPendingRestore = restoreState.status !== "inactive" && restoreState.overlay === entry;
+                if (!isFocused && !hasPendingRestore)
                     return;
-                this.clearOverlayRestoreFocus(entry);
-                const topVisible = this.getTopmostVisibleOverlay();
-                this.setFocus(topVisible && topVisible !== entry ? topVisible.component : entry.preFocus);
+                if (restoreState.status === "blocked" &&
+                    restoreState.overlay === entry &&
+                    this.focusedComponent === restoreState.blockedBy) {
+                    if (unfocusOptions) {
+                        this.overlayFocusRestore = {
+                            status: "blocked",
+                            overlay: entry,
+                            blockedBy: restoreState.blockedBy,
+                            resume: { status: "focus-target", target: unfocusOptions.target },
+                        };
+                    }
+                    else {
+                        this.clearOverlayFocusRestore();
+                    }
+                    this.requestRender();
+                    return;
+                }
+                this.clearOverlayFocusRestoreFor(entry);
+                if (isFocused || unfocusOptions) {
+                    const topVisible = this.getTopmostVisibleOverlay();
+                    const fallbackTarget = topVisible && topVisible !== entry ? topVisible.component : entry.preFocus;
+                    this.setFocus(unfocusOptions ? unfocusOptions.target : fallbackTarget);
+                }
                 this.requestRender();
             },
             isFocused: () => this.focusedComponent === component,
@@ -307,19 +446,26 @@ export class TUI extends Container {
     }
     /** Hide the topmost overlay and restore previous focus. */
     hideOverlay() {
-        const overlay = this.overlayStack.pop();
+        const overlay = this.overlayStack[this.overlayStack.length - 1];
         if (!overlay)
             return;
-        this.clearOverlayRestoreFocus(overlay);
+        this.clearOverlayFocusRestoreFor(overlay);
+        this.retargetOverlayPreFocus(overlay);
+        this.overlayStack.pop();
         if (this.focusedComponent === overlay.component) {
             // Find topmost visible overlay, or fall back to preFocus
             const topVisible = this.getTopmostVisibleOverlay();
             this.setFocus(topVisible?.component ?? overlay.preFocus);
         }
         if (this.overlayStack.length === 0)
-            this.terminal.hideCursor();
+            this.hideTerminalCursor();
         this.requestRender();
     }
+    /** Hide the cursor while running. After stop(), the shell owns the cursor and it must stay visible. */
+    hideTerminalCursor() {
+        if (!this.stopped)
+            this.terminal.hideCursor();
+    }
     /** Check if there are any visible overlays */
     hasOverlay() {
         return this.overlayStack.some((o) => this.isOverlayVisible(o));
@@ -333,16 +479,17 @@ export class TUI extends Container {
         }
         return true;
     }
-    /** Find the topmost visible capturing overlay, if any */
+    /** Find the visual-frontmost visible capturing overlay, if any */
     getTopmostVisibleOverlay() {
-        for (let i = this.overlayStack.length - 1; i >= 0; i--) {
-            if (this.overlayStack[i].options?.nonCapturing)
+        let topmost;
+        for (const overlay of this.overlayStack) {
+            if (overlay.options?.nonCapturing || !this.isOverlayVisible(overlay))
                 continue;
-            if (this.isOverlayVisible(this.overlayStack[i])) {
-                return this.overlayStack[i];
+            if (!topmost || overlay.focusOrder > topmost.focusOrder) {
+                topmost = overlay;
             }
         }
-        return undefined;
+        return topmost;
     }
     invalidate() {
         super.invalidate();
@@ -376,12 +523,11 @@ export class TUI extends Container {
     }
     stop() {
         this.stopped = true;
-        if (this.renderTimer) {
-            clearTimeout(this.renderTimer);
-            this.renderTimer = undefined;
-        }
+        this.cancelRenderTimer();
         // 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) {
@@ -405,19 +551,7 @@ export class TUI extends Container {
             this.maxLinesRendered = 0;
             this.previousViewportTop = 0;
             this.skippedOffscreenChangeRange = undefined;
-            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.requestImmediateRender();
             return;
         }
         if (this.renderRequested)
@@ -425,6 +559,30 @@ 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;
@@ -480,17 +638,23 @@ export class TUI extends Container {
                 this.setFocus(topVisible.component);
             }
             else {
-                // No visible overlays, restore to preFocus
-                this.setFocus(focusedOverlay.preFocus);
+                this.setFocusInternal({ component: focusedOverlay.preFocus, overlayFocusRestore: "preserve" });
             }
         }
         const focusIsOverlay = this.overlayStack.some((o) => o.component === this.focusedComponent);
         if (!focusIsOverlay) {
-            const overlayToRestore = this.getRestoreFocusOverlay();
-            if (overlayToRestore &&
-                (overlayToRestore.restoreFocus.status === "eligible" ||
-                    overlayToRestore.restoreFocus.blockedBy !== this.focusedComponent)) {
-                this.setFocus(overlayToRestore.component);
+            const restoreState = this.getVisibleOverlayFocusRestore();
+            if (restoreState.status === "eligible") {
+                this.setFocus(restoreState.overlay.component);
+            }
+            else if (restoreState.status === "blocked" && restoreState.blockedBy !== this.focusedComponent) {
+                if (restoreState.resume.status === "restore-overlay") {
+                    this.setFocus(restoreState.overlay.component);
+                }
+                else {
+                    this.clearOverlayFocusRestore();
+                    this.setFocus(restoreState.resume.target);
+                }
             }
         }
         // Pass input to focused component (including Ctrl+C)
@@ -501,7 +665,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();
         }
     }
     consumeCellSizeResponse(data) {
@@ -882,18 +1048,32 @@ export class TUI extends Container {
         // Helper to clear scrollback and viewport and render all new lines
         const fullRender = (clear) => {
             this.fullRedrawCount += 1;
-            let buffer = "\x1b[?2026h"; // Begin synchronized output
+            const output = new BoundedTerminalWriter((data) => this.terminal.write(data));
+            output.append("\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
+                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)
-                    buffer += "\r\n";
-                buffer += newLines[i];
+                    output.append("\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++) {
+                        output.append("\r\n");
+                    }
+                    output.append(`\x1b[${imageReservedRows - 1}A`);
+                    output.append(line);
+                    output.append(`\x1b[${imageReservedRows - 1}B`);
+                    i += imageReservedRows - 1;
+                    continue;
+                }
+                output.append(line);
             }
-            buffer += "\x1b[?2026l"; // End synchronized output
-            this.terminal.write(buffer);
+            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
@@ -912,11 +1092,12 @@ export class TUI extends Container {
             this.previousHeight = height;
             this.skippedOffscreenChangeRange = undefined;
         };
-        const debugRedraw = process.env.PI_DEBUG_REDRAW === "1";
+        const redrawLogDirectory = process.env.PI_DEBUG_REDRAW === "1" ? this.logDirectory : undefined;
         const logRedraw = (reason) => {
-            if (!debugRedraw)
+            if (redrawLogDirectory === undefined)
                 return;
-            const logPath = path.join(os.homedir(), ".pi", "agent", "pi-debug.log");
+            const logPath = path.join(redrawLogDirectory, "tui-debug.log");
+            fs.mkdirSync(redrawLogDirectory, { recursive: true });
             const msg = `[${new Date().toISOString()}] fullRender: ${reason} (prev=${this.previousLines.length}, new=${newLines.length}, height=${height})\n`;
             fs.appendFileSync(logPath, msg);
         };
@@ -935,7 +1116,17 @@ export class TUI extends Container {
         // 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()) {
+        // If the new Termux viewport would reveal rows skipped by the offscreen optimization,
+        // redraw once so stale scrollback does not become visible.
+        if (heightChanged && isTermuxSession()) {
+            const viewportBottom = prevViewportTop + height - 1;
+            if (this.skippedOffscreenChangesIntersect(prevViewportTop, viewportBottom)) {
+                logRedraw(`terminal height changed revealing skipped offscreen changes (${this.previousHeight} -> ${height})`);
+                fullRender(true);
+                return;
+            }
+        }
+        else if (heightChanged) {
             logRedraw(`terminal height changed (${this.previousHeight} -> ${height})`);
             fullRender(true);
             return;
@@ -1010,8 +1201,9 @@ export class TUI extends Container {
         // 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);
+                const output = new BoundedTerminalWriter((data) => this.terminal.write(data));
+                output.append("\x1b[?2026h");
+                output.append(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) {
@@ -1021,10 +1213,10 @@ export class TUI extends Container {
                 }
                 const lineDiff = computeLineDiff(targetRow);
                 if (lineDiff > 0)
-                    buffer += `\x1b[${lineDiff}B`;
+                    output.append(`\x1b[${lineDiff}B`);
                 else if (lineDiff < 0)
-                    buffer += `\x1b[${-lineDiff}A`;
-                buffer += "\r";
+                    output.append(`\x1b[${-lineDiff}A`);
+                output.append("\r");
                 // Clear extra lines without scrolling
                 const extraLines = this.previousLines.length - newLines.length;
                 if (extraLines > height) {
@@ -1033,18 +1225,18 @@ export class TUI extends Container {
                     return;
                 }
                 if (extraLines > 0) {
-                    buffer += "\x1b[1B";
+                    output.append("\x1b[1B");
                 }
                 for (let i = 0; i < extraLines; i++) {
-                    buffer += "\r\x1b[2K";
+                    output.append("\r\x1b[2K");
                     if (i < extraLines - 1)
-                        buffer += "\x1b[1B";
+                        output.append("\x1b[1B");
                 }
                 if (extraLines > 0) {
-                    buffer += `\x1b[${extraLines}A`;
+                    output.append(`\x1b[${extraLines}A`);
                 }
-                buffer += "\x1b[?2026l";
-                this.terminal.write(buffer);
+                output.append("\x1b[?2026l");
+                output.flush();
                 this.cursorRow = targetRow;
                 this.hardwareCursorRow = targetRow;
             }
@@ -1064,19 +1256,20 @@ export class TUI extends Container {
             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);
+        // 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 output
+        output.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) {
-                buffer += `\x1b[${moveToBottom}B`;
+                output.append(`\x1b[${moveToBottom}B`);
             }
             const scroll = moveTargetRow - prevViewportBottom;
-            buffer += "\r\n".repeat(scroll);
+            output.append("\r\n".repeat(scroll));
             prevViewportTop += scroll;
             viewportTop += scroll;
             hardwareCursorRow = moveTargetRow;
@@ -1084,18 +1277,18 @@ export class TUI extends Container {
         // Move cursor to first changed line (use hardwareCursorRow for actual position)
         const lineDiff = computeLineDiff(moveTargetRow);
         if (lineDiff > 0) {
-            buffer += `\x1b[${lineDiff}B`; // Move down
+            output.append(`\x1b[${lineDiff}B`); // Move down
         }
         else if (lineDiff < 0) {
-            buffer += `\x1b[${-lineDiff}A`; // Move up
+            output.append(`\x1b[${-lineDiff}A`); // Move up
         }
-        buffer += appendStart ? "\r\n" : "\r"; // Move to column 0
+        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)
-                buffer += "\r\n";
+                output.append("\r\n");
             const line = newLines[i];
             const isImage = isImageLine(line);
             const imageReservedRows = isImage ? this.getKittyImageReservedRows(newLines, i, renderEnd) : 1;
@@ -1106,31 +1299,34 @@ export class TUI extends Container {
                     fullRender(true);
                     return;
                 }
-                buffer += "\x1b[2K";
+                output.append("\x1b[2K");
                 for (let row = 1; row < imageReservedRows; row++) {
-                    buffer += "\r\n\x1b[2K";
+                    output.append("\r\n\x1b[2K");
                 }
-                buffer += `\x1b[${imageReservedRows - 1}A`;
-                buffer += line;
-                buffer += `\x1b[${imageReservedRows - 1}B`;
+                output.append(`\x1b[${imageReservedRows - 1}A`);
+                output.append(line);
+                output.append(`\x1b[${imageReservedRows - 1}B`);
                 i += imageReservedRows - 1;
                 continue;
             }
-            buffer += "\x1b[2K"; // Clear current line
+            output.append("\x1b[2K"); // Clear current line
             if (!isImage && visibleWidth(line) > width) {
-                // Log all lines to crash file for debugging
-                const crashLogPath = path.join(os.homedir(), ".pi", "agent", "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);
+                // Log all lines to a crash file for debugging. Only into the caller's private log directory: the
+                // dump holds the full rendered transcript, so a predictable path in a shared temp dir could leak it.
+                const crashLogPath = this.logDirectory ? path.join(this.logDirectory, "tui-crash.log") : undefined;
+                if (crashLogPath) {
+                    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, mode: 0o700 });
+                    fs.writeFileSync(crashLogPath, crashData, { mode: 0o600 });
+                }
                 // Clean up terminal state before throwing
                 this.stop();
                 const errorMsg = [
@@ -1139,11 +1335,13 @@ export class TUI extends Container {
                     "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}`,
+                    crashLogPath
+                        ? `Debug log written to: ${crashLogPath}`
+                        : "No debug log written (no log directory configured).",
                 ].join("\n");
                 throw new Error(errorMsg);
             }
-            buffer += line;
+            output.append(line);
         }
         // Track where cursor ended up after rendering
         let finalCursorRow = renderEnd;
@@ -1152,17 +1350,17 @@ export class TUI extends Container {
             // 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`;
+                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++) {
-                buffer += "\r\n\x1b[2K";
+                output.append("\r\n\x1b[2K");
             }
             // Move cursor back to end of new content
-            buffer += `\x1b[${extraLines}A`;
+            output.append(`\x1b[${extraLines}A`);
         }
-        buffer += "\x1b[?2026l"; // End synchronized output
+        output.append("\x1b[?2026l"); // End synchronized output
         if (process.env.PI_TUI_DEBUG === "1") {
             const debugDir = "/tmp/tui";
             fs.mkdirSync(debugDir, { recursive: true });
@@ -1187,12 +1385,11 @@ export class TUI extends Container {
                 JSON.stringify(this.previousLines, null, 2),
                 "",
                 "=== buffer ===",
-                JSON.stringify(buffer),
+                `[${output.length} chars written in bounded chunks]`,
             ].join("\n");
             fs.writeFileSync(debugPath, debugData);
         }
-        // Write entire buffer at once
-        this.terminal.write(buffer);
+        output.flush();
         // Track cursor position for next render
         // cursorRow tracks end of content (for viewport calculation)
         // hardwareCursorRow tracks actual terminal cursor position (for movement)