@draht/tui 2026.5.12 → 2026.7.7

package/dist/tui.js

@@ -6,8 +6,43 @@ 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 { getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
-import { extractSegments, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
+import { isOsc11BackgroundColorResponse, parseOsc11BackgroundColor, parseTerminalColorSchemeReport, } from "./terminal-colors.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";
+function parseKittyImageHeader(line) {
+    const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
+    if (sequenceStart === -1)
+        return undefined;
+    const paramsStart = sequenceStart + KITTY_SEQUENCE_PREFIX.length;
+    const paramsEnd = line.indexOf(";", paramsStart);
+    if (paramsEnd === -1)
+        return undefined;
+    const ids = [];
+    let rows = 1;
+    const params = line.slice(paramsStart, paramsEnd);
+    for (const param of params.split(",")) {
+        const [key, value] = param.split("=", 2);
+        if (value === undefined)
+            continue;
+        const numberValue = Number(value);
+        if (!Number.isInteger(numberValue) || numberValue <= 0 || numberValue > 0xffffffff)
+            continue;
+        if (key === "i") {
+            ids.push(numberValue);
+        }
+        else if (key === "r") {
+            rows = numberValue;
+        }
+    }
+    return { ids, rows };
+}
+function extractKittyImageIds(line) {
+    return parseKittyImageHeader(line)?.ids ?? [];
+}
+function extractKittyImageRows(line) {
+    return parseKittyImageHeader(line)?.rows ?? 1;
+}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -75,6 +110,7 @@ export class Container {
 export class TUI extends Container {
     terminal;
     previousLines = [];
+    previousKittyImageIds = new Set();
     previousWidth = 0;
     previousHeight = 0;
     focusedComponent = null;
@@ -93,9 +129,14 @@ export class TUI extends Container {
     previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves
     fullRedrawCount = 0;
     stopped = false;
+    pendingOsc11BackgroundReplies = 0;
+    pendingOsc11BackgroundQueries = [];
+    terminalColorSchemeListeners = new Set();
+    terminalColorSchemeNotificationsEnabled = false;
     // Overlay stack for modal components rendered on top of base content
     focusOrderCounter = 0;
     overlayStack = [];
+    overlayFocusRestore = { status: "inactive" };
     constructor(terminal, showHardwareCursor) {
         super();
         this.terminal = terminal;
@@ -130,16 +171,115 @@ export class TUI extends Container {
         this.clearOnShrink = enabled;
     }
     setFocus(component) {
-        // Clear focused flag on old 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) {
+            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 &&
+                restoreState.status !== "inactive" &&
+                restoreState.overlay === previousFocusedOverlay &&
+                !this.isOverlayFocusAncestor(previousFocusedOverlay, 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();
+            }
+        }
         if (isFocusable(this.focusedComponent)) {
             this.focusedComponent.focused = false;
         }
-        this.focusedComponent = component;
-        // Set focused flag on new component
-        if (isFocusable(component)) {
-            component.focused = true;
+        this.focusedComponent = nextFocus;
+        if (isFocusable(nextFocus)) {
+            nextFocus.focused = true;
+        }
+        const focusedOverlay = nextFocus
+            ? this.overlayStack.find((entry) => entry.component === nextFocus && this.isOverlayVisible(entry))
+            : undefined;
+        if (focusedOverlay) {
+            this.overlayFocusRestore = { status: "eligible", overlay: focusedOverlay };
+        }
+    }
+    clearOverlayFocusRestore() {
+        this.overlayFocusRestore = { status: "inactive" };
+    }
+    clearOverlayFocusRestoreFor(overlay) {
+        if (this.overlayFocusRestore.status !== "inactive" && this.overlayFocusRestore.overlay === overlay) {
+            this.clearOverlayFocusRestore();
+        }
+    }
+    resolveBlockedOverlayFocusResume(restoreState) {
+        if (restoreState.resume.status === "restore-overlay")
+            return restoreState.overlay.component;
+        this.clearOverlayFocusRestore();
+        return restoreState.resume.target;
+    }
+    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();
+        let current = entry.preFocus;
+        while (current && !visited.has(current)) {
+            visited.add(current);
+            if (current === component)
+                return true;
+            current = this.overlayStack.find((overlay) => overlay.component === current)?.preFocus ?? null;
+        }
+        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.
@@ -147,7 +287,7 @@ export class TUI extends Container {
     showOverlay(component, options) {
         const entry = {
             component,
-            options,
+            ...(options === undefined ? {} : { options }),
             preFocus: this.focusedComponent,
             hidden: false,
             focusOrder: ++this.focusOrderCounter,
@@ -164,6 +304,8 @@ export class TUI extends Container {
             hide: () => {
                 const index = this.overlayStack.indexOf(entry);
                 if (index !== -1) {
+                    this.clearOverlayFocusRestoreFor(entry);
+                    this.retargetOverlayPreFocus(entry);
                     this.overlayStack.splice(index, 1);
                     // Restore focus if this overlay had focus
                     if (this.focusedComponent === component) {
@@ -181,6 +323,7 @@ export class TUI extends Container {
                 entry.hidden = hidden;
                 // Update focus when hiding/showing
                 if (hidden) {
+                    this.clearOverlayFocusRestoreFor(entry);
                     // If this overlay had focus, move focus to next visible or preFocus
                     if (this.focusedComponent === component) {
                         const topVisible = this.getTopmostVisibleOverlay();
@@ -200,17 +343,39 @@ export class TUI extends Container {
             focus: () => {
                 if (!this.overlayStack.includes(entry) || !this.isOverlayVisible(entry))
                     return;
-                if (this.focusedComponent !== component) {
-                    this.setFocus(component);
-                }
                 entry.focusOrder = ++this.focusOrderCounter;
+                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;
-                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,
@@ -218,9 +383,12 @@ 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.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();
@@ -243,16 +411,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();
@@ -263,6 +432,9 @@ export class TUI extends Container {
         this.stopped = false;
         this.terminal.start((data) => this.handleInput(data), () => this.requestRender());
         this.terminal.hideCursor();
+        if (this.terminalColorSchemeNotificationsEnabled) {
+            this.terminal.write("\x1b[?2031h");
+        }
         this.queryCellSize();
         this.requestRender();
     }
@@ -275,6 +447,21 @@ export class TUI extends Container {
     removeInputListener(listener) {
         this.inputListeners.delete(listener);
     }
+    onTerminalColorSchemeChange(listener) {
+        this.terminalColorSchemeListeners.add(listener);
+        return () => {
+            this.terminalColorSchemeListeners.delete(listener);
+        };
+    }
+    setTerminalColorSchemeNotifications(enabled) {
+        if (this.terminalColorSchemeNotificationsEnabled === enabled) {
+            return;
+        }
+        this.terminalColorSchemeNotificationsEnabled = enabled;
+        if (!this.stopped) {
+            this.terminal.write(enabled ? "\x1b[?2031h" : "\x1b[?2031l");
+        }
+    }
     queryCellSize() {
         // Only query if terminal supports images (cell size is only used for image rendering)
         if (!getCapabilities().images) {
@@ -290,6 +477,9 @@ export class TUI extends Container {
             clearTimeout(this.renderTimer);
             this.renderTimer = undefined;
         }
+        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) {
             const targetRow = this.previousLines.length; // Line after the last content
@@ -354,6 +544,12 @@ export class TUI extends Container {
         }, delay);
     }
     handleInput(data) {
+        if (this.consumeOsc11BackgroundResponse(data)) {
+            return;
+        }
+        if (this.consumeTerminalColorSchemeReport(data)) {
+            return;
+        }
         if (this.inputListeners.size > 0) {
             let current = data;
             for (const listener of this.inputListeners) {
@@ -389,8 +585,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 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)
@@ -404,6 +615,37 @@ export class TUI extends Container {
             this.requestRender();
         }
     }
+    consumeOsc11BackgroundResponse(data) {
+        if (this.pendingOsc11BackgroundReplies <= 0) {
+            return false;
+        }
+        if (!isOsc11BackgroundColorResponse(data)) {
+            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;
+        }
+        return true;
+    }
+    consumeTerminalColorSchemeReport(data) {
+        const scheme = parseTerminalColorSchemeReport(data);
+        if (!scheme) {
+            return false;
+        }
+        for (const listener of this.terminalColorSchemeListeners) {
+            listener(scheme);
+        }
+        return true;
+    }
     consumeCellSizeResponse(data) {
         // Response format: ESC [ 6 ; height ; width t
         const match = data.match(/^\x1b\[6;(\d+);(\d+)t$/);
@@ -602,11 +844,71 @@ export class TUI extends Container {
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
             if (!isImageLine(line)) {
-                lines[i] = line + reset;
+                lines[i] = normalizeTerminalOutput(line) + reset;
             }
         }
         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))
@@ -700,12 +1002,27 @@ export class TUI extends Container {
         const fullRender = (clear) => {
             this.fullRedrawCount += 1;
             let buffer = "\x1b[?2026h"; // Begin synchronized output
-            if (clear)
+            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";
-                buffer += newLines[i];
+                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);
@@ -722,6 +1039,7 @@ export class TUI extends Container {
             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;
         };
@@ -782,6 +1100,11 @@ export class TUI extends Container {
             }
             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) {
@@ -794,6 +1117,7 @@ export class TUI extends Container {
         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) {
@@ -814,16 +1138,18 @@ export class TUI extends Container {
                     fullRender(true);
                     return;
                 }
-                if (extraLines > 0) {
-                    buffer += "\x1b[1B";
+                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";
                 }
-                if (extraLines > 0) {
-                    buffer += `\x1b[${extraLines}A`;
+                const moveBack = Math.max(0, extraLines - 1 + clearStartOffset);
+                if (moveBack > 0) {
+                    buffer += `\x1b[${moveBack}A`;
                 }
                 buffer += "\x1b[?2026l";
                 this.terminal.write(buffer);
@@ -832,6 +1158,7 @@ export class TUI extends Container {
             }
             this.positionHardwareCursor(cursorPos, newLines.length);
             this.previousLines = newLines;
+            this.previousKittyImageIds = this.collectKittyImageIds(newLines);
             this.previousWidth = width;
             this.previousHeight = height;
             this.previousViewportTop = prevViewportTop;
@@ -847,6 +1174,7 @@ export class TUI extends Container {
         // 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) {
@@ -876,9 +1204,27 @@ export class TUI extends Container {
         for (let i = firstChanged; i <= renderEnd; i++) {
             if (i > firstChanged)
                 buffer += "\r\n";
-            buffer += "\x1b[2K"; // Clear current line
             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(os.homedir(), ".pi", "agent", "pi-crash.log");
@@ -966,6 +1312,7 @@ export class TUI extends Container {
         // Position hardware cursor for IME
         this.positionHardwareCursor(cursorPos, newLines.length);
         this.previousLines = newLines;
+        this.previousKittyImageIds = this.collectKittyImageIds(newLines);
         this.previousWidth = width;
         this.previousHeight = height;
     }
@@ -1004,5 +1351,57 @@ export class TUI extends Container {
             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 }) {
+        return new Promise((resolve) => {
+            const query = {
+                settled: false,
+                resolve,
+                timer: undefined,
+            };
+            query.timer = setTimeout(() => {
+                if (query.settled) {
+                    return;
+                }
+                query.settled = true;
+                query.timer = undefined;
+                query.resolve?.(undefined);
+                query.resolve = undefined;
+            }, 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");
+        });
+    }
 }
 //# sourceMappingURL=tui.js.map