@greppleai/grip-tui 0.0.0-stage → 0.1.3

package/dist/tui.js

@@ -0,0 +1,868 @@
+/**
+ * Minimal TUI implementation with differential rendering
+ */
+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, normalizeTerminalOutput, sliceByColumn, sliceWithWidth, visibleWidth } from "./utils.js";
+/** Type guard to check if a component implements Focusable */
+export function isFocusable(component) {
+    return component !== null && "focused" in component;
+}
+/**
+ * Cursor position marker - APC (Application Program Command) sequence.
+ * This is a zero-width escape sequence that terminals ignore.
+ * Components emit this at the cursor position when focused.
+ * TUI finds and strips this marker, then positions the hardware cursor there.
+ */
+export const CURSOR_MARKER = "\x1b_pi:c\x07";
+export { visibleWidth };
+/** Parse a SizeValue into absolute value given a reference size */
+function parseSizeValue(value, referenceSize) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "number")
+        return value;
+    // Parse percentage string like "50%"
+    const match = value.match(/^(\d+(?:\.\d+)?)%$/);
+    if (match) {
+        return Math.floor((referenceSize * parseFloat(match[1])) / 100);
+    }
+    return undefined;
+}
+/**
+ * Container - a component that contains other components
+ */
+export class Container {
+    children = [];
+    addChild(component) {
+        this.children.push(component);
+    }
+    removeChild(component) {
+        const index = this.children.indexOf(component);
+        if (index !== -1) {
+            this.children.splice(index, 1);
+        }
+    }
+    clear() {
+        this.children = [];
+    }
+    invalidate() {
+        for (const child of this.children) {
+            child.invalidate?.();
+        }
+    }
+    render(width) {
+        const lines = [];
+        for (const child of this.children) {
+            const childLines = child.render(width);
+            for (const line of childLines) {
+                lines.push(line);
+            }
+        }
+        return lines;
+    }
+}
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+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("@greppleai/grip-tui/viewport");
+export function isViewportTUI(tui) {
+    return tui[VIEWPORT_TUI] === true;
+}
+export class TuiBase extends Container {
+    terminal;
+    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;
+    showHardwareCursor = process.env.GRIP_HARDWARE_CURSOR === "1";
+    clearOnShrink = process.env.GRIP_CLEAR_ON_SHRINK === "1";
+    fullRedrawCount = 0;
+    stopped = false;
+    logDirectory;
+    // Overlay stack for modal components rendered on top of base content
+    focusOrderCounter = 0;
+    overlayStack = [];
+    get hasOverlayEntries() {
+        return this.overlayStack.length > 0;
+    }
+    overlayFocusRestore = { status: "inactive" };
+    constructor(terminal, showHardwareCursor, logDirectory) {
+        super();
+        this.terminal = terminal;
+        this.logDirectory =
+            logDirectory ?? process.env.GRIP_CODING_AGENT_DIR ?? path.join(os.homedir(), ".grip", "agent");
+        if (showHardwareCursor !== undefined) {
+            this.showHardwareCursor = showHardwareCursor;
+        }
+    }
+    resetRenderState() { }
+    beforeTerminalStart() { }
+    afterTerminalStart() { }
+    onTerminalResize() { }
+    onOverlayStackChanged() { }
+    beforeTerminalStop(_options) { }
+    afterTerminalStop(_options) { }
+    get fullRedraws() {
+        return this.fullRedrawCount;
+    }
+    getShowHardwareCursor() {
+        return this.showHardwareCursor;
+    }
+    setShowHardwareCursor(enabled) {
+        if (this.showHardwareCursor === enabled)
+            return;
+        this.showHardwareCursor = enabled;
+        if (!enabled) {
+            this.terminal.hideCursor();
+        }
+        this.requestRender();
+    }
+    getClearOnShrink() {
+        return this.clearOnShrink;
+    }
+    /**
+     * 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).
+     */
+    setClearOnShrink(enabled) {
+        this.clearOnShrink = enabled;
+    }
+    getFocusedComponent() {
+        return this.focusedComponent;
+    }
+    setFocus(component) {
+        this.setFocusInternal({ component, overlayFocusRestore: "clear" });
+    }
+    resolveNonOverlayFocus(nextFocus, previousFocus, restoreState) {
+        if (restoreState.status === "blocked" && restoreState.blockedBy === previousFocus) {
+            if (restoreState.resume.status === "focus-target" || !this.isComponentMounted(restoreState.blockedBy)) {
+                return this.resolveBlockedOverlayFocusResume(restoreState);
+            }
+            this.overlayFocusRestore = {
+                status: "blocked",
+                overlay: restoreState.overlay,
+                blockedBy: nextFocus,
+                resume: restoreState.resume,
+            };
+            return nextFocus;
+        }
+        const previousFocusedOverlay = previousFocus
+            ? this.overlayStack.find((entry) => entry.component === previousFocus && this.isOverlayVisible(entry))
+            : undefined;
+        if (previousFocusedOverlay &&
+            restoreState.status !== "inactive" &&
+            restoreState.overlay === previousFocusedOverlay &&
+            !this.isOverlayFocusAncestor(previousFocusedOverlay, nextFocus)) {
+            this.overlayFocusRestore = {
+                status: "blocked",
+                overlay: previousFocusedOverlay,
+                blockedBy: nextFocus,
+                resume: { status: "restore-overlay" },
+            };
+        }
+        return nextFocus;
+    }
+    resolveNullFocus(previousFocus, restoreState, overlayFocusRestore) {
+        if (restoreState.status === "blocked" && restoreState.blockedBy === previousFocus) {
+            return this.resolveBlockedOverlayFocusResume(restoreState);
+        }
+        if (overlayFocusRestore === "clear")
+            this.clearOverlayFocusRestore();
+        return null;
+    }
+    resolveFocusTarget(component, overlayFocusRestore) {
+        const previousFocus = this.focusedComponent;
+        const restoreState = this.getVisibleOverlayFocusRestore();
+        if (component === null)
+            return this.resolveNullFocus(previousFocus, restoreState, overlayFocusRestore);
+        const isOverlay = this.overlayStack.some((entry) => entry.component === component);
+        if (isOverlay)
+            return component;
+        return this.resolveNonOverlayFocus(component, previousFocus, restoreState);
+    }
+    applyFocus(nextFocus) {
+        if (isFocusable(this.focusedComponent))
+            this.focusedComponent.focused = false;
+        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 };
+    }
+    setFocusInternal({ component, overlayFocusRestore }) {
+        const nextFocus = this.resolveFocusTarget(component, overlayFocusRestore);
+        this.applyFocus(nextFocus);
+    }
+    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 preFocusByComponent = new Map();
+        for (const overlay of this.overlayStack) {
+            if (!preFocusByComponent.has(overlay.component)) {
+                preFocusByComponent.set(overlay.component, overlay.preFocus);
+            }
+        }
+        const visited = new Set();
+        let current = entry.preFocus;
+        while (current && !visited.has(current)) {
+            visited.add(current);
+            if (current === component)
+                return true;
+            current = preFocusByComponent.get(current) ?? null;
+        }
+        return false;
+    }
+    retargetOverlayPreFocus(removed) {
+        for (const overlay of this.overlayStack) {
+            if (overlay !== removed && overlay.preFocus === removed.component) {
+                overlay.preFocus = removed.preFocus;
+            }
+        }
+    }
+    getMountedRoots() {
+        return this.children;
+    }
+    isComponentMounted(component) {
+        return this.getMountedRoots().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));
+    }
+    applyBlockedOverlayUnfocus(entry, restoreState, options) {
+        if (restoreState.status !== "blocked" ||
+            restoreState.overlay !== entry ||
+            this.focusedComponent !== restoreState.blockedBy) {
+            return false;
+        }
+        if (options) {
+            this.overlayFocusRestore = {
+                status: "blocked",
+                overlay: entry,
+                blockedBy: restoreState.blockedBy,
+                resume: { status: "focus-target", target: options.target },
+            };
+        }
+        else {
+            this.clearOverlayFocusRestore();
+        }
+        this.requestRender();
+        return true;
+    }
+    unfocusOverlay(entry, options) {
+        const isFocused = this.focusedComponent === entry.component;
+        const restoreState = this.overlayFocusRestore;
+        const hasPendingRestore = restoreState.status !== "inactive" && restoreState.overlay === entry;
+        if (!isFocused && !hasPendingRestore)
+            return;
+        if (this.applyBlockedOverlayUnfocus(entry, restoreState, options))
+            return;
+        this.clearOverlayFocusRestoreFor(entry);
+        if (isFocused || options) {
+            const topVisible = this.getTopmostVisibleOverlay();
+            const fallbackTarget = topVisible && topVisible !== entry ? topVisible.component : entry.preFocus;
+            this.setFocus(options ? options.target : fallbackTarget);
+        }
+        this.requestRender();
+    }
+    /**
+     * Show an overlay component with configurable positioning and sizing.
+     * Returns a handle to control the overlay's visibility.
+     */
+    showOverlay(component, options) {
+        const entry = {
+            component,
+            ...(options === undefined ? {} : { options }),
+            preFocus: this.focusedComponent,
+            hidden: false,
+            focusOrder: ++this.focusOrderCounter,
+            visible: false,
+        };
+        this.overlayStack.push(entry);
+        entry.visible = this.isOverlayVisible(entry);
+        this.onOverlayStackChanged();
+        // Only focus if overlay is actually visible
+        if (!options?.nonCapturing && this.isOverlayVisible(entry)) {
+            this.setFocus(component);
+        }
+        this.terminal.hideCursor();
+        this.requestRender();
+        // Return handle for controlling this overlay
+        return {
+            hide: () => {
+                const index = this.overlayStack.indexOf(entry);
+                if (index !== -1) {
+                    this.clearOverlayFocusRestoreFor(entry);
+                    this.retargetOverlayPreFocus(entry);
+                    this.overlayStack.splice(index, 1);
+                    this.onOverlayStackChanged();
+                    // Restore focus if this overlay had focus
+                    if (this.focusedComponent === component) {
+                        const topVisible = this.getTopmostVisibleOverlay();
+                        this.setFocus(topVisible?.component ?? entry.preFocus);
+                    }
+                    if (this.overlayStack.length === 0)
+                        this.terminal.hideCursor();
+                    this.requestRender();
+                }
+            },
+            setHidden: (hidden) => {
+                if (entry.hidden === hidden)
+                    return;
+                entry.hidden = hidden;
+                entry.visible = this.isOverlayVisible(entry);
+                // 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();
+                        this.setFocus(topVisible?.component ?? entry.preFocus);
+                    }
+                }
+                else {
+                    // Restore focus to this overlay when showing (if it's actually visible)
+                    if (!options?.nonCapturing && this.isOverlayVisible(entry)) {
+                        entry.focusOrder = ++this.focusOrderCounter;
+                        this.setFocus(component);
+                    }
+                }
+                this.onOverlayStackChanged();
+                this.requestRender();
+            },
+            isHidden: () => entry.hidden,
+            focus: () => {
+                if (!this.overlayStack.includes(entry) || !this.isOverlayVisible(entry))
+                    return;
+                entry.focusOrder = ++this.focusOrderCounter;
+                this.setFocus(component);
+                this.requestRender();
+            },
+            unfocus: (unfocusOptions) => this.unfocusOverlay(entry, unfocusOptions),
+            isFocused: () => this.focusedComponent === component,
+        };
+    }
+    /** Hide the topmost overlay and restore previous focus. */
+    hideOverlay() {
+        const overlay = this.overlayStack[this.overlayStack.length - 1];
+        if (!overlay)
+            return;
+        this.clearOverlayFocusRestoreFor(overlay);
+        this.retargetOverlayPreFocus(overlay);
+        this.overlayStack.pop();
+        this.onOverlayStackChanged();
+        if (this.focusedComponent === overlay.component) {
+            // Find topmost visible overlay, or fall back to preFocus
+            const topVisible = this.getTopmostVisibleOverlay();
+            this.setFocus(topVisible?.component ?? overlay.preFocus);
+        }
+        if (this.overlayStack.length === 0)
+            this.terminal.hideCursor();
+        this.requestRender();
+    }
+    /** Check if there are any visible overlays */
+    hasOverlay() {
+        return this.overlayStack.some((o) => this.isOverlayVisible(o));
+    }
+    hasCapturingOverlay() {
+        return this.overlayStack.some((o) => !o.options?.nonCapturing && this.isOverlayVisible(o));
+    }
+    /** Check if an overlay entry is currently visible */
+    isOverlayVisible(entry) {
+        if (entry.hidden)
+            return false;
+        if (entry.options?.visible) {
+            return entry.options.visible(this.terminal.columns, this.terminal.rows);
+        }
+        return true;
+    }
+    /** Find the visual-frontmost visible capturing overlay, if any */
+    getTopmostVisibleOverlay() {
+        let topmost;
+        for (const overlay of this.overlayStack) {
+            if (overlay.options?.nonCapturing || !this.isOverlayVisible(overlay))
+                continue;
+            if (!topmost || overlay.focusOrder > topmost.focusOrder) {
+                topmost = overlay;
+            }
+        }
+        return topmost;
+    }
+    refreshOverlayVisibility() {
+        let newlyVisible;
+        for (const overlay of this.overlayStack) {
+            const visible = this.isOverlayVisible(overlay);
+            if (visible && !overlay.visible && !overlay.options?.nonCapturing) {
+                if (!newlyVisible || overlay.focusOrder > newlyVisible.focusOrder)
+                    newlyVisible = overlay;
+            }
+            overlay.visible = visible;
+        }
+        return newlyVisible;
+    }
+    retargetFocusFromHiddenOverlay() {
+        const focusedOverlay = this.overlayStack.find((overlay) => overlay.component === this.focusedComponent);
+        if (!focusedOverlay || this.isOverlayVisible(focusedOverlay))
+            return;
+        const topVisible = this.getTopmostVisibleOverlay();
+        if (topVisible) {
+            this.setFocus(topVisible.component);
+            return;
+        }
+        this.setFocusInternal({ component: focusedOverlay.preFocus, overlayFocusRestore: "preserve" });
+    }
+    focusNewlyVisibleOverlay(newlyVisible) {
+        if (!newlyVisible)
+            return;
+        const currentFocusedOverlay = this.overlayStack.find((overlay) => overlay.component === this.focusedComponent && this.isOverlayVisible(overlay));
+        if (!currentFocusedOverlay || newlyVisible.focusOrder > currentFocusedOverlay.focusOrder) {
+            this.setFocus(newlyVisible.component);
+        }
+    }
+    restoreVisibleOverlayFocus() {
+        if (this.overlayStack.some((overlay) => overlay.component === this.focusedComponent))
+            return;
+        const restoreState = this.getVisibleOverlayFocusRestore();
+        if (restoreState.status === "eligible") {
+            this.setFocus(restoreState.overlay.component);
+            return;
+        }
+        if (restoreState.status !== "blocked" || restoreState.blockedBy === this.focusedComponent)
+            return;
+        if (restoreState.resume.status === "restore-overlay") {
+            this.setFocus(restoreState.overlay.component);
+            return;
+        }
+        this.clearOverlayFocusRestore();
+        this.setFocus(restoreState.resume.target);
+    }
+    reconcileOverlayFocus() {
+        const newlyVisible = this.refreshOverlayVisibility();
+        this.retargetFocusFromHiddenOverlay();
+        this.focusNewlyVisibleOverlay(newlyVisible);
+        this.restoreVisibleOverlayFocus();
+    }
+    invalidate() {
+        for (const root of this.getMountedRoots())
+            root.invalidate();
+        for (const overlay of this.overlayStack)
+            overlay.component.invalidate?.();
+    }
+    start() {
+        this.stopped = false;
+        try {
+            this.beforeTerminalStart();
+            this.terminal.start((data) => this.handleTerminalInput(data), () => {
+                this.reconcileOverlayFocus();
+                this.onTerminalResize();
+                this.requestRender();
+            });
+            this.afterTerminalStart();
+            this.terminal.hideCursor();
+            this.queryCellSize();
+            this.requestRender();
+        }
+        catch (error) {
+            // A terminal may throw after partially entering raw or alternate-screen mode.
+            // Route startup failures through the same complete cleanup path as signals.
+            try {
+                this.stop();
+            }
+            catch {
+                // Preserve the startup failure; cleanup is best-effort but exhaustive.
+            }
+            throw error;
+        }
+    }
+    addInputListener(listener) {
+        this.inputListeners.add(listener);
+        return () => {
+            this.inputListeners.delete(listener);
+        };
+    }
+    removeInputListener(listener) {
+        this.inputListeners.delete(listener);
+    }
+    queryCellSize() {
+        // Only query if terminal supports images (cell size is only used for image rendering)
+        if (!getCapabilities().images) {
+            return;
+        }
+        // Query terminal for cell size in pixels: CSI 16 t
+        // Response format: CSI 6 ; height ; width t
+        this.terminal.write("\x1b[16t");
+    }
+    stop(options) {
+        this.stopped = true;
+        this.renderRequested = false;
+        this.cancelRenderTimer();
+        let failure;
+        const cleanup = (action) => {
+            try {
+                action();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        };
+        cleanup(() => this.beforeTerminalStop(options));
+        cleanup(() => this.terminal.showCursor());
+        cleanup(() => this.terminal.stop());
+        // Alternate-screen exit and capability restoration must run even when
+        // keyboard/raw-mode shutdown reports an error.
+        cleanup(() => this.afterTerminalStop(options));
+        if (failure !== undefined)
+            throw failure;
+    }
+    renderNow(force = false) {
+        if (force)
+            this.resetRenderState();
+        this.renderRequested = false;
+        this.cancelRenderTimer();
+        this.lastRenderAt = performance.now();
+        this.doRender();
+    }
+    requestRender(force = false) {
+        if (force) {
+            this.resetRenderState();
+            this.requestImmediateRender();
+            return;
+        }
+        if (this.renderRequested)
+            return;
+        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;
+            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, TuiBase.MIN_RENDER_INTERVAL_MS - elapsed);
+        this.renderTimer = setTimeout(() => {
+            this.renderTimer = undefined;
+            if (this.stopped || !this.renderRequested)
+                return;
+            this.renderRequested = false;
+            this.lastRenderAt = performance.now();
+            this.doRender();
+            if (this.renderRequested)
+                this.scheduleRender();
+        }, delay);
+    }
+    applyInputListeners(data) {
+        if (this.inputListeners.size === 0)
+            return data;
+        let current = data;
+        for (const listener of this.inputListeners) {
+            const result = listener(current);
+            if (result?.consume)
+                return undefined;
+            if (result?.data !== undefined)
+                current = result.data;
+        }
+        return current.length === 0 ? undefined : current;
+    }
+    handleTerminalInput(data) {
+        this.reconcileOverlayFocus();
+        const filteredData = this.applyInputListeners(data);
+        if (filteredData === undefined)
+            return;
+        data = filteredData;
+        // Consume terminal cell size responses without blocking unrelated input.
+        if (this.consumeCellSizeResponse(data))
+            return;
+        // Global debug key handler (Shift+Ctrl+D)
+        if (matchesKey(data, "shift+ctrl+d") && this.onDebug) {
+            this.onDebug();
+            return;
+        }
+        // Pass input to focused component (including Ctrl+C).
+        // The focused component can decide how to handle Ctrl+C.
+        if (!this.focusedComponent?.handleInput)
+            return;
+        // Filter out key release events unless component opts in.
+        if (isKeyRelease(data) && !this.focusedComponent.wantsKeyRelease)
+            return;
+        this.focusedComponent.handleInput(data);
+        this.requestImmediateRender();
+    }
+    consumeCellSizeResponse(data) {
+        // Response format: ESC [ 6 ; height ; width t
+        const match = data.match(/^\x1b\[6;(\d+);(\d+)t$/);
+        if (!match) {
+            return false;
+        }
+        const heightPx = parseInt(match[1], 10);
+        const widthPx = parseInt(match[2], 10);
+        if (heightPx <= 0 || widthPx <= 0) {
+            return true;
+        }
+        setCellDimensions({ widthPx, heightPx });
+        // Invalidate all components so images re-render with correct dimensions.
+        this.invalidate();
+        this.requestRender();
+        return true;
+    }
+    resolveOverlayBounds(options, termWidth, termHeight) {
+        const margin = typeof options.margin === "number"
+            ? { top: options.margin, right: options.margin, bottom: options.margin, left: options.margin }
+            : (options.margin ?? {});
+        const marginTop = Math.max(0, margin.top ?? 0);
+        const marginRight = Math.max(0, margin.right ?? 0);
+        const marginBottom = Math.max(0, margin.bottom ?? 0);
+        const marginLeft = Math.max(0, margin.left ?? 0);
+        return {
+            marginTop,
+            marginRight,
+            marginBottom,
+            marginLeft,
+            availableWidth: Math.max(1, termWidth - marginLeft - marginRight),
+            availableHeight: Math.max(1, termHeight - marginTop - marginBottom),
+        };
+    }
+    resolveOverlayWidth(options, termWidth, bounds) {
+        let width = parseSizeValue(options.width, termWidth) ?? Math.min(80, bounds.availableWidth);
+        if (options.minWidth !== undefined)
+            width = Math.max(width, options.minWidth);
+        return Math.max(1, Math.min(width, bounds.availableWidth));
+    }
+    resolveOverlayMaxHeight(options, termHeight, bounds) {
+        const maxHeight = parseSizeValue(options.maxHeight, termHeight);
+        return maxHeight === undefined ? undefined : Math.max(1, Math.min(maxHeight, bounds.availableHeight));
+    }
+    resolveOverlayRow(options, overlayHeight, bounds) {
+        if (options.row === undefined) {
+            return this.resolveAnchorRow(options.anchor ?? "center", overlayHeight, bounds.availableHeight, bounds.marginTop);
+        }
+        if (typeof options.row === "number")
+            return options.row;
+        const match = options.row.match(/^(\d+(?:\.\d+)?)%$/);
+        if (!match)
+            return this.resolveAnchorRow("center", overlayHeight, bounds.availableHeight, bounds.marginTop);
+        const maxRow = Math.max(0, bounds.availableHeight - overlayHeight);
+        return bounds.marginTop + Math.floor(maxRow * (parseFloat(match[1]) / 100));
+    }
+    resolveOverlayColumn(options, width, bounds) {
+        if (options.col === undefined) {
+            return this.resolveAnchorCol(options.anchor ?? "center", width, bounds.availableWidth, bounds.marginLeft);
+        }
+        if (typeof options.col === "number")
+            return options.col;
+        const match = options.col.match(/^(\d+(?:\.\d+)?)%$/);
+        if (!match)
+            return this.resolveAnchorCol("center", width, bounds.availableWidth, bounds.marginLeft);
+        const maxCol = Math.max(0, bounds.availableWidth - width);
+        return bounds.marginLeft + Math.floor(maxCol * (parseFloat(match[1]) / 100));
+    }
+    /** Resolve overlay layout from options. */
+    resolveOverlayLayout(options, overlayHeight, termWidth, termHeight) {
+        const resolvedOptions = options ?? {};
+        const bounds = this.resolveOverlayBounds(resolvedOptions, termWidth, termHeight);
+        const width = this.resolveOverlayWidth(resolvedOptions, termWidth, bounds);
+        const maxHeight = this.resolveOverlayMaxHeight(resolvedOptions, termHeight, bounds);
+        const effectiveHeight = maxHeight === undefined ? overlayHeight : Math.min(overlayHeight, maxHeight);
+        let row = this.resolveOverlayRow(resolvedOptions, effectiveHeight, bounds) + (resolvedOptions.offsetY ?? 0);
+        let col = this.resolveOverlayColumn(resolvedOptions, width, bounds) + (resolvedOptions.offsetX ?? 0);
+        row = Math.max(bounds.marginTop, Math.min(row, termHeight - bounds.marginBottom - effectiveHeight));
+        col = Math.max(bounds.marginLeft, Math.min(col, termWidth - bounds.marginRight - width));
+        return { width, row, col, maxHeight };
+    }
+    resolveAnchorRow(anchor, height, availHeight, marginTop) {
+        switch (anchor) {
+            case "top-left":
+            case "top-center":
+            case "top-right":
+                return marginTop;
+            case "bottom-left":
+            case "bottom-center":
+            case "bottom-right":
+                return marginTop + availHeight - height;
+            case "left-center":
+            case "center":
+            case "right-center":
+                return marginTop + Math.floor((availHeight - height) / 2);
+        }
+    }
+    resolveAnchorCol(anchor, width, availWidth, marginLeft) {
+        switch (anchor) {
+            case "top-left":
+            case "left-center":
+            case "bottom-left":
+                return marginLeft;
+            case "top-right":
+            case "right-center":
+            case "bottom-right":
+                return marginLeft + availWidth - width;
+            case "top-center":
+            case "center":
+            case "bottom-center":
+                return marginLeft + Math.floor((availWidth - width) / 2);
+        }
+    }
+    prepareOverlayRenderPlan(baseLineCount, termWidth, termHeight) {
+        const visibleEntries = this.overlayStack.filter((entry) => this.isOverlayVisible(entry));
+        visibleEntries.sort((left, right) => left.focusOrder - right.focusOrder);
+        const overlays = [];
+        let minimumLineCount = baseLineCount;
+        for (const entry of visibleEntries) {
+            const { width, maxHeight } = this.resolveOverlayLayout(entry.options, 0, termWidth, termHeight);
+            let overlayLines = entry.component.render(width);
+            if (maxHeight !== undefined && overlayLines.length > maxHeight) {
+                overlayLines = overlayLines.slice(0, maxHeight);
+            }
+            const { row, col } = this.resolveOverlayLayout(entry.options, overlayLines.length, termWidth, termHeight);
+            overlays.push({ lines: overlayLines, row, col, width });
+            minimumLineCount = Math.max(minimumLineCount, row + overlayLines.length);
+        }
+        return { overlays, minimumLineCount };
+    }
+    compositeRenderedOverlay(result, overlay, viewportStart, termWidth) {
+        for (let lineIndex = 0; lineIndex < overlay.lines.length; lineIndex++) {
+            const targetIndex = viewportStart + overlay.row + lineIndex;
+            if (targetIndex < 0 || targetIndex >= result.length)
+                continue;
+            const overlayLine = overlay.lines[lineIndex];
+            const truncatedLine = visibleWidth(overlayLine) > overlay.width
+                ? sliceByColumn(overlayLine, 0, overlay.width, true)
+                : overlayLine;
+            result[targetIndex] = this.compositeLineAt(result[targetIndex], truncatedLine, overlay.col, overlay.width, termWidth);
+        }
+    }
+    /** Composite all overlays into content lines (sorted by focusOrder, higher = on top). */
+    compositeOverlays(lines, termWidth, termHeight) {
+        if (this.overlayStack.length === 0)
+            return lines;
+        const result = [...lines];
+        const plan = this.prepareOverlayRenderPlan(result.length, termWidth, termHeight);
+        const workingHeight = Math.max(result.length, termHeight, plan.minimumLineCount);
+        while (result.length < workingHeight)
+            result.push("");
+        const viewportStart = Math.max(0, workingHeight - termHeight);
+        for (const overlay of plan.overlays) {
+            this.compositeRenderedOverlay(result, overlay, viewportStart, termWidth);
+        }
+        return result;
+    }
+    applyLineResets(lines) {
+        const reset = SEGMENT_RESET;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!isImageLine(line)) {
+                lines[i] = normalizeTerminalOutput(line) + reset;
+            }
+        }
+        return lines;
+    }
+    compositeLineAt(baseLine, overlayLine, startCol, overlayWidth, totalWidth) {
+        return compositeTuiLine(baseLine, overlayLine, startCol, overlayWidth, totalWidth);
+    }
+    /**
+     * Find and extract cursor position from rendered lines.
+     * Searches for CURSOR_MARKER, calculates its position, and strips it from the output.
+     * Only scans the bottom terminal height lines (visible viewport).
+     * @param lines - Rendered lines to search
+     * @param height - Terminal height (visible viewport size)
+     * @returns Cursor position { row, col } or null if no marker found
+     */
+    extractCursorPosition(lines, height) {
+        // Only scan the bottom `height` lines (visible viewport)
+        const viewportTop = Math.max(0, lines.length - height);
+        for (let row = lines.length - 1; row >= viewportTop; row--) {
+            const line = lines[row];
+            const markerIndex = line.indexOf(CURSOR_MARKER);
+            if (markerIndex !== -1) {
+                // Calculate visual column (width of text before marker)
+                const beforeMarker = line.slice(0, markerIndex);
+                const col = visibleWidth(beforeMarker);
+                // Strip marker from the line
+                lines[row] = line.slice(0, markerIndex) + line.slice(markerIndex + CURSOR_MARKER.length);
+                return { row, col };
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=tui.js.map