@fractaal/pi-tui 0.85.4 → 0.86.2

package/dist/tui.js

@@ -1,48 +1,61 @@
 /**
  * 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 { parseOscColorResponse, parseTerminalColorSchemeReport, } from "./terminal-colors.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)
+/**
+ * Dispatch an event to a component and retain the exact target and coordinate
+ * transform. Containers use this when forwarding events to nested children.
+ */
+export function dispatchMouseEvent(component, event) {
+    const result = component.handleMouse?.(event);
+    if (!result)
         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;
-        }
+    if ("target" in result) {
+        // The component forwarded the event to a child it hosts. Like a delegating container, it routes
+        // keys to that child itself, so it keeps keyboard focus. Focusing the child directly would leave
+        // focus on a detached component once the host removes it, e.g. a closed settings submenu.
+        const forwarded = result;
+        return forwarded.focus && component.handleInput ? { ...forwarded, focusTarget: component } : forwarded;
     }
-    return { ids, rows };
-}
-function extractKittyImageIds(line) {
-    return parseKittyImageHeader(line)?.ids ?? [];
+    if (!result.handled && !result.capture && !result.focus)
+        return undefined;
+    return {
+        ...result,
+        handled: true,
+        ...(result.focus ? { focusTarget: component } : {}),
+        target: {
+            component,
+            originX: event.screenX - event.x,
+            originY: event.screenY - event.y,
+            width: event.width,
+            height: event.height,
+        },
+    };
 }
-function extractKittyImageRows(line) {
-    return parseKittyImageHeader(line)?.rows ?? 1;
+/** Recreate local coordinates for a previously dispatched mouse target. */
+export function retargetMouseEvent(event, target) {
+    return {
+        ...event,
+        x: event.screenX - target.originX,
+        y: event.screenY - target.originY,
+        width: target.width,
+        height: target.height,
+    };
 }
+const TERMINAL_PALETTE_SIZE = 16;
+/** OSC 10 and 11 plus OSC 4 for every palette color. */
+const TERMINAL_COLOR_REPLY_COUNT = 2 + TERMINAL_PALETTE_SIZE;
+/**
+ * Default colors, palette colors 0-15, and a trailing primary device attributes (DA1) request.
+ * Every terminal answers DA1 and terminals answer in order, so the DA1 reply marks the end of
+ * the color replies, including for terminals that ignore the color queries.
+ */
+const TERMINAL_COLOR_QUERY = `\x1b]10;?\x07\x1b]11;?\x07${Array.from({ length: TERMINAL_PALETTE_SIZE }, (_, index) => `\x1b]4;${index};?\x07`).join("")}\x1b[c`;
+const DEVICE_ATTRIBUTES_RESPONSE_PATTERN = /^\x1b\[\?[\d;]*c$/;
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -68,14 +81,12 @@ function parseSizeValue(value, referenceSize) {
     }
     return undefined;
 }
-function isTermuxSession() {
-    return Boolean(process.env.TERMUX_VERSION);
-}
 /**
  * Container - a component that contains other components
  */
 export class Container {
     children = [];
+    mouseLayout;
     addChild(component) {
         this.children.push(component);
     }
@@ -93,59 +104,118 @@ export class Container {
             child.invalidate?.();
         }
     }
+    handleMouse(event) {
+        if (event.y < 0 || event.y >= event.height)
+            return undefined;
+        const mouseChildren = this.mouseLayout?.width === event.width
+            ? this.mouseLayout.children
+            : this.children.map((component) => ({ component, height: component.render(event.width).length }));
+        let childY = 0;
+        for (const { component: child, height: childHeight } of mouseChildren) {
+            if (event.y >= childY && event.y < childY + childHeight) {
+                const result = dispatchMouseEvent(child, {
+                    ...event,
+                    y: event.y - childY,
+                    height: childHeight,
+                });
+                if (result?.focus && this.handleInput)
+                    return { ...result, focusTarget: this };
+                return result;
+            }
+            childY += childHeight;
+        }
+        return undefined;
+    }
     render(width) {
         const lines = [];
+        const mouseChildren = [];
         for (const child of this.children) {
             const childLines = child.render(width);
+            mouseChildren.push({ component: child, height: childLines.length });
             for (const line of childLines) {
                 lines.push(line);
             }
         }
+        this.mouseLayout = { width, children: mouseChildren };
         return lines;
     }
 }
 /**
  * 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
+    showHardwareCursor = false;
+    clearOnShrink = false;
     fullRedrawCount = 0;
     stopped = false;
-    pendingOsc11BackgroundReplies = 0;
-    pendingOsc11BackgroundQueries = [];
+    /**
+     * Color queries waiting for their DA1 reply, oldest first. Terminals answer in order, so color
+     * replies belong to the oldest one. Queries stay here after a timeout to collect late replies.
+     */
+    pendingTerminalColorQueries = [];
     terminalColorSchemeListeners = new Set();
     terminalColorSchemeNotificationsEnabled = false;
