@prometheus-ai/tui 0.5.0

package/dist/types/stdin-buffer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * StdinBuffer buffers input and emits complete sequences.
+ *
+ * This is necessary because stdin data events can arrive in partial chunks,
+ * especially for escape sequences like mouse events. Without buffering,
+ * partial sequences can be misinterpreted as regular keypresses.
+ *
+ * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
+ * - Event 1: `\x1b`
+ * - Event 2: `[<35`
+ * - Event 3: `;20;5m`
+ *
+ * The buffer accumulates these until a complete sequence is detected.
+ * Call the `process()` method to feed input data.
+ *
+ * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
+ * MIT License - Copyright (c) 2025 opentui
+ */
+import { EventEmitter } from "events";
+export type StdinBufferOptions = {
+    /**
+     * Maximum time to wait for sequence completion (default: 75ms).
+     * After this time, a genuinely incomplete escape is flushed.
+     */
+    timeout?: number;
+};
+export type StdinBufferEventMap = {
+    data: [string];
+    paste: [string];
+};
+/**
+ * Buffers stdin input and emits complete sequences via the 'data' event.
+ * Handles partial escape sequences that arrive across multiple chunks.
+ */
+export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
+    #private;
+    constructor(options?: StdinBufferOptions);
+    process(data: string | Buffer): void;
+    flush(): string[];
+    clear(): void;
+    getBuffer(): string;
+    destroy(): void;
+}

package/dist/types/symbols.d.ts

@@ -0,0 +1,25 @@
+export interface BoxSymbols {
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+    teeDown: string;
+    teeUp: string;
+    teeLeft: string;
+    teeRight: string;
+    cross: string;
+}
+export interface SymbolTheme {
+    cursor: string;
+    inputCursor: string;
+    boxRound: Omit<BoxSymbols, "teeDown" | "teeUp" | "teeLeft" | "teeRight" | "cross">;
+    boxSharp: BoxSymbols;
+    table: BoxSymbols;
+    quoteBorder: string;
+    hrChar: string;
+    /** Chip glyph drawn (painted with the referenced color) before inline hex colors. */
+    colorSwatch?: string;
+    spinnerFrames: string[];
+}

package/dist/types/terminal-capabilities.d.ts

