@code-yeongyu/senpi-tui 2026.8.1 → 2026.8.3-3

package/dist/tui.js

@@ -22,20 +22,17 @@ function parseKittyImageHeader(line) {
         return undefined;
     const ids = [];
     let rows = 1;
-    const params = line.slice(paramsStart, paramsEnd);
-    for (const param of params.split(",")) {
+    for (const param of line.slice(paramsStart, paramsEnd).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") {
+        if (key === "i")
             ids.push(numberValue);
-        }
-        else if (key === "r") {
+        else if (key === "r")
             rows = numberValue;
-        }
     }
     return { ids, rows };
 }
@@ -45,6 +42,9 @@ function extractKittyImageIds(line) {
 function extractKittyImageRows(line) {
     return parseKittyImageHeader(line)?.rows ?? 1;
 }
+function isTermuxSession() {
+    return Boolean(process.env.TERMUX_VERSION);
+}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -56,6 +56,9 @@ export function isFocusable(component) {
  * TUI finds and strips this marker, then positions the hardware cursor there.
  */
 export const CURSOR_MARKER = "\x1b_pi:c\x07";
+const FAKE_CURSOR_START = "\x1b[7m";
+const FAKE_CURSOR_END = "\x1b[27m";
+const FAKE_CURSOR_RESET = "\x1b[0m";
 export { visibleWidth };
 const renderErrorLoggedClasses = new Set();
 let renderErrorLogWrites = 0;
@@ -186,9 +189,6 @@ function parseSizeValue(value, referenceSize) {
     }
     return undefined;
 }
-function isTermuxSession() {
-    return Boolean(process.env.TERMUX_VERSION);
-}
 /**
  * Container - a component that contains other components
  */
@@ -258,12 +258,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) && visibleWidth(baseLine) === 0)
+        return baseLine;
+    const placeholderIndex = baseLine.indexOf("\u{10eeee}");
+    const protocolEnd = placeholderIndex === -1 ? -1 : baseLine.lastIndexOf("\x1b\\", placeholderIndex);
+    const protocolPrefix = protocolEnd === -1 ? "" : baseLine.slice(0, protocolEnd + 2);
+    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);
+    const composited = visibleWidth(result) <= totalWidth ? result : sliceByColumn(result, 0, totalWidth, true);
+    return protocolPrefix + composited;
+}
+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 {
     /** Minimum interval between scheduled renders. Default preserves the historic ~60fps cap. */
     #minRenderIntervalMs;
     #lastCursorVisibility;
+    get hasOverlayEntries() {
+        return this.overlayStack.length > 0;
+    }
     #muxDetector;
-    constructor(terminal, options) {
+    constructor(terminal, options, logDirectory) {
         super();
         this.previousLines = [];
         this.previousRawLines = [];
@@ -300,10 +335,16 @@ export class TUI extends Container {
         // Preserve existing positional boolean callers while allowing explicit render-policy overrides.
         const normalizedOptions = typeof options === "boolean" ? { showHardwareCursor: options } : (options ?? {});
         this.#muxDetector = normalizedOptions.muxDetector ?? isMultiplexerSession;
+        this.logDirectory = logDirectory ?? path.join(os.homedir(), ".senpi", "agent");
         if (normalizedOptions.showHardwareCursor !== undefined) {
             this.showHardwareCursor = normalizedOptions.showHardwareCursor;
         }
     }
+    resetRenderState() { }
+    beforeTerminalStart() { }
+    afterTerminalStart() { }
+    beforeTerminalStop() { }
+    afterTerminalStop() { }
     get fullRedraws() {
         return this.fullRedrawCount;
     }
@@ -317,9 +358,6 @@ export class TUI extends Container {
         if (this.showHardwareCursor === enabled)
             return;
         this.showHardwareCursor = enabled;
-        if (!enabled) {
-            this.#setCursorVisibility(false);
-        }
         this.requestRender();
     }
     getClearOnShrink() {
@@ -433,8 +471,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)
@@ -596,7 +637,9 @@ export class TUI extends Container {
         this.renderRequested = false;
         this.inputRenderPending = false;
         this.#lastCursorVisibility = undefined;
-        this.terminal.start((data) => this.handleInput(data), () => this.requestRender());
+        this.beforeTerminalStart();
+        this.terminal.start((data) => this.handleTerminalInput(data), () => this.requestRender());
+        this.afterTerminalStart();
         if (process.env.TMUX)
             this.terminal.write(ENABLE_FOCUS_REPORTING);
         this.#setCursorVisibility(false);
@@ -650,10 +693,14 @@ export class TUI extends Container {
         if (this.terminalColorSchemeNotificationsEnabled) {
             this.terminal.write("\x1b[?2031l");
         }
+        this.beforeTerminalStop();
         // 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(" ");
+            // Only overwrite the cursor cell when the last published frame kept the hardware cursor hidden;
+            // a pending visibility change has not rendered yet and must not erase content.
+            if (this.#lastCursorVisibility === false) {
+                this.terminal.write(" ");
+            }
             const targetRow = this.previousLines.length; // Line after the last content
             const lineDiff = targetRow - this.hardwareCursorRow;
             if (lineDiff > 0) {
@@ -669,6 +716,8 @@ export class TUI extends Container {
         if (process.env.TMUX)
             this.terminal.write(DISABLE_FOCUS_REPORTING);
         this.terminal.stop();
+        this.afterTerminalStop();
+        this.resetRenderState();
         this.#lastCursorVisibility = undefined;
         this.previousLines = [];
         this.previousRawLines = [];
@@ -694,6 +743,7 @@ export class TUI extends Container {
     requestRender(force = false, source = "unknown") {
         if (force) {
             this.inputRenderPending = false;
+            this.resetRenderState();
             this.previousLines = [];
             this.previousRawLines = [];
             this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear
@@ -773,7 +823,7 @@ export class TUI extends Container {
         this.lastRenderAt = performance.now();
         this.doRender();
     }
-    handleInput(data) {
+    handleTerminalInput(data) {
         const focus = consumeTmuxFocusEvent(data);
         if (focus.event !== null) {
             resetCapabilitiesCache();
@@ -1107,7 +1157,10 @@ export class TUI extends Container {
         this.normalizeMemo.set(line, normalized);
         return { line: normalized, normalized: true };
     }
-    applyLineResets(lines, mode = "full") {
+    applyLineResets(lines) {
+        return this.applyLineResetResult(lines).lines;
+    }
+    applyLineResetResult(lines, mode = "full") {
         const previousMemo = this.normalizeMemo;
         const nextMemo = new Map();
         const normalizedLines = [];
@@ -1141,7 +1194,7 @@ export class TUI extends Container {
             this.previousLines.length === 0 ||
             this.previousLines.length !== rawLines.length ||
             this.previousRawLines.length !== rawLines.length) {
-            return this.applyLineResets(rawLines);
+            return this.applyLineResetResult(rawLines);
         }
         const windowStart = Math.max(0, viewportTop - VIEWPORT_RENDER_OVERSCAN);
         const windowEnd = Math.min(rawLines.length, viewportTop + height + VIEWPORT_RENDER_OVERSCAN);
@@ -1154,7 +1207,7 @@ export class TUI extends Container {
                 firstRawChanged = i;
             }
             if (i < windowStart || i >= windowEnd) {
-                return this.applyLineResets(rawLines, "escaped");
+                return this.applyLineResetResult(rawLines, "escaped");
             }
         }
         const lines = this.previousLines.slice();
@@ -1323,13 +1376,12 @@ export class TUI extends Container {
             buffer += row.content;
             finalPaintedScreenRow = row.screenRow;
         }
-        buffer += TUI.FRAME_END;
+        const finalCursorRow = plan.viewportTop + finalPaintedScreenRow;
+        buffer = this.finishFrame(buffer, cursorPos, newLines.length, finalCursorRow);
         this.terminal.write(buffer);
         this.cursorRow = Math.max(0, newLines.length - 1);
-        this.hardwareCursorRow = plan.viewportTop + finalPaintedScreenRow;
         this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
         this.previousViewportTop = plan.viewportTop;
-        this.positionHardwareCursor(cursorPos, newLines.length);
         this.setPreviousLines(newLines, rawLines);
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
@@ -1352,13 +1404,11 @@ export class TUI extends Container {
             buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
             buffer += newLines[row] ?? "";
         }
-        buffer += TUI.FRAME_END;
+        buffer = this.finishFrame(buffer, cursorPos, newLines.length, bufferLength - 1);
         this.terminal.write(buffer);
         this.cursorRow = Math.max(0, newLines.length - 1);
-        this.hardwareCursorRow = bufferLength - 1;
         this.maxLinesRendered = newLines.length;
         this.previousViewportTop = Math.max(0, bufferLength - height);
-        this.positionHardwareCursor(cursorPos, newLines.length);
         this.setPreviousLines(newLines, rawLines);
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
@@ -1381,14 +1431,13 @@ export class TUI extends Container {
             buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
             buffer += newLines[viewportTop + row] ?? "";
         }
-        buffer += TUI.FRAME_END;
+        const finalCursorRow = viewportTop + Math.max(0, height - 1);
+        buffer = this.finishFrame(buffer, cursorPos, newLines.length, finalCursorRow);
         this.terminal.write(buffer);
         this.muxViewportRepaintCount += 1;
         this.cursorRow = Math.max(0, newLines.length - 1);
-        this.hardwareCursorRow = viewportTop + Math.max(0, height - 1);
         this.maxLinesRendered = newLines.length;
         this.previousViewportTop = viewportTop;
-        this.positionHardwareCursor(cursorPos, newLines.length);
         this.setPreviousLines(newLines, rawLines);
         this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
@@ -1455,8 +1504,22 @@ export class TUI extends Container {
                 // Calculate visual column (width of text before marker)
                 const beforeMarker = line.slice(0, markerIndex);
                 const col = visibleWidth(beforeMarker);
-                // Strip marker from the line
-                lines[row] = line.slice(0, markerIndex) + line.slice(markerIndex + CURSOR_MARKER.length);
+                let afterMarker = line.slice(markerIndex + CURSOR_MARKER.length);
+                if (this.showHardwareCursor && afterMarker.startsWith(FAKE_CURSOR_START)) {
+                    const fakeCursorEnd = afterMarker.indexOf(FAKE_CURSOR_END, FAKE_CURSOR_START.length);
+                    const fakeCursorReset = afterMarker.indexOf(FAKE_CURSOR_RESET, FAKE_CURSOR_START.length);
+                    if (fakeCursorReset !== -1 && (fakeCursorEnd === -1 || fakeCursorReset < fakeCursorEnd)) {
+                        // Keep a full reset because it may also terminate styles surrounding the fake cursor.
+                        afterMarker = afterMarker.slice(FAKE_CURSOR_START.length);
+                    }
+                    else if (fakeCursorEnd !== -1) {
+                        afterMarker =
+                            afterMarker.slice(FAKE_CURSOR_START.length, fakeCursorEnd) +
+                                afterMarker.slice(fakeCursorEnd + FAKE_CURSOR_END.length);
+                    }
+                }
+                // Strip marker and any colocated fake cursor styling when the hardware cursor owns the position.
+                lines[row] = beforeMarker + afterMarker;
                 return { row, col };
             }
         }
@@ -1522,10 +1585,10 @@ export class TUI extends Container {
                 }
                 buffer += line;
             }
-            buffer += TUI.FRAME_END;
+            const finalCursorRow = Math.max(0, newLines.length - 1);
+            buffer = this.finishFrame(buffer, cursorPos, newLines.length, finalCursorRow);
             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;
@@ -1535,7 +1598,6 @@ export class TUI extends Container {
             }
             const bufferLength = Math.max(height, newLines.length);
             this.previousViewportTop = Math.max(0, bufferLength - height);
-            this.positionHardwareCursor(cursorPos, newLines.length);
             this.setPreviousLines(newLines, rawLines);
             this.previousKittyImageIds = this.collectKittyImageIds(newLines);
             this.previousWidth = width;
@@ -1545,8 +1607,9 @@ export class TUI extends Container {
         const logRedraw = (reason) => {
             if (!debugRedraw)
                 return;
-            const logPath = path.join(os.homedir(), ".senpi", "agent", "senpi-debug.log");
+            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, { encoding: "utf8", mode: DIAGNOSTIC_LOG_MODE });
             chmodDiagnosticLogBestEffort(logPath);
         };
@@ -1667,12 +1730,13 @@ export class TUI extends Container {
                 if (moveBack > 0) {
                     buffer += `\x1b[${moveBack}A`;
                 }
-                buffer += TUI.FRAME_END;
+                buffer = this.finishFrame(buffer, cursorPos, newLines.length, targetRow);
                 this.terminal.write(buffer);
                 this.cursorRow = targetRow;
-                this.hardwareCursorRow = targetRow;
             }
-            this.positionHardwareCursor(cursorPos, newLines.length);
+            else {
+                this.positionHardwareCursor(cursorPos, newLines.length);
+            }
             this.setPreviousLines(newLines, rawLines);
             this.previousKittyImageIds = this.collectKittyImageIds(newLines);
             this.previousWidth = width;
@@ -1736,13 +1800,12 @@ export class TUI extends Container {
                     buffer += `\r\x1b[2K${TUI.SEGMENT_RESET}`;
                     buffer += newLines[viewportTop + row] ?? "";
                 }
-                buffer += TUI.FRAME_END;
+                const finalCursorRow = viewportTop + Math.max(0, height - 1);
+                buffer = this.finishFrame(buffer, cursorPos, newLines.length, finalCursorRow);
                 this.terminal.write(buffer);
                 this.cursorRow = Math.max(0, newLines.length - 1);
-                this.hardwareCursorRow = viewportTop + Math.max(0, height - 1);
                 this.maxLinesRendered = Math.max(this.maxLinesRendered, newLines.length);
                 this.previousViewportTop = viewportTop;
-                this.positionHardwareCursor(cursorPos, newLines.length);
                 this.setPreviousLines(newLines, rawLines);
                 this.previousKittyImageIds = this.collectKittyImageIds(newLines);
                 this.previousWidth = width;
@@ -1857,7 +1920,7 @@ export class TUI extends Container {
             // Move cursor back to end of new content
             buffer += `\x1b[${extraLines}A`;
         }
-        buffer += TUI.FRAME_END;
+        buffer = this.finishFrame(buffer, cursorPos, newLines.length, finalCursorRow);
         if (process.env.PI_TUI_DEBUG === "1") {
             const debugDir = "/tmp/tui";
             fs.mkdirSync(debugDir, { recursive: true });
@@ -1893,12 +1956,9 @@ export class TUI extends Container {
         // 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.setPreviousLines(newLines, rawLines);
         if (needsKittyImageExpansion) {
             this.previousKittyImageIds = this.collectKittyImageIds(newLines);
@@ -1911,7 +1971,7 @@ export class TUI extends Container {
      * @param cursorPos The cursor position extracted from rendered output, or null
      * @param totalLines Total number of rendered lines
      */
-    positionHardwareCursor(cursorPos, totalLines) {
+    buildHardwareCursorSequence(cursorPos, totalLines) {
         let buffer = "";
         if (!cursorPos || totalLines <= 0) {
             if (this.#lastCursorVisibility !== false) {
@@ -1939,9 +1999,16 @@ export class TUI extends Container {
                 this.#lastCursorVisibility = this.showHardwareCursor;
             }
         }
-        if (buffer) {
-            this.terminal.write(buffer);
-        }
+        return buffer;
+    }
+    finishFrame(buffer, cursorPos, totalLines, hardwareCursorRow) {
+        this.hardwareCursorRow = hardwareCursorRow;
+        return buffer + this.buildHardwareCursorSequence(cursorPos, totalLines) + TUI.FRAME_END;
+    }
+    positionHardwareCursor(cursorPos, totalLines) {
+        const buffer = this.buildHardwareCursorSequence(cursorPos, totalLines);
+        if (buffer)
+            this.terminal.write(TUI.FRAME_BEGIN + buffer + TUI.FRAME_END);
     }
     /**
      * Query the terminal's default background color with OSC 11 (`ESC ] 11 ; ? BEL`).
@@ -1996,4 +2063,7 @@ export class TUI extends Container {
         });
     }
 }
+/** Legacy main-screen renderer export. */
+export class TUI extends TuiBase {
+}
 //# sourceMappingURL=tui.js.map