+    /** Directory for debug/crash logs. When undefined, debug logging is disabled and crash dumps fall back to the OS temp directory. */
     logDirectory;
     // Overlay stack for modal components rendered on top of base content
     focusOrderCounter = 0;
     overlayStack = [];
+    renderedOverlayLayouts = [];
+    get hasOverlayEntries() {
+        return this.overlayStack.length > 0;
+    }
     overlayFocusRestore = { status: "inactive" };
     constructor(terminal, showHardwareCursor, logDirectory) {
         super();
         this.terminal = terminal;
-        this.logDirectory = logDirectory ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+        this.logDirectory = logDirectory;
         if (showHardwareCursor !== undefined) {
             this.showHardwareCursor = showHardwareCursor;
         }
     }
+    resetRenderState() { }
+    beforeTerminalStart() { }
+    afterTerminalStart() { }
+    beforeTerminalStop(_options) { }
+    afterTerminalStop(_options) { }
     get fullRedraws() {
         return this.fullRedrawCount;
     }
@@ -157,7 +227,7 @@ export class TUI extends Container {
             return;
         this.showHardwareCursor = enabled;
         if (!enabled) {
-            this.terminal.hideCursor();
+            this.hideTerminalCursor();
         }
         this.requestRender();
     }
@@ -166,12 +236,15 @@ export class TUI extends Container {
     }
     /**
      * Set whether to trigger full re-render when content shrinks.
-     * When true (default), empty rows are cleared when content shrinks.
-     * When false, empty rows remain (reduces redraws on slower terminals).
+     * When true, empty rows are cleared when content shrinks.
+     * When false (default), empty rows remain (reduces redraws on slower terminals).
      */
     setClearOnShrink(enabled) {
         this.clearOnShrink = enabled;
     }
+    getFocusedComponent() {
+        return this.focusedComponent;
+    }
     setFocus(component) {
         this.setFocusInternal({ component, overlayFocusRestore: "clear" });
     }
@@ -272,8 +345,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)
@@ -299,7 +375,7 @@ export class TUI extends Container {
         if (!options?.nonCapturing && this.isOverlayVisible(entry)) {
             this.setFocus(component);
         }
-        this.terminal.hideCursor();
+        this.hideTerminalCursor();
         this.requestRender();
         // Return handle for controlling this overlay
         return {
@@ -315,7 +391,7 @@ export class TUI extends Container {
                         this.setFocus(topVisible?.component ?? entry.preFocus);
                     }
                     if (this.overlayStack.length === 0)
-                        this.terminal.hideCursor();
+                        this.hideTerminalCursor();
                     this.requestRender();
                 }
             },
@@ -381,6 +457,11 @@ export class TUI extends Container {
                 this.requestRender();
             },
             isFocused: () => this.focusedComponent === component,
+            getBounds: () => {
+                if (!this.overlayStack.includes(entry) || !this.isOverlayVisible(entry) || !entry.bounds)
+                    return undefined;
+                return { ...entry.bounds };
+            },
         };
     }
     /** Hide the topmost overlay and restore previous focus. */
@@ -397,13 +478,58 @@ export class TUI extends Container {
             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));
     }