@@ -0,0 +1,196 @@
+export declare enum ImageProtocol {
+    Kitty = "\u001B_G",
+    Iterm2 = "\u001B]1337;File=",
+    Sixel = "\u001BPq"
+}
+export declare enum NotifyProtocol {
+    Bell = "\u0007",
+    Osc99 = "\u001B]99;;",
+    Osc9 = "\u001B]9;"
+}
+export type TerminalId = "kitty" | "ghostty" | "wezterm" | "iterm2" | "vscode" | "alacritty" | "base" | "trueColor";
+/** Terminal capability details used for rendering and protocol selection. */
+export declare class TerminalInfo {
+    readonly id: TerminalId;
+    readonly imageProtocol: ImageProtocol | null;
+    readonly trueColor: boolean;
+    readonly hyperlinks: boolean;
+    readonly notifyProtocol: NotifyProtocol;
+    readonly eagerEraseScrollbackRisk: boolean;
+    readonly deccara: boolean;
+    readonly supportsScreenToScrollback: boolean;
+    /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
+    readonly textSizing: boolean;
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean, deccara?: boolean, supportsScreenToScrollback?: boolean, 
+    /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
+    textSizing?: boolean);
+    isImageLine(line: string): boolean;
+    formatNotification(message: string | TerminalNotification): string;
+    sendNotification(message: string | TerminalNotification): void;
+}
+export declare function isNotificationSuppressed(): boolean;
+/**
+ * Returns true when running in Windows Terminal with known SIXEL support.
+ *
+ * Windows Terminal introduced SIXEL support in preview 1.22.
+ */
+export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether live-frame native scrollback rebuilds are unsafe when the terminal
+ * viewport position is unobservable.
+ *
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
+ * terminals either clamp a scrolled reader back to the active tail or erase host
+ * scrollback when ED3 lands. The important property is not the brand name — it
+ * is that an unknown viewport position cannot be proven safe. Environment
+ * markers are therefore only used to prove *risk* or a strongly-known profile;
+ * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
+ *
+ * Native win32 is excluded here because the renderer has dedicated ConPTY
+ * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
+ * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
+ */
+export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
+export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, terminalId?: TerminalId): boolean;
+/**
+ * Whether the terminal applies Kitty-style DECCARA rectangular SGR changes
+ * (`CSI Pt ; Pl ; Pb ; Pr ; <sgr> $ r`) extended to background color, so large
+ * filled regions can be painted as rectangles instead of background-padded
+ * strings on every row.
+ *
+ * Verified against terminal sources rather than terminfo, because a bare
+ * `Cara`/DECCARA terminfo capability does not imply the Kitty SGR-background
+ * extension:
+ * - Kitty implements it for *all* SGR attributes including background (see
+ *   kitty `docs/deccara.rst` and the `test_deccara` parser test).
+ * - Ghostty does NOT: its `CSI $ r` dispatch falls through to an "unknown CSI"
+ *   warning and DECCARA/DECSACE are tracked as unsupported
+ *   (ghostty-org/ghostty#632). Enabling it there would silently drop panel
+ *   backgrounds, so ghostty stays on the padded-string fallback.
+ *
+ * Disabled under tmux/screen/zellij multiplexers — screen-coordinate rectangle
+ * protocols are not safe to assume through a multiplexer — and via the
+ * `PROMETHEUS_NO_DECCARA` kill switch. Pure helper for tests and `TERMINAL` construction.
+ */
+export declare function detectRectangularSgrSupport(terminalId: TerminalId, env?: NodeJS.ProcessEnv): boolean;
+export declare const TERMINAL_ID: TerminalId;
+export declare const TERMINAL: TerminalInfo;
+/**
+ * Override terminal image protocol at runtime after capability probes complete.
+ */
+export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void;
+/**
+ * Override DECCARA rectangular-SGR capability at runtime. Used by tests to
+ * exercise the optimizer and fallback paths deterministically — the default is
+ * resolved once at import and force-disabled under the test runtime.
+ */
+export declare function setTerminalDeccara(enabled: boolean): void;
+/** Override screen-to-scrollback clear support for targeted renderer tests. */
+export declare function setTerminalScreenToScrollback(enabled: boolean): void;
+/**
+ * Enable/disable OSC 66 text-sizing at runtime. The coding-agent calls this from
+ * the `tui.textSizing` setting (gated on the terminal's static `textSizing`
+ * capability); tests flip it directly to exercise the scaled-heading path.
+ */
+export declare function setTerminalTextSizing(enabled: boolean): void;
+export declare function getTerminalInfo(terminalId: TerminalId): TerminalInfo;
+export interface CellDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageRenderOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    preserveAspectRatio?: boolean;
+    /**
+     * Stable Kitty image id (`i=`). When set, the image is displayed via a
+     * transmit-once + placement scheme keyed off this id instead of re-sending the
+     * base64 each frame.
+     */
+    imageId?: number;
+    /** Stable Kitty placement id (`p=`); defaults to {@link imageId}. */
+    placementId?: number;
+    /** When true (Kitty + {@link imageId}), also return the one-time transmit sequence. */
+    includeTransmit?: boolean;
+}
+export declare function getCellDimensions(): CellDimensions;
+export declare function setCellDimensions(dims: CellDimensions): void;
+/** Transmit-and-display (`a=T`) — the self-contained form used when no stable id is available. */
+export declare function encodeKitty(base64Data: string, options?: {
+    columns?: number;
+    rows?: number;
+    imageId?: number;
+}): string;
+/**
+ * Transmit image data only (`a=t`), keyed by `imageId`, without displaying it.
+ * Sent once per image; the data then persists in the terminal's store (it
+ * survives scroll-off and text clears for images with a non-zero id), so
+ * subsequent frames display it with the tiny {@link encodeKittyPlacement}
+ * sequence instead of re-sending the base64.
+ */
+export declare function encodeKittyTransmit(base64Data: string, imageId: number): string;
+/**
+ * Display a previously transmitted image (`a=p`) at the cursor. Carrying a
+ * stable `placementId` (`p=`) means re-emitting the sequence on a repaint
+ * *replaces* the existing placement (moving/resizing it without flicker) rather
+ * than stacking a duplicate.
+ */
+export declare function encodeKittyPlacement(options: {
+    imageId: number;
+    placementId?: number;
+    columns?: number;
+    rows?: number;
+}): string;
+/**
+ * Kitty graphics delete command for a single image id. Uses `d=I` (capital)
+ * which removes the image and every one of its placements — on screen *and* in
+ * scrollback — and frees the backing data. `q=2` suppresses the terminal reply.
+ * Text-clearing escapes (`CSI 2 J` / `CSI 3 J`) do not remove Kitty graphics, so
+ * this is the only way to actually purge a placed image.
+ */
+export declare function encodeKittyDeleteImage(imageId: number): string;
+export declare function encodeITerm2(base64Data: string, options?: {
+    width?: number | string;
+    height?: number | string;
+    name?: string;
+    preserveAspectRatio?: boolean;
+    inline?: boolean;
+}): string;
+export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
+export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
+export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
+export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
+export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
+export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
+export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
+    sequence?: string;
+    lines?: string[];
+    rows: number;
+    transmit?: string;
+} | null;
+export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+/**
+ * Structured terminal notification. Rich fields are honored only by OSC 99
+ * (Kitty) once support is confirmed; other protocols and the unconfirmed Kitty
+ * path collapse to a single `title: body` line.
+ */
+export interface TerminalNotification {
+    title?: string;
+    body?: string;
+    id?: string;
+    type?: string | string[];
+    urgency?: "low" | "normal" | "critical";
+    iconName?: string;
+    sound?: "silent" | "system" | "info" | "warning" | "error" | "question";
+    actions?: "focus" | "report" | "focus-report" | "none";
+    expiresMs?: number;
+}
+/** Record the OSC 99 capability-probe result (called by ProcessTerminal). */
+export declare function setOsc99Supported(supported: boolean): void;
+/** True when OSC 99 structured notifications have been confirmed available. */
+export declare function isOsc99Supported(): boolean;

package/dist/types/terminal.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Emergency terminal restore - call this from signal/crash handlers
+ * Resets terminal state without requiring access to the ProcessTerminal instance
+ */
+export declare function emergencyTerminalRestore(): void;
+/** Terminal-reported appearance (dark/light mode). */
+export type TerminalAppearance = "dark" | "light";
+export interface Terminal {
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    /**
+     * Drain stdin before exiting to prevent Kitty key release events from
+     * leaking to the parent shell over slow SSH connections.
+     * @param maxMs - Maximum time to drain (default: 1000ms)
+     * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
+     */
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    get columns(): number;
+    get rows(): number;
+    get kittyProtocolActive(): boolean;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    /**
+     * Returns whether the native terminal viewport is at the scrollback tail when
+     * the host exposes that state. `undefined` means the terminal cannot report it.
+     *
+     * `ProcessTerminal` deliberately does not implement this — no real terminal
+     * can answer it truthfully:
+     *
+     * - POSIX terminals expose no scrollback-position API at all.
+     * - Every modern Windows terminal host (Windows Terminal, VS Code, Tabby,
+     *   Hyper, Alacritty, WezTerm, JetBrains, …) fronts console apps through
+     *   ConPTY, where kernel32's `GetConsoleScreenBufferInfo` describes the
+     *   pseudo-console buffer. That buffer is pinned to the visible grid —
+     *   scrollback lives in the host UI, invisible to console APIs
+     *   (microsoft/terminal#10191) — so a probe reads "at bottom" no matter
+     *   where the user scrolled. Trusting it let streaming-time rebuilds emit
+     *   `\x1b[3J` and yank scrolled readers: #1635 (Windows Terminal), #1746
+     *   (Tabby and other ConPTY hosts). No env var distinguishes these hosts
+     *   (Tabby sets none), so trust cannot be conditional on the environment.
+     * - Legacy conhost (the only non-ConPTY host) keeps a real scrollback
+     *   buffer, but its window follows the output cursor: a probe comparing
+     *   `srWindow.Bottom` against `dwSize.Y - 1` reads "scrolled up" for a user
+     *   following live output until all ~9001 buffer rows fill, permanently
+     *   blocking checkpoint scrollback reconciliation.
+     *
+     * The renderer treats a missing implementation / `undefined` as "unknown":
+     * live mutations defer destructive rebuilds and reconcile native scrollback
+     * at explicit checkpoints (prompt submit), where the user's keystroke has
+     * already pinned the host viewport to the bottom. Only test terminals
+     * (xterm.js-backed) implement this with a real answer.
+     */
+    isNativeViewportAtBottom?(): boolean | undefined;
+    /**
+     * Override the global terminal-profile ED3 risk decision for custom/test
+     * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
+     */
+    hasEagerEraseScrollbackRisk?(): boolean | undefined;
+    /**
+     * Register a callback for terminal appearance (dark/light) changes.
+     * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
+     * Fires when the detected appearance changes, including the initial detection.
+     */
+    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    /** The last detected terminal appearance, or undefined if not yet known. */
+    get appearance(): TerminalAppearance | undefined;
+    /**
+     * Register a callback fired once per DEC private mode when its DECRQM support
+     * status resolves. Optional: only real terminals implement capability probing.
+     */
+    onPrivateModeReport?(callback: (mode: number, supported: boolean) => void): void;
+}
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export declare class ProcessTerminal implements Terminal {
+    #private;
+    get kittyProtocolActive(): boolean;
+    get appearance(): TerminalAppearance | undefined;
+    onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    onPrivateModeReport(callback: (mode: number, supported: boolean) => void): void;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    stop(): void;
+    write(data: string): void;
+    get columns(): number;
+    get rows(): number;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}

package/dist/types/ttyid.d.ts

@@ -0,0 +1,9 @@
+/** Resolve the TTY device path for stdin (fd 0) via POSIX `ttyname(3)`. */
+export declare function getTtyPath(): string | null;
+/**
+ * Get a stable identifier for the current terminal.
+ * Uses the TTY device path (e.g., /dev/pts/3), falling back to environment
+ * variables for terminal multiplexers or terminal emulators.
+ * Returns null if no terminal can be identified (e.g., piped input).
+ */
+export declare function getTerminalId(): string | null;

package/dist/types/tui.d.ts

@@ -0,0 +1,275 @@
+import { ImageBudget } from "./components/image";
+import type { Terminal } from "./terminal";
+import { visibleWidth } from "./utils";
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+export interface RenderTimer {
+    cancel(): void;
+}
+export interface RenderScheduler {
+    now(): number;
+    scheduleImmediate(callback: () => void): void;
+    scheduleRender(callback: () => void, delayMs: number): RenderTimer;
+}
+export interface TUIOptions {
+    renderScheduler?: RenderScheduler;
+}
+/**
+ * Component interface - all components must implement this
+ */
+export interface Component {
+    /**
+     * Render the component to lines for the given viewport width
+     * @param width - Current viewport width
+     * @returns Array of strings, each representing a line
+     */
+    render(width: number): string[];
+    /**
+     * Optional handler for keyboard input when component has focus
+     */
+    handleInput?(data: string): void;
+    /**
+     * If true, component receives key release events (Kitty protocol).
+     * Default is false - release events are filtered out.
+     */
+    wantsKeyRelease?: boolean;
+    /**
+     * Invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate(): void;
+}
+/**
+ * Optional component seam for native-scrollback pinning. A component that
+ * renders a stable prefix followed by a live/transient suffix reports the local
+ * line index where that suffix begins after each render. TUI treats that suffix
+ * — and every root child rendered below it — as not yet safe to commit to native
+ * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ *
+ * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
+ * inside that live suffix: the line index up to which the live region is
+ * append-only (its earlier rows never re-layout, only new rows append at the
+ * bottom — a streaming assistant message). Rows in `[liveRegionStart,
+ * commitSafeEnd)` that scroll above the viewport are safe to commit to native
+ * scrollback even though they are technically live, because they will never
+ * change. Without this, a single live block that alone overflows the viewport
+ * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
+ * live blocks (tool previews that collapse) omit it, so their mutable rows stay
+ * deferred. Defaults to `liveRegionStart` when absent.
+ */
+export interface NativeScrollbackLiveRegion {
+    getNativeScrollbackLiveRegionStart(): number | undefined;
+    getNativeScrollbackCommitSafeEnd?(): number | undefined;
+}
+/**
+ * Interface for components that can receive focus and display a cursor.
+ * When focused, the component should emit CURSOR_MARKER at the cursor position
+ * in its render output. TUI will find this marker and position the hardware
+ * cursor there for proper IME candidate window positioning.
+ *
+ * Components that can switch between terminal-cursor and software-cursor
+ * rendering expose `setUseTerminalCursor`; TUI keeps that mode in sync with
+ * its resolved hardware-cursor preference whenever focus or the preference
+ * changes.
+ */
+export interface Focusable {
+    /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
+    focused: boolean;
+    /** Set by TUI when hardware cursor rendering is enabled or disabled. */
+    setUseTerminalCursor?(useTerminalCursor: boolean): void;
+}
+/** Options for scheduling a TUI render. */
+export interface RenderRequestOptions {
+    /** Clear terminal scrollback for intentional transcript replacement. */
+    clearScrollback?: boolean;
+    /**
+     * Bypass the unknown-Windows-viewport deferral for this render so the
+     * caller's intentional live UI mutation reaches the terminal even when
+     * `Terminal#isNativeViewportAtBottom()` cannot answer.
+     *
+     * Use only for renders driven by direct user interaction (autocomplete
+     * updates, IME, etc.). Any background/offscreen transcript change that
+     * coalesces into the same frame WILL also bypass the deferral and reach
+     * native scrollback — that is the trade-off, and the reason ordinary
+     * `requestRender()` calls must continue to omit this flag.
+     */
+    allowUnknownViewportMutation?: boolean;
+}
+/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
+export interface NativeScrollbackRefreshOptions {
+    allowUnknownViewport?: boolean;
+}
+/** Type guard to check if a component implements Focusable */
+export declare function isFocusable(component: Component | null): component is Component & Focusable;
+/**
+ * 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 declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
+export { visibleWidth };
+/**
+ * Anchor position for overlays
+ */
+export type OverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+/**
+ * Margin configuration for overlays
+ */
+export interface OverlayMargin {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Value that can be absolute (number) or percentage (string like "50%") */
+export type SizeValue = number | `${number}%`;
+/**
+ * Options for overlay positioning and sizing.
+ * Values can be absolute numbers or percentage strings (e.g., "50%").
+ */
+export interface OverlayOptions {
+    /** Width in columns, or percentage of terminal width (e.g., "50%") */
+    width?: SizeValue;
+    /** Minimum width in columns */
+    minWidth?: number;
+    /** Maximum height in rows, or percentage of terminal height (e.g., "50%") */
+    maxHeight?: SizeValue;
+    /** Anchor point for positioning (default: 'center') */
+    anchor?: OverlayAnchor;
+    /** Horizontal offset from anchor position (positive = right) */
+    offsetX?: number;
+    /** Vertical offset from anchor position (positive = down) */
+    offsetY?: number;
+    /** Row position: absolute number, or percentage (e.g., "25%" = 25% from top) */
+    row?: SizeValue;
+    /** Column position: absolute number, or percentage (e.g., "50%" = centered horizontally) */
+    col?: SizeValue;
+    /** Margin from terminal edges. Number applies to all sides. */
+    margin?: OverlayMargin | number;
+    /**
+     * Control overlay visibility based on terminal dimensions.
+     * If provided, overlay is only rendered when this returns true.
+     * Called each render cycle with current terminal dimensions.
+     */
+    visible?: (termWidth: number, termHeight: number) => boolean;
+}
+/**
+ * Handle returned by showOverlay for controlling the overlay
+ */
+export interface OverlayHandle {
+    /** Permanently remove the overlay (cannot be shown again) */
+    hide(): void;
+    /** Temporarily hide or show the overlay */
+    setHidden(hidden: boolean): void;
+    /** Check if overlay is temporarily hidden */
+    isHidden(): boolean;
+}
+/**
+ * Container - a component that contains other components
+ */
+export declare class Container implements Component {
+    children: Component[];
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/**
+ * TUI - Main class for managing terminal UI with differential rendering
+ */
+export declare class TUI extends Container {
+    #private;
+    terminal: Terminal;
+    /** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
+    onDebug?: () => void;
+    overlayStack: {
+        component: Component;
+        options?: OverlayOptions;
+        preFocus: Component | null;
+        hidden: boolean;
+    }[];
+    constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
+    render(width: number): string[];
+    get fullRedraws(): number;
+    /** Shared budget that caps how many inline images render as live graphics. */
+    get imageBudget(): ImageBudget;
+    /**
+     * Set how many inline images stay live graphics before older ones fall back
+     * to text (`0` disables the cap). Older images are hidden via a graphics purge
+     * plus a full redraw on the frame after a new image exceeds the cap.
+     */
+    setMaxInlineImages(cap: number): void;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    /**
+     * 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: boolean): void;
+    /**
+     * Whether DEC 2026 synchronized-output wrappers are currently emitted around
+     * paints. Starts from conservative terminal/env detection and is force-disabled
+     * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
+     */
+    get synchronizedOutput(): boolean;
+    /**
+     * When enabled, live render frames rebuild native scrollback on offscreen and
+     * structural changes even when the viewport position is unobservable (POSIX,
+     * where `isNativeViewportAtBottom()` is `undefined`), instead of deferring to a
+     * non-destructive repaint. This trades the anti-yank guarantee for a clean,
+     * duplicate-free history and is meant for windows where output above the fold
+     * is actively re-rendering — e.g. a tool whose result is still streaming and
+     * re-laying-out rows that have already scrolled into history. A terminal that
+     * reports a *known*-scrolled viewport still defers, as does native Windows
+     * (the viewport is never observable there and ConPTY hosts erase host
+     * scrollback on ED3 — #1635/#1746); only the unknown POSIX case is forced to
+     * rebuild. POSIX hosts known to disturb scrolled readers on xterm ED3
+     * (`CSI 3 J`, erase saved lines) also defer the eager opt-in; checkpoint
+     * rebuilds are unaffected.
+     *
+     * Disabling stays active through one already-requested frame: the event batch
+     * that ends a foreground stream both removes its UI rows (loader/status
+     * teardown — a shrink) and clears this flag before the throttled render timer
+     * fires. If the flag dropped immediately, that teardown frame would hit the
+     * ED3-risk idle deferral and freeze on screen (stale spinner) until the next
+     * keystroke. When no render is pending, disable immediately so a later
+     * unrelated content mutation does not inherit foreground-stream privileges.
+     */
+    setEagerNativeScrollbackRebuild(enabled: boolean): void;
+    setFocus(component: Component | null): void;
+    /**
+     * Show an overlay component with configurable positioning and sizing.
+     * Returns a handle to control the overlay's visibility.
+     */
+    showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+    /** Hide the topmost overlay and restore previous focus. */
+    hideOverlay(): void;
+    /** Check if there are any visible overlays */
+    hasOverlay(): boolean;
+    invalidate(): void;
+    start(): void;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    stop(): void;
+    /**
+     * Rebuild native terminal scrollback if live rendering deferred a history rewrite.
+     * Callers should only invoke this at checkpoints where the user is expected to be
+     * at the terminal bottom, such as after submitting a new prompt.
+     */
+    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
+    /**
+     * Force an immediate full replay of the current frame, including native
+     * scrollback. This is the keyboard-accessible equivalent of the resize reset:
+     * no queued diff frame or terminal scrollback probe can downgrade it to a
+     * viewport-only repaint.
+     */
+    resetDisplay(): void;
+    requestRender(force?: boolean, options?: RenderRequestOptions): void;
+}