@linxiraos/pi-tui 1.0.4 → 1.0.6

package/dist/types/terminal.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Split `data` into chunks whose encoded UTF-8 byte length is no greater than
+ * `maxChunkBytes`, preferring a line boundary (`\n`) as the cut point so
+ * escape sequences (which never contain `\n`) stay intact. The TUI's
+ * full-paint buffers are line-structured (`buffer += "\r\n"` between rows),
+ * so a newline almost always exists within the window. The fallback for a
+ * buffer with no newline in range is a hard cut at the last UTF-8 code-point
+ * boundary that still fits — the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a
+ * buffer the renderer effectively never produces.
+ *
+ * UTF-16 code units are walked manually rather than measuring with
+ * `Buffer.byteLength` per slice candidate: each code unit's UTF-8 width is
+ * known from its value (BMP `<0x80` → 1, `<0x800` → 2, surrogate pair → 4
+ * bytes across two units, other BMP → 3), and surrogate pairs are kept
+ * together so the chunker never splits a non-BMP character.
+ *
+ * Exported for unit testing of the chunking contract; `#safeWrite` is the
+ * sole production caller.
+ */
+export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
+/**
+ * Turns an unbounded, never-draining stdout writable buffer into a bounded
+ * disconnect signal.
+ *
+ * `process.stdout.write()` returns `false` once its buffer exceeds the stream
+ * high-water mark; the bytes stay queued and are only freed when the consumer
+ * drains (the `drain` event). While the consumer keeps up, writes are accepted
+ * and nothing accumulates. When it stalls, every subsequent write piles onto
+ * the buffer — a stalled-but-alive PTY reader never throws, so the write path
+ * has no other signal that output is going nowhere. This guard sums the bytes
+ * queued since backpressure began and reports when that backlog crosses the
+ * cap, at which point the caller treats the terminal as disconnected.
+ *
+ * Exported for unit testing; `ProcessTerminal` is the sole production user.
+ */
+export declare class OutputBacklogGuard {
+    #private;
+    private readonly capBytes;
+    constructor(capBytes?: number);
+    /** True once a refused write started a backlog that has not yet drained. */
+    get tracking(): boolean;
+    /**
+     * Record one `stdout.write()`: `accepted` is that call's return value and
+     * `bytes` its encoded size. Returns true when the pending backlog now
+     * exceeds the cap and the terminal should be treated as disconnected.
+     */
+    record(accepted: boolean, bytes: number): boolean;
+    /** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+    reset(): void;
+}
+/** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
+export declare function setAltScreenActive(active: boolean): void;
+/**
+ * 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";
+/** Identity of an accepted explicit terminal appearance refresh request. */
+export type TerminalAppearanceRequestToken = number;
+export interface Terminal {
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => 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;
+    get kittyEnableSequence(): string | null;
+    readonly keyboardEnhancementEnterSequence?: string | null;
+    readonly keyboardEnhancementExitSequence?: string | null;
+    moveBy(lines: number): void;
+    hideCursor(force?: boolean): void;
+    showCursor(force?: boolean): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    /**
+     * 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.
+     * Subscribers registered after detection are invoked immediately with the
+     * already-detected appearance so late subscribers never miss it.
+     */
+    onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;
+    /**
+     * Register a callback fired for every valid OSC 11 appearance report,
+     * including reports whose classification matches the current appearance.
+     * Unlike onAppearanceChange, this does not replay an earlier report.
+     * Optional so custom Terminals built against older pi-tui versions keep working.
+     */
+    onAppearanceReport?(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): (() => void) | void;
+    /**
+     * Start a bounded OSC 11 background-color refresh cycle, driving appearance
+     * callbacks through the same parse/dedup pipeline used at startup and on Mode
+     * 2031 notifications. Direct terminals need one query; tmux needs a
+     * passthrough query to update its cache followed by one delayed direct cache
+     * read. Invoked on the user's explicit display-reset gesture so terminals
+     * without end-to-end Mode 2031 notifications pick up a light/dark switch
+     * without a restart. No periodic probes are armed.
+     *
+     * A caller-provided token must be propagated unchanged to callbacks and
+     * returned when the request is accepted. This lets callers establish ownership
+     * before implementations synchronously dispatch a cached response. Optional so
+     * custom Terminals built against older pi-tui versions keep working.
+     */
+    refreshAppearance?(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | 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. `confirmed` is false when the terminal answered the DA1
+     * sentinel without answering DECRQM, which proves only that querying support
+     * is unavailable — not that the private mode itself is unsupported.
+     */
+    onPrivateModeReport?(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+}
+/**
+ * True when stdout flows through a ConPTY pseudo-console (native win32, or
+ * Linux running under WSL where stdout still crosses into ConPTY at the
+ * `wslhost` boundary). ConPTY hosts share the per-WriteFile viewport-tracking
+ * quirks documented above and on {@link MAX_CONPTY_WRITE_CHUNK_BYTES}, so both
+ * `#safeWrite` and the renderer's post-big-paint settle gate hang off this
+ * single predicate.
+ */
+export declare function isConPTYHosted(): boolean;
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export declare class ProcessTerminal implements Terminal {
+    #private;
+    get kittyProtocolActive(): boolean;
+    get kittyEnableSequence(): string | null;
+    get keyboardEnhancementEnterSequence(): string | null;
+    get keyboardEnhancementExitSequence(): string | null;
+    get appearance(): TerminalAppearance | undefined;
+    onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;
+    onAppearanceReport(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): () => void;
+    /**
+     * Re-query the terminal background through the startup DA1-sentinel FIFO,
+     * pending/queued gating, parsing, dedup, and appearance callbacks. Inside
+     * tmux, only this explicit path first passes an OSC 11 query to the outer
+     * terminal, waits briefly for tmux to consume the response into its cache,
+     * then reads that cache with a direct query. The outer query deliberately has
+     * no DA1 sentinel: multiplexers can decode a fragmented DA1 response as a key
+     * sequence and leak the remaining bytes into the editor. Startup and Mode 2031
+     * probes remain direct. Suppressed while inactive, headless, or after teardown.
+     */
+    refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
+    onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => 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(force?: boolean): void;
+    showCursor(force?: boolean): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}

package/dist/types/tmux.d.ts

@@ -0,0 +1,6 @@
+/** Whether the process is running inside a tmux session. */
+export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export declare function wrapTmuxPassthrough(payload: string): string;
+/** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
+export declare function wrapTmuxPassthroughIfNeeded(payload: string, env?: NodeJS.ProcessEnv): string;

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,480 @@
+import { ImageBudget } from "./components/image.js";
+import { type Terminal } from "./terminal.js";
+import { visibleWidth } from "./utils.js";
+type InputListenerResult = {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+type InputListener = (data: string) => InputListenerResult;
+type StartListener = () => void;
+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;
+}
+export interface TUIStartOptions {
+    /** Clear saved native scrollback before the first paint. */
+    clearScrollback?: boolean;
+}
+/**
+ * Component interface - all components must implement this
+ *
+ * Render contract: the returned array (and its rows) belongs to the component.
+ * Callers MUST NOT mutate it — components are allowed to return a cached array
+ * and will return the exact same reference for as long as their rendered
+ * content is unchanged. Conversely, a component MUST return a fresh array
+ * reference whenever its content changed; reference equality across two
+ * render() calls is the engine's proof that the rows are byte-identical
+ * (containers memoize their concatenation on it, and the TUI derives the
+ * frame's stable prefix from it). A component that mutates a previously
+ * returned array in place must implement {@link RenderStablePrefix} to declare
+ * which leading rows survived.
+ */
+export interface Component {
+    /**
+     * Render the component to an array of physical rows at the given width.
+     * The result is component-owned and `readonly` to the caller; an unchanged
+     * component may (and should) return the same array reference it returned
+     * last time.
+     */
+    render(width: number): readonly 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;
+    /**
+     * Optional hook to invalidate any cached rendering state.
+     * Called when theme changes or when component needs to re-render from scratch.
+     */
+    invalidate?(): void;
+    /**
+     * Optional hook to set whether this component ignores tight layout mode.
+     */
+    setIgnoreTight?(ignore: boolean): any;
+    /**
+     * Optional teardown. Called when the component is permanently removed from
+     * the live tree (e.g. a transcript reset). Release timers, intervals, and
+     * subscriptions here. Must be idempotent. Containers propagate dispose to
+     * their children; leaf components without resources may omit it.
+     */
+    dispose?(): void;
+}
+/** Lets an overlay root delegate keyboard focus to components it owns. */
+export interface OverlayFocusOwner {
+    /** Returns true when `component` is a focus target inside this overlay. */
+    ownsOverlayFocusTarget(component: Component): boolean;
+}
+/**
+ * Component seam for append-only native-scrollback commits. A component whose
+ * rendered rows can still change reports, after each render, the local line
+ * index where that mutable suffix begins. Rows above the boundary are declared
+ * FINAL — byte-stable at the current width for the component's lifetime — and
+ * commit to native scrollback as exact, audited content. Rows at/after the
+ * boundary repaint in place inside the visible window; when they scroll above
+ * the window top they normally commit as frozen visual snapshots.
+ *
+ * A viewport-pinned region opts out of those mutable snapshot commits. Its
+ * offscreen mutable rows are virtually clipped until the boundary advances;
+ * use this for fixed-height dashboards whose frames replace each other rather
+ * than append. A root that reports no seam commits everything that scrolls as
+ * final (shell semantics).
+ *
+ * When several root children report a seam in the same frame, the topmost one
+ * defines the boundary and pinning policy: commits are prefix-only, so
+ * everything below the first seam is already excluded.
+ */
+export interface NativeScrollbackLiveRegion {
+    getNativeScrollbackLiveRegionStart(): number | undefined;
+    /** Keeps the mutable suffix viewport-local instead of recording frozen snapshots. */
+    isNativeScrollbackLiveRegionPinned?(): boolean;
+}
+export interface NativeScrollbackCommittedRows {
+    setNativeScrollbackCommittedRows(rows: number): void;
+}
+/**
+ * Width-independent source boundary for multiplexer resize epochs. Capture
+ * reads the last rendered source state; resolve maps that same logical boundary
+ * into the most recent render's physical rows at its new width. The current
+ * boundary identifies the source tail after updates queued during the resize.
+ */
+export interface NativeScrollbackWidthEpoch {
+    captureNativeScrollbackWidthEpoch(): unknown;
+    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
+    getNativeScrollbackWidthEpochRows(): number | undefined;
+    /** False when updates can insert before captured trailing rows. */
+    isNativeScrollbackWidthEpochAppendOnly?(boundary: unknown): boolean;
+    /** Changes when child structure mutates independently of width reflow. */
+    getNativeScrollbackWidthEpochRevision?(): number;
+}
+/**
+ * A component that discards rows after they enter native scrollback implements
+ * this hook so a destructive full replay can rehydrate its complete frame.
+ */
+export interface NativeScrollbackReplay {
+    prepareNativeScrollbackReplay(): void;
+}
+/**
+ * Opt-in stability report for components that mutate their returned render
+ * array in place across frames (instead of returning a fresh array per
+ * change). The engine reads it right after the component's `render()` returns:
+ * the report counts the leading rows of the just-returned array that are
+ * byte-identical to the array state the reader last observed. The engine uses
+ * it to reuse the composed frame's prefix — skipping marker extraction, line
+ * preparation, and the committed-prefix audit for those rows.
+ *
+ * Contract:
+ * - Reading CONSUMES the report: it re-bases the baseline to the current
+ *   array state. The accumulated count therefore covers every render since
+ *   the previous read, so out-of-band `render()` calls between engine frames
+ *   (an exporter walking the tree) can only lower the report, never inflate
+ *   it past what the engine actually has.
+ * - An implementer that cannot prove stability for a frame must lower the
+ *   accumulated count to 0 for that render.
+ * - Rows at or beyond the report may have been mutated in place; rows before
+ *   it must be the identical string values at the identical indices.
+ */
+export interface RenderStablePrefix {
+    getRenderStablePrefixRows(): number;
+}
+/**
+ * Opt-in fast path for composing only the visible tail of a tall component
+ * during a terminal resize. A drag emits a SIGWINCH burst, and the width
+ * changes on every event: a full compose re-lays-out (and, for markdown,
+ * re-lexes) the entire transcript per event — O(history) work that is
+ * discarded the instant the next event arrives. While the resize is in flight
+ * the engine paints only the viewport, so it asks each tall root child for at
+ * most `maxRows` rows from the bottom of its render at `width` and skips
+ * composing everything above the fold. The authoritative full paint replays
+ * once the drag settles (see {@link TUI} resize handling).
+ *
+ * Contract:
+ * - Returns the BOTTOM rows of the component's full render at `width`, in
+ *   top-to-bottom order, capped at `maxRows` (fewer when the component is
+ *   shorter). The rows MUST be byte-identical to the corresponding tail of
+ *   what `render(width)` would have returned, modulo a one-row separator at
+ *   the very top edge (a transient frame the settle paint overwrites).
+ * - MUST NOT mutate any persistent full-compose state: the next `render()`
+ *   (the settle paint) has to reconcile exactly as if the tail render never
+ *   happened. Warming pure per-width render caches is fine and desirable.
+ */
+export interface ViewportTailProvider {
+    renderViewportTail(width: number, maxRows: number): readonly string[];
+}
+/**
+ * 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;
+}
+/** 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;
+    /**
+     * Borrow the terminal's alternate screen buffer for this overlay's lifetime
+     * (vim/less idiom). While the topmost visible overlay sets this, the engine
+     * paints only the modal on the alt screen and emits no ED3 / scrollback
+     * bytes, so the transcript on the normal screen stays untouched and is not
+     * scrollable behind the modal. Defaults off — all other overlays are
+     * unchanged and still draw over the transcript on the normal screen.
+     */
+    fullscreen?: boolean;
+    /**
+     * Enable terminal mouse reporting while fullscreen. Defaults on; disable it
+     * when native terminal text selection takes precedence over pointer events.
+     */
+    mouseTracking?: 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, NativeScrollbackCommittedRows, NativeScrollbackReplay, NativeScrollbackWidthEpoch {
+    #private;
+    children: Component[];
+    setIgnoreTight(ignore: boolean): this;
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    /** Dispose every child, then detach it from this container. */
+    disposeChildren(): void;
+    invalidate(): void;
+    /**
+     * Propagate teardown to children. Call when the container's children are
+     * being permanently discarded (not when they are detached for reuse — use
+     * {@link clear} for that). Idempotent per child via each child's own dispose.
+     */
+    dispose(): void;
+    /**
+     * Split the committed prefix from the container's most recently rendered
+     * rows across its children. The memoized child arrays are the exact geometry
+     * that produced that frame; when the child list was invalidated or rebuilt,
+     * there is no safe old-to-new coordinate mapping, so propagation waits for
+     * the next render/post-emit publication.
+     */
+    setNativeScrollbackCommittedRows(rows: number): void;
+    /** Recursively discard layout locks that are meaningful only to the old tape. */
+    prepareNativeScrollbackReplay(): void;
+    captureNativeScrollbackWidthEpoch(): unknown;
+    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
+    getNativeScrollbackWidthEpochRows(): number | undefined;
+    isNativeScrollbackWidthEpochAppendOnly(boundary: unknown): boolean;
+    getNativeScrollbackWidthEpochRevision(): number;
+    render(width: number): readonly string[];
+}
+/**
+ * Merge runs of byte-adjacent SGR sequences (`CSI [0-9;:]* m`) into one. Only
+ * CSI-SGR sequences are touched; text, cursor moves, OSC, hyperlinks and image
+ * payloads pass through verbatim. Returns the original reference when nothing
+ * merges, so SGR-light lines incur only a single `indexOf` scan.
+ */
+export declare function coalesceAdjacentSgr(line: string): string;
+/**
+ * Decide whether `frame` still aligns with the committed prefix, and where to
+ * re-anchor the commit index when it does not. Returns the resync row index,
+ * or -1 when no resync is needed.
+ *
+ * Zones (verifiedTo ≤ finalTo ≤ prefix.length):
+ *   [0, verifiedTo)         VERIFIED exact rows — sampled with tolerance.
+ *   [verifiedTo, finalTo)   NEWLY-FINAL rows — frozen visual snapshots whose
+ *       source just became declared-final (the block finalized / a barrier
+ *       cleared). Hard-scanned in FULL with no tolerance: any content change
+ *       (a pending header settling, a preview replaced by its result, a tail
+ *       shifting up after a barrier removal) re-anchors so the engine can
+ *       erase-and-replay history with the final content exactly once (or, on
+ *       ED3-unsafe multiplexers, recommit it below the frozen snapshot —
+ *       duplication, never loss) instead of committing it nowhere and
+ *       painting it nowhere.
+ *   [finalTo, prefix.length) FROZEN visual snapshots of still-live rows —
+ *       exempt: their drift is expected (a collapsing preview, a ticking
+ *       progress tree) and must never spray re-anchors mid-run.
+ *
+ * The verified zone's sampled check exploits the asymmetry between the two
+ * mutation classes: an in-place edit/restyle disturbs only the touched rows
+ * (alignment below stays intact; the stale copy in history is the accepted
+ * artifact), while an insertion/deletion shifts EVERY row below it. Up to 8
+ * non-blank rows within the last 24 verified rows are compared SGR-stripped
+ * (theme changes stay quiet), tolerating a SINGLE mismatch. The tolerance is
+ * load-bearing for roots that report NO seam: an animated row already in
+ * history would otherwise re-anchor on every glyph tick.
+ *
+ * Highly repetitive tails (identical filler rows) can mask a shift in the tail
+ * sample, in which case the skipped rows are content-identical to the committed
+ * ones — observationally harmless. Exported for the render-stress harness, whose
+ * shadow commit ledger must mirror the engine's law exactly.
+ */
+export declare function findCommittedPrefixResync(frame: readonly string[], prefix: readonly string[], verifiedTo?: number, finalTo?: number): number;
+/**
+ * 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);
+    captureNativeScrollbackWidthEpoch(): unknown;
+    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
+    getNativeScrollbackWidthEpochRows(): number | undefined;
+    render(width: number): readonly string[];
+    get fullRedraws(): number;
+    /**
+     * Transient viewport-only paints emitted by the non-multiplexer resize fast
+     * path. These never touch native scrollback or the commit ledger, so they
+     * are counted apart from {@link fullRedraws}.
+     */
+    get resizeViewportPaints(): number;
+    /** Whether a non-multiplexer resize drag is currently in flight. */
+    get resizeViewportActive(): boolean;
+    /** 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;
+    /** Delete every tracked Kitty image from the terminal graphics store. */
+    clearInlineImages(): void;
+    /**
+     * Get whether scrollback divergence rebuild is enabled.
+     */
+    getScrollbackRebuild(): boolean;
+    /**
+     * Enable or disable scrollback divergence rebuild (default off).
+     * When enabled, the engine will erase and replay the terminal's
+     * scrollback (using ED3 / alt buffer / scrollback replay) to avoid
+     * duplicate blocks when a block's final form replaces its live preview.
+     */
+    setScrollbackRebuild(enabled: boolean): void;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    /**
+     * Whether DEC 2026 synchronized-output wrappers are currently emitted around
+     * paints. Starts from conservative terminal/env detection and is reconciled at
+     * runtime against the terminal's DECRQM mode-2026 report — enabled on a
+     * positive report, disabled on a negative one.
+     */
+    get synchronizedOutput(): boolean;
+    setFocus(component: Component | null): void;
+    /** Component currently receiving keyboard input, if any. */
+    getFocused(): Component | null;
+    /**
+     * 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(options?: TUIStartOptions): void;
+    addStartListener(listener: StartListener): () => void;
+    addInputListener(listener: InputListener): () => void;
+    removeInputListener(listener: InputListener): void;
+    stop(): void;
+    /**
+     * 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.
+     *
+     * Invalidates every component first so the replay reflects current state. A
+     * geometry-driven reset thaws frozen scrollback snapshots implicitly (the new
+     * width misses every cached snapshot), but a same-width reset would otherwise
+     * replay stale snapshots — leaving host-frozen blocks (e.g. a transcript whose
+     * committed rows are immutable on ED3-risk terminals) showing pre-mutation
+     * content. Invalidation is the generic signal those containers use to retire
+     * their snapshots, which is exactly what a user-driven display reset wants.
+     */
+    resetDisplay(): void;
+    requestRender(force?: boolean, options?: RenderRequestOptions): void;
+    /**
+     * Opt `component` into subtree-only renders when input leaves focus stable.
+     *
+     * The host must explicitly request renders for every sibling mutated by the
+     * component's input callbacks. Components without this opt-in retain the
+     * legacy full-root render after input.
+     */
+    enableScopedInputRender(component: Component): void;
+    /**
+     * Schedule a render on behalf of `component` after a self-contained change
+     * (spinner frame, blink) that cannot have affected any other component.
+     *
+     * When every request since the last frame is component-scoped and the
+     * frame is otherwise quiet — no resize or geometry change, no overlays, no
+     * live inline images, no forced repaint, unchanged root child list — the
+     * next compose re-renders only the root subtrees containing the requesting
+     * components and reuses the previous frame's rows (and seam reports) for
+     * every other root child, skipping the full component-tree walk that makes
+     * long transcripts expensive to repaint at animation rate. Any concurrent
+     * full request or unsafe condition downgrades the frame to a normal full
+     * compose, so this is never less correct than `requestRender()` — only
+     * cheaper.
+     */
+    requestComponentRender(component: Component): void;
+    /**
+     * Rewrite a quiet, visible component segment directly.
+     *
+     * Loader-style animation changes one already-positioned segment at a fixed
+     * size. When the current frame geometry is still valid, rewrite just those
+     * rows and update the diff baseline instead of scheduling a full render
+     * cycle. Unsafe states fall back to `requestComponentRender()`, preserving
+     * the ordinary renderer as the correctness path.
+     */
+    requestDirectWrite(component: Component): void;
+}