+    /** Check if the focused component is a visible overlay */
+    isOverlayFocused() {
+        return this.overlayStack.some((entry) => entry.component === this.focusedComponent && this.isOverlayVisible(entry));
+    }
+    /** Keep overlay containers as keyboard focus owners when a nested control is clicked. */
+    resolveMouseFocusTarget(component) {
+        for (let index = this.overlayStack.length - 1; index >= 0; index--) {
+            const overlay = this.overlayStack[index];
+            if (this.isOverlayVisible(overlay) && this.containsComponent(overlay.component, component)) {
+                return overlay.component;
+            }
+        }
+        return component;
+    }
+    /** Dispatch to the visually topmost overlay under the pointer. */
+    dispatchMouseToOverlay(event) {
+        for (let index = this.renderedOverlayLayouts.length - 1; index >= 0; index--) {
+            const layout = this.renderedOverlayLayouts[index];
+            if (event.screenX < layout.col ||
+                event.screenX >= layout.col + layout.width ||
+                event.screenY < layout.row ||
+                event.screenY >= layout.row + layout.height) {
+                continue;
+            }
+            const result = dispatchMouseEvent(layout.entry.component, {
+                ...event,
+                x: event.screenX - layout.col,
+                y: event.screenY - layout.row,
+                width: layout.width,
+                height: layout.height,
+            });
+            return result
+                ? {
+                    hit: true,
+                    result: result.focus ? { ...result, focusTarget: layout.entry.component } : result,
+                }
+                : { hit: true };
+        }
+        return { hit: false };
+    }
     /** Check if an overlay entry is currently visible */
     isOverlayVisible(entry) {
         if (entry.hidden)
@@ -426,13 +552,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 +602,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 +632,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,8 +675,8 @@ export class TUI extends Container {
             }
         }, delay);
     }
-    handleInput(data) {
-        if (this.consumeOsc11BackgroundResponse(data)) {
+    handleTerminalInput(data) {
+        if (this.consumeTerminalColorResponse(data)) {
             return;
         }
         if (this.consumeTerminalColorSchemeReport(data)) {
@@ -616,30 +744,55 @@ 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) {
-        if (this.pendingOsc11BackgroundReplies <= 0) {
+    consumeTerminalColorResponse(data) {
+        const query = this.pendingTerminalColorQueries[0];
+        if (!query) {
             return false;
         }
-        if (!isOsc11BackgroundColorResponse(data)) {
+        if (DEVICE_ATTRIBUTES_RESPONSE_PATTERN.test(data)) {
+            this.pendingTerminalColorQueries.shift();
+            this.completeTerminalColorQuery(query);
+            return true;
+        }
+        const response = parseOscColorResponse(data);
+        if (!response) {
             return false;
         }
-        const rgb = parseOsc11BackgroundColor(data);
-        this.pendingOsc11BackgroundReplies -= 1;
-        const query = this.pendingOsc11BackgroundQueries.shift();
-        if (query && !query.settled) {
-            query.settled = true;
-            if (query.timer) {
-                clearTimeout(query.timer);
-                query.timer = undefined;
-            }
-            query.resolve?.(rgb);
-            query.resolve = undefined;
+        const { target, rgb } = response;
+        const key = String(target);
+        if (!query.deliver || query.replied.has(key)) {
+            return true;
+        }
+        query.replied.add(key);
+        if (target === "foreground") {
+            query.foreground = rgb;
+        }
+        else if (target === "background") {
+            query.background = rgb;
+        }
+        else if (target < TERMINAL_PALETTE_SIZE) {
+            query.palette[target] = rgb;
+        }
+        if (query.replied.size === TERMINAL_COLOR_REPLY_COUNT) {
+            this.completeTerminalColorQuery(query);
         }
         return true;
     }
+    terminalColorQueryResult(query) {
+        const palette = query.palette.every((color) => color !== undefined) ? query.palette : undefined;
+        return { foreground: query.foreground, background: query.background, palette };
+    }
+    completeTerminalColorQuery(query) {
+        const deliver = query.deliver;
+        query.deliver = undefined;
+        clearTimeout(query.timer);
+        deliver?.(this.terminalColorQueryResult(query));
+    }
     consumeTerminalColorSchemeReport(data) {
         const scheme = parseTerminalColorSchemeReport(data);
         if (!scheme) {
@@ -795,9 +948,13 @@ export class TUI extends Container {
     }
     /** Composite all overlays into content lines (sorted by focusOrder, higher = on top). */
     compositeOverlays(lines, termWidth, termHeight) {
-        if (this.overlayStack.length === 0)
+        if (this.overlayStack.length === 0) {
+            this.renderedOverlayLayouts = [];
             return lines;
+        }
         const result = [...lines];
+        for (const entry of this.overlayStack)
+            entry.bounds = undefined;
         // Pre-render all visible overlays and calculate positions
         const rendered = [];
         let minLinesNeeded = result.length;
@@ -816,9 +973,17 @@ export class TUI extends Container {
             }
             // Get final row/col with actual overlay height
             const { row, col } = this.resolveOverlayLayout(options, overlayLines.length, termWidth, termHeight);
-            rendered.push({ overlayLines, row, col, w: width });
+            entry.bounds = { row, col, width, height: overlayLines.length };
+            rendered.push({ entry, overlayLines, row, col, w: width });
             minLinesNeeded = Math.max(minLinesNeeded, row + overlayLines.length);
         }
+        this.renderedOverlayLayouts = rendered.map(({ entry, row, col, w, overlayLines }) => ({
+            entry,
+            row,
+            col,
+            width: w,
+            height: overlayLines.length,
+        }));
         // Pad to at least terminal height so overlays have screen-relative positions.
         // Excludes maxLinesRendered: the historical high-water mark caused self-reinforcing
         // inflation that pushed content into scrollback on terminal widen.
@@ -842,9 +1007,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 +1017,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,435 +1045,29 @@ 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
+     * Query the terminal's theme colors: the default foreground (OSC 10), the default background
+     * (OSC 11), and ANSI colors 0-15 (OSC 4), followed by a DA1 request that marks the end of the
+     * replies. Resolves when the DA1 reply or all color replies arrive, or when the timeout expires.
+     * Colors the terminal did not report are undefined; the palette is only set when all 16 arrived.
+     * @param timeoutMs Query timeout in milliseconds, for terminals that do not answer DA1 either.
+     * @param onLateReply Receives the replies if the query completes after the timeout, e.g. over slow links.
      */
-    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.
-     * @returns Promise containing the parsed RGB color, or undefined if it times out or fails to parse.
-     */
-    queryTerminalBackgroundColor({ timeoutMs }) {
+    queryTerminalColors({ timeoutMs, onLateReply, }) {
         return new Promise((resolve) => {
             const query = {
-                settled: false,
-                resolve,
+                palette: Array.from({ length: TERMINAL_PALETTE_SIZE }, () => undefined),
+                replied: new Set(),
+                deliver: resolve,
                 timer: undefined,
             };
+            // Resolve with the replies so far, and keep collecting late replies for `onLateReply`.
             query.timer = setTimeout(() => {
-                if (query.settled) {
-                    return;
-                }
-                query.settled = true;
-                query.timer = undefined;
-                query.resolve?.(undefined);
-                query.resolve = undefined;
+                query.deliver = onLateReply;
+                resolve(this.terminalColorQueryResult(query));
             }, timeoutMs);
-            this.pendingOsc11BackgroundQueries.push(query);
-            this.pendingOsc11BackgroundReplies += 1;
-            this.terminal.write("\x1b]11;?\x07");
-        });
-    }
-    /**
-     * Query the terminal's color-scheme preference with DSR (`CSI ? 996 n`).
-     * Terminals that support the color palette notification protocol reply with
-     * `CSI ? 997 ; 1 n` for dark or `CSI ? 997 ; 2 n` for light.
-     */
-    queryTerminalColorScheme({ timeoutMs }) {
-        return new Promise((resolve) => {
-            let settled = false;
-            let timer;
-            let unsubscribe = () => { };
-            const settle = (scheme) => {
-                if (settled)
-                    return;
-                settled = true;
-                if (timer) {
-                    clearTimeout(timer);
-                    timer = undefined;
-                }
-                unsubscribe();
-                resolve(scheme);
-            };
-            unsubscribe = this.onTerminalColorSchemeChange(settle);
-            timer = setTimeout(() => settle(undefined), timeoutMs);
-            this.terminal.write("\x1b[?996n");
+            this.pendingTerminalColorQueries.push(query);
+            this.terminal.write(TERMINAL_COLOR_QUERY);
         });
     }
 }