@draht/tui 2026.5.12 → 2026.6.11

package/dist/tui.js

@@ -6,8 +6,29 @@ 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 { deleteKittyImage, getCapabilities, isImageLine, setCellDimensions } from "./terminal-image.js";
+import { extractSegments, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
+const KITTY_SEQUENCE_PREFIX = "\x1b_G";
+function extractKittyImageIds(line) {
+    const sequenceStart = line.indexOf(KITTY_SEQUENCE_PREFIX);
+    if (sequenceStart === -1)
+        return [];
+    const paramsStart = sequenceStart + KITTY_SEQUENCE_PREFIX.length;
+    const paramsEnd = line.indexOf(";", paramsStart);
+    if (paramsEnd === -1)
+        return [];
+    const params = line.slice(paramsStart, paramsEnd);
+    for (const param of params.split(",")) {
+        const [key, value] = param.split("=", 2);
+        if (key !== "i" || value === undefined)
+            continue;
+        const id = Number(value);
+        if (Number.isInteger(id) && id > 0 && id <= 0xffffffff) {
+            return [id];
+        }
+    }
+    return [];
+}
 /** Type guard to check if a component implements Focusable */
 export function isFocusable(component) {
     return component !== null && "focused" in component;
@@ -75,6 +96,7 @@ export class Container {
 export class TUI extends Container {
     terminal;
     previousLines = [];
+    previousKittyImageIds = new Set();
     previousWidth = 0;
     previousHeight = 0;
     focusedComponent = null;
@@ -96,6 +118,7 @@ export class TUI extends Container {
     // 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 +153,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 +269,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 +286,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 +305,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 +325,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;
+                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;
-                const topVisible = this.getTopmostVisibleOverlay();
-                this.setFocus(topVisible && topVisible !== entry ? topVisible.component : entry.preFocus);
+                }
+                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 +365,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 +393,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();
@@ -389,8 +540,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)
@@ -602,11 +768,48 @@ 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;
+    }
+    expandLastChangedForKittyImages(firstChanged, lastChanged) {
+        let expandedLastChanged = lastChanged;
+        for (let i = firstChanged; i < this.previousLines.length; i++) {
+            if (extractKittyImageIds(this.previousLines[i]).length > 0) {
+                expandedLastChanged = Math.max(expandedLastChanged, i);
+            }
+        }
+        return 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,8 +903,10 @@ 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";
@@ -722,6 +927,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 +988,9 @@ export class TUI extends Container {
             }
             lastChanged = newLines.length - 1;
         }
+        if (firstChanged !== -1) {
+            lastChanged = this.expandLastChangedForKittyImages(firstChanged, 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 +1003,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 +1024,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 +1044,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 +1060,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) {
@@ -966,6 +1180,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;
     }