@termuijs/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1081 @@
+/**
+ * Supported color depth levels, ordered from least to most capable.
+ */
+declare enum ColorDepth {
+    /** No color support (e.g. NO_COLOR env var set) */
+    None = 0,
+    /** 4-bit, 16 colors (standard ANSI) */
+    Basic = 4,
+    /** 8-bit, 256 colors */
+    Ansi256 = 8,
+    /** 24-bit, 16.7 million colors (true color) */
+    TrueColor = 24
+}
+/**
+ * Represents a color value in the terminal.
+ * Supports named ANSI colors, 256-color palette, and RGB true color.
+ */
+type Color = {
+    type: 'named';
+    name: NamedColor;
+} | {
+    type: 'ansi256';
+    code: number;
+} | {
+    type: 'rgb';
+    r: number;
+    g: number;
+    b: number;
+} | {
+    type: 'hex';
+    hex: string;
+} | {
+    type: 'none';
+};
+type NamedColor = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white' | 'brightBlack' | 'brightRed' | 'brightGreen' | 'brightYellow' | 'brightBlue' | 'brightMagenta' | 'brightCyan' | 'brightWhite';
+/**
+ * Parse a color string into a Color object.
+ *
+ * Accepts:
+ * - Named colors: 'red', 'brightBlue', etc.
+ * - Hex: '#ff0000', '#f00'
+ * - RGB: 'rgb(255, 0, 0)'
+ * - ANSI 256: 'ansi256(196)'
+ */
+declare function parseColor(input: string): Color;
+/**
+ * Convert any Color to its RGB representation.
+ */
+declare function colorToRgb(color: Color): [number, number, number];
+/**
+ * Detect the terminal's color depth from environment variables.
+ */
+declare function detectColorDepth(): ColorDepth;
+/**
+ * Generate the ANSI escape codes for a foreground color at the given depth.
+ */
+declare function colorToAnsiFg(color: Color, depth: ColorDepth): string;
+/**
+ * Generate the ANSI escape codes for a background color at the given depth.
+ */
+declare function colorToAnsiBg(color: Color, depth: ColorDepth): string;
+
+interface TerminalOptions {
+    /** Override stdout stream (useful for testing) */
+    stdout?: NodeJS.WriteStream;
+    /** Override stdin stream (useful for testing) */
+    stdin?: NodeJS.ReadStream;
+    /** Force a specific color depth */
+    colorDepth?: ColorDepth;
+    /** Enable mouse tracking */
+    mouse?: boolean;
+    /** Use alternate screen buffer for full-screen apps */
+    altScreen?: boolean;
+}
+/**
+ * Terminal adapter — wraps process.stdout/stdin and manages
+ * terminal state (raw mode, cursor, mouse, alternate screen).
+ */
+declare class Terminal {
+    readonly stdout: NodeJS.WriteStream;
+    readonly stdin: NodeJS.ReadStream;
+    readonly colorDepth: ColorDepth;
+    private _cols;
+    private _rows;
+    private _isRawMode;
+    private _isAltScreen;
+    private _isMouseEnabled;
+    private _resizeHandlers;
+    private _cleanupHandlers;
+    private _originalRawMode;
+    constructor(options?: TerminalOptions);
+    /** Current terminal width in columns */
+    get cols(): number;
+    /** Current terminal height in rows */
+    get rows(): number;
+    /** Whether stdin is a TTY (interactive) */
+    isInteractive(): boolean;
+    /** Whether the terminal supports raw mode */
+    supportsRawMode(): boolean;
+    enterRawMode(): void;
+    exitRawMode(): void;
+    enterAltScreen(): void;
+    exitAltScreen(): void;
+    enableMouse(): void;
+    disableMouse(): void;
+    hideCursor(): void;
+    showCursor(): void;
+    write(data: string): void;
+    onResize(handler: (cols: number, rows: number) => void): () => void;
+    /**
+     * Restore terminal to its original state.
+     * Called automatically on SIGINT, SIGTERM, process exit.
+     */
+    restore(): void;
+    /**
+     * Register a custom cleanup handler that runs on terminal restore.
+     */
+    onCleanup(handler: () => void): void;
+    private _setupCleanup;
+}
+
+/**
+ * A single cell in the terminal grid.
+ */
+interface Cell {
+    /** The character displayed (single grapheme cluster) */
+    char: string;
+    /** Foreground color */
+    fg: Color;
+    /** Background color */
+    bg: Color;
+    /** Bold text */
+    bold: boolean;
+    /** Italic text */
+    italic: boolean;
+    /** Underline text */
+    underline: boolean;
+    /** Dim text */
+    dim: boolean;
+    /** Strikethrough text */
+    strikethrough: boolean;
+    /** Inverse colors */
+    inverse: boolean;
+    /**
+     * Visual width of this cell.
+     * - 1 for normal characters
+     * - 2 for wide chars (CJK/emoji) — the next cell is a "continuation" cell
+     * - 0 for continuation cells (second half of a wide char)
+     */
+    width: number;
+}
+/** Create a blank cell with default attributes */
+declare function emptyCell(): Cell;
+/** Check if two cells are visually identical */
+declare function cellsEqual(a: Cell, b: Cell): boolean;
+/**
+ * Double-buffered 2D cell grid for the terminal.
+ *
+ * - `front` = what's currently displayed on screen
+ * - `back` = what we're building for the next frame
+ *
+ * After rendering, the renderer diffs `front` vs `back` and only emits
+ * changes, then swaps the buffers.
+ */
+declare class Screen {
+    private _cols;
+    private _rows;
+    front: Cell[][];
+    back: Cell[][];
+    /**
+     * Stack of clipping regions. When non-empty, setCell/writeString
+     * only write to cells within the topmost clip rectangle.
+     */
+    private _clipStack;
+    constructor(cols: number, rows: number);
+    get cols(): number;
+    get rows(): number;
+    /**
+     * Push a clipping region onto the stack.
+     * All subsequent setCell/writeString calls will be constrained
+     * to cells within this rectangle. Clips are intersected with
+     * any parent clip already on the stack (nested clipping).
+     */
+    pushClip(region: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Pop the most recent clipping region from the stack.
+     */
+    popClip(): void;
+    /**
+     * Get the current active clip region, or null if no clip is active.
+     */
+    get activeClip(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Write a cell to the back buffer at position (col, row).
+     */
+    setCell(col: number, row: number, cell: Partial<Cell>): void;
+    /**
+     * Write a string to the back buffer starting at (col, row).
+     * Applies the provided style attributes to each character.
+     */
+    writeString(col: number, row: number, str: string, style?: Partial<Omit<Cell, 'char' | 'width'>>): void;
+    /**
+     * Clear the back buffer to all empty cells.
+     */
+    clear(): void;
+    /**
+     * Swap front and back buffers. Called after rendering diffs.
+     */
+    swap(): void;
+    /**
+     * Resize the screen. Clears both buffers.
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Clear the front buffer (marks everything as "needs redraw").
+     */
+    invalidate(): void;
+    private _createGrid;
+    private _isWideCodePoint;
+}
+
+/**
+ * Differential renderer — compares front/back screen buffers and
+ * outputs only the changed cells. Uses synchronized output (CSI 2026)
+ * for atomic, flicker-free updates.
+ */
+declare class Renderer {
+    private _terminal;
+    private _screen;
+    private _fps;
+    private _frameTimer;
+    private _renderRequested;
+    private _colorDepth;
+    constructor(terminal: Terminal, screen: Screen, fps?: number);
+    /** Change the rendering frame rate cap */
+    setFPS(fps: number): void;
+    /** Start the render loop */
+    start(): void;
+    /** Stop the render loop */
+    stop(): void;
+    /** Request a render on the next frame */
+    requestFrame(): void;
+    /** Force an immediate render (bypass frame rate) */
+    renderNow(): void;
+    /**
+     * Full-screen clear and redraw (first render or after resize).
+     */
+    fullRender(): void;
+    /**
+     * Core diff and flush: compare front vs back buffer,
+     * emit only changed cells.
+     */
+    private _flush;
+    /**
+     * Generate the ANSI escape sequence to render a single cell.
+     */
+    private _renderCell;
+}
+
+/**
+ * A computed rectangle with position and size.
+ */
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A 2D size.
+ */
+interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * Create an empty rect at origin.
+ */
+declare function emptyRect(): Rect;
+/**
+ * Check if a point is inside a rect.
+ */
+declare function containsPoint(rect: Rect, x: number, y: number): boolean;
+/**
+ * Shrink a rect by the given edges (inset).
+ */
+declare function shrinkRect(rect: Rect, top: number, right: number, bottom: number, left: number): Rect;
+/**
+ * Intersect two rects. Returns the overlapping region, or null if disjoint.
+ */
+declare function intersectRect(a: Rect, b: Rect): Rect | null;
+/**
+ * Union two rects into the smallest bounding rect that contains both.
+ */
+declare function unionRect(a: Rect, b: Rect): Rect;
+
+/**
+ * A rendering layer. Each layer has its own cell grid and z-index.
+ * Higher z-index layers render on top of lower ones during compositing.
+ */
+interface Layer {
+    /** Unique identifier for this layer */
+    id: string;
+    /** Stacking order — higher renders on top */
+    zIndex: number;
+    /** Cell grid (same dimensions as Screen) */
+    cells: Cell[][];
+    /** Whether this layer is visible */
+    visible: boolean;
+    /** Bounding box of cells written since last clear (null = nothing dirty) */
+    dirtyRegion: Rect | null;
+}
+/**
+ * Manages multiple rendering layers for overlay support.
+ *
+ * The base layer (z=0) is the primary widget layer — always opaque.
+ * Overlay layers (z>0) support transparency: only cells explicitly
+ * written to them overwrite the base layer during compositing.
+ *
+ * Typical z-index values:
+ * - 0:    Base widget layer
+ * - 10:   Dropdown menus
+ * - 100:  Modal dialogs
+ * - 1000: Toasts / notifications
+ */
+declare class LayerManager {
+    private _layers;
+    private _cols;
+    private _rows;
+    constructor(cols: number, rows: number);
+    get cols(): number;
+    get rows(): number;
+    /**
+     * Create a new overlay layer.
+     * @param id   Unique identifier (e.g. 'modal', 'select-dropdown', 'toast')
+     * @param zIndex  Stacking order (higher = rendered on top)
+     */
+    createLayer(id: string, zIndex: number): Layer;
+    /**
+     * Remove an overlay layer and clean up its resources.
+     */
+    removeLayer(id: string): void;
+    /**
+     * Get a layer by ID.
+     */
+    getLayer(id: string): Layer | undefined;
+    /**
+     * Check if a layer exists.
+     */
+    hasLayer(id: string): boolean;
+    /**
+     * Get all layers sorted by z-index (ascending).
+     */
+    getSortedLayers(): Layer[];
+    /**
+     * Write a cell to a specific layer.
+     */
+    setCell(layerId: string, col: number, row: number, cell: Partial<Cell>): void;
+    /**
+     * Write a string to a specific layer at position (col, row).
+     */
+    writeString(layerId: string, col: number, row: number, str: string, style?: Partial<Omit<Cell, 'char' | 'width'>>): void;
+    /**
+     * Clear all cells in a specific layer.
+     */
+    clearLayer(id: string): void;
+    /**
+     * Clear all overlay layers.
+     */
+    clearAll(): void;
+    /**
+     * Composite all overlay layers onto the Screen's back buffer.
+     * Layers are applied in z-index order (lowest first).
+     * Transparent cells (empty with no colors) are skipped.
+     */
+    composite(screen: Screen): void;
+    /**
+     * Resize all layers when the terminal is resized.
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Create an empty cell grid.
+     */
+    private _createGrid;
+    /**
+     * Expand the dirty region of a layer to include the given cell.
+     */
+    private _expandDirty;
+}
+
+/**
+ * Keyboard event emitted when a key is pressed.
+ */
+interface KeyEvent {
+    /** Human-readable key name: 'a', 'enter', 'up', 'f1', 'tab', etc. */
+    key: string;
+    /** Raw byte sequence from stdin */
+    raw: Buffer;
+    /** Ctrl modifier held */
+    ctrl: boolean;
+    /** Alt/Meta modifier held */
+    alt: boolean;
+    /** Shift modifier held */
+    shift: boolean;
+    /** The widget ID that currently has focus (target of the event) */
+    targetId?: string;
+    /** Whether propagation has been stopped */
+    _propagationStopped?: boolean;
+    /** Whether the default action has been prevented */
+    _defaultPrevented?: boolean;
+    /** Stop this event from bubbling to parent widgets */
+    stopPropagation(): void;
+    /** Prevent the default action for this event */
+    preventDefault(): void;
+}
+/**
+ * Create a KeyEvent with propagation control methods attached.
+ */
+declare function createKeyEvent(base: {
+    key: string;
+    raw: Buffer;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    targetId?: string;
+}): KeyEvent;
+/**
+ * Mouse event types.
+ */
+type MouseEventType = 'mousedown' | 'mouseup' | 'mousemove' | 'scroll';
+type MouseButton = 'left' | 'middle' | 'right' | 'none';
+/**
+ * Mouse event emitted when mouse activity is detected.
+ */
+interface MouseEvent {
+    /** x (column) position, 0-indexed */
+    x: number;
+    /** y (row) position, 0-indexed */
+    y: number;
+    /** Which mouse button */
+    button: MouseButton;
+    /** Type of mouse event */
+    type: MouseEventType;
+    /** Scroll direction (-1 = up, 1 = down) */
+    scrollDelta?: number;
+}
+/**
+ * Resize event emitted when the terminal is resized.
+ */
+interface ResizeEvent {
+    cols: number;
+    rows: number;
+}
+/**
+ * Focus event emitted when a widget gains or loses focus.
+ */
+interface FocusEvent {
+    /** Widget ID that is gaining or losing focus */
+    targetId: string;
+    /** Type of focus event */
+    type: 'focus' | 'blur';
+}
+/**
+ * Map of all event types to their data shapes.
+ */
+interface EventMap {
+    'key': KeyEvent;
+    'mouse': MouseEvent;
+    'resize': ResizeEvent;
+    'focus': FocusEvent;
+    'blur': FocusEvent;
+    'render': void;
+    'mount': void;
+    'unmount': void;
+    'tick': number;
+}
+
+/**
+ * Reads raw stdin bytes and parses them into typed KeyEvent / MouseEvent objects.
+ * Handles escape sequences, multi-byte keys, ctrl+key, and SGR mouse events.
+ */
+declare class InputParser {
+    private _events;
+    private _stdin;
+    private _handler;
+    private _escapeTimeout;
+    private _escapeBuffer;
+    constructor(stdin: NodeJS.ReadStream);
+    /** Subscribe to key events */
+    onKey(handler: (event: KeyEvent) => void): () => void;
+    /** Subscribe to mouse events */
+    onMouse(handler: (event: MouseEvent) => void): () => void;
+    /** Start listening for input */
+    start(): void;
+    /** Stop listening for input */
+    stop(): void;
+    /**
+     * Process a chunk of raw input bytes.
+     */
+    private _processInput;
+    /**
+     * Try to parse buffered escape sequence.
+     */
+    private _tryParseEscape;
+}
+
+/**
+ * Maps raw byte sequences to human-readable key names.
+ * These are standard VT100/xterm escape sequences.
+ */
+declare const ESCAPE_SEQUENCES: Record<string, string>;
+/**
+ * Maps control character codes (0x01-0x1A) to key names.
+ * Ctrl+A = 0x01, Ctrl+B = 0x02, ... Ctrl+Z = 0x1A
+ */
+declare const CTRL_KEYS: Record<number, string>;
+/**
+ * Special single-byte key codes.
+ */
+declare const SPECIAL_KEYS: Record<number, string>;
+
+/**
+ * Parse an SGR mouse event escape sequence.
+ *
+ * SGR format: ESC [ < Cb ; Cx ; Cy M  (button press)
+ *             ESC [ < Cb ; Cx ; Cy m  (button release)
+ *
+ * Where Cb encodes the button and modifiers, Cx/Cy are 1-based coordinates.
+ *
+ * @returns Parsed MouseEvent or null if not a mouse sequence.
+ */
+declare function parseMouseEvent(data: string): MouseEvent | null;
+/**
+ * Check if a string looks like it could be a mouse sequence.
+ */
+declare function isMouseSequence(data: string): boolean;
+
+/**
+ * Supported border styles.
+ */
+type BorderStyle = 'none' | 'single' | 'double' | 'round' | 'heavy' | 'dashed' | 'custom';
+/**
+ * The characters used to draw a border.
+ * Layout:
+ * ```
+ *  topLeft ─── top ─── topRight
+ *    │                    │
+ *   left     content    right
+ *    │                    │
+ *  bottomLeft ─ bottom ─ bottomRight
+ * ```
+ */
+interface BorderChars {
+    topLeft: string;
+    top: string;
+    topRight: string;
+    right: string;
+    bottomRight: string;
+    bottom: string;
+    bottomLeft: string;
+    left: string;
+}
+/** Character maps for each border style */
+declare const BORDER_CHARS: Record<Exclude<BorderStyle, 'none' | 'custom'>, BorderChars>;
+/**
+ * Get the border characters for a given style.
+ */
+declare function getBorderChars(style: BorderStyle, customChars?: Partial<BorderChars>): BorderChars | null;
+/**
+ * Calculate the total space a border takes up.
+ * Returns { horizontal, vertical } representing how many columns/rows
+ * the border consumes (0 for none, 2 for any visible border — 1 on each side).
+ */
+declare function borderSize(style: BorderStyle): {
+    horizontal: number;
+    vertical: number;
+};
+
+/**
+ * Edge values (padding, margin) — top, right, bottom, left.
+ */
+interface Edges {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Complete style definition for a widget.
+ */
+interface Style {
+    fg?: Color;
+    bg?: Color;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    dim?: boolean;
+    strikethrough?: boolean;
+    inverse?: boolean;
+    padding?: Partial<Edges> | number;
+    margin?: Partial<Edges> | number;
+    border?: BorderStyle;
+    borderColor?: Color;
+    width?: number | string;
+    height?: number | string;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    flexDirection?: 'row' | 'column';
+    justifyContent?: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around';
+    alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch';
+    flexGrow?: number;
+    flexShrink?: number;
+    flexWrap?: 'nowrap' | 'wrap';
+    gap?: number;
+    overflow?: 'visible' | 'hidden' | 'scroll';
+    /** Z-index for layer ordering. Higher values render on top. */
+    zIndex?: number;
+    /** Color of the focus ring when this widget has focus */
+    focusRingColor?: Color;
+    /** Style of the focus ring indicator */
+    focusRingStyle?: 'border' | 'corners' | 'glow' | 'none';
+    visible?: boolean;
+}
+/**
+ * Normalize a shorthand edge value (number) into the full Edges object.
+ */
+declare function normalizeEdges(value: Partial<Edges> | number | undefined): Edges;
+/**
+ * Merge two styles. `override` values take precedence.
+ * Undefined values in override do not overwrite base values.
+ */
+declare function mergeStyles(base: Style, override: Style): Style;
+/**
+ * Create a default (empty) style.
+ */
+declare function defaultStyle(): Style;
+/**
+ * Extract the cell-level style attributes from a Style object.
+ * Used when rendering text into the screen buffer.
+ */
+declare function styleToCellAttrs(style: Style): {
+    fg: Color;
+    bg: Color;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    dim: boolean;
+    strikethrough: boolean;
+    inverse: boolean;
+};
+
+/**
+ * A node in the layout tree. Each widget produces one LayoutNode.
+ */
+interface LayoutNode {
+    /** Reference back to the widget/element that created this node */
+    id: string;
+    /** Style properties that affect layout */
+    style: Style;
+    /** Child nodes */
+    children: LayoutNode[];
+    /** Computed position and size — filled in by computeLayout() */
+    computed: Rect;
+}
+/**
+ * Create a LayoutNode with default values.
+ */
+declare function createLayoutNode(id: string, style: Style, children?: LayoutNode[]): LayoutNode;
+/**
+ * Compute the layout of a tree of LayoutNodes.
+ *
+ * This is a simplified Flexbox implementation that handles:
+ * - flexDirection: row | column
+ * - justifyContent: flex-start | flex-end | center | space-between | space-around
+ * - alignItems: flex-start | flex-end | center | stretch
+ * - flexGrow / flexShrink
+ * - padding, margin, border
+ * - fixed width/height, percentage width/height
+ * - minWidth, maxWidth, minHeight, maxHeight
+ * - gap between children
+ */
+declare function computeLayout(root: LayoutNode, containerWidth: number, containerHeight: number): void;
+
+/**
+ * Strongly-typed event emitter using TypeScript generics.
+ * Supports `on`, `off`, `once`, `emit` with type-safe event maps.
+ */
+declare class EventEmitter<TEventMap extends Record<string, any>> {
+    private _handlers;
+    private _onceHandlers;
+    /**
+     * Subscribe to an event.
+     * @returns Unsubscribe function.
+     */
+    on<K extends keyof TEventMap>(event: K, handler: (data: TEventMap[K]) => void): () => void;
+    /**
+     * Subscribe to an event, but only fire once.
+     */
+    once<K extends keyof TEventMap>(event: K, handler: (data: TEventMap[K]) => void): () => void;
+    /**
+     * Unsubscribe from an event.
+     */
+    off<K extends keyof TEventMap>(event: K, handler: (data: TEventMap[K]) => void): void;
+    /**
+     * Emit an event to all subscribed handlers.
+     */
+    emit<K extends keyof TEventMap>(event: K, data: TEventMap[K]): void;
+    /**
+     * Remove all handlers for a specific event, or all events if no event specified.
+     */
+    removeAll(event?: keyof TEventMap): void;
+    /**
+     * Check if there are any handlers for an event.
+     */
+    hasListeners(event: keyof TEventMap): boolean;
+}
+
+interface Focusable {
+    id: string;
+    tabIndex: number;
+    focusable: boolean;
+}
+/**
+ * Manages tab-order focus cycling between focusable widgets.
+ * Dispatches focus/blur events when focus changes.
+ *
+ * Supports:
+ * - Tab-order cycling (focusNext/focusPrev)
+ * - Focus trapping (for modals — limits Tab to a container)
+ * - Focus groups (for arrow-key navigation within a group)
+ */
+declare class FocusManager {
+    private _focusables;
+    private _currentIndex;
+    private _events;
+    /**
+     * Stack of trap container IDs. When non-empty, only focusables
+     * that belong to the topmost trap container are reachable via Tab.
+     */
+    private _trapStack;
+    /**
+     * Map of container ID → child widget IDs that belong to it.
+     * Used for trap membership lookup.
+     */
+    private _containerMembers;
+    /**
+     * Named focus groups. Arrow keys move within a group, Tab moves between groups.
+     * Maps groupId → ordered list of widget IDs.
+     */
+    private _groups;
+    /** Currently focused widget ID, or null if none */
+    get currentId(): string | null;
+    /** Subscribe to focus/blur events */
+    on<K extends 'focus' | 'blur'>(event: K, handler: (data: FocusEvent) => void): () => void;
+    /**
+     * Register a focusable widget.
+     * Widgets are ordered by tabIndex (ascending), then insertion order.
+     */
+    register(focusable: Focusable): void;
+    /**
+     * Unregister a focusable widget.
+     */
+    unregister(id: string): void;
+    /**
+     * Move focus to the next focusable widget (wraps around).
+     * Respects focus traps — if a trap is active, only cycles within it.
+     */
+    focusNext(): void;
+    /**
+     * Move focus to the previous focusable widget (wraps around).
+     * Respects focus traps.
+     */
+    focusPrev(): void;
+    /**
+     * Focus a specific widget by ID.
+     */
+    focusWidget(id: string): void;
+    /**
+     * Check if a specific widget currently has focus.
+     */
+    isFocused(id: string): boolean;
+    /**
+     * Register widget IDs as members of a container (for trap lookup).
+     */
+    registerContainerMembers(containerId: string, memberIds: string[]): void;
+    /**
+     * Unregister a container's member list.
+     */
+    unregisterContainerMembers(containerId: string): void;
+    /**
+     * Trap focus within a container. Only focusables inside the
+     * container are reachable via Tab. Traps are stacked —
+     * nested modals create nested traps.
+     */
+    trap(containerId: string): void;
+    /**
+     * Release the current focus trap. Restores previous trap or free navigation.
+     */
+    release(): void;
+    /** Whether a focus trap is currently active */
+    get isTrapped(): boolean;
+    /** ID of the current trap container, or null */
+    get currentTrapId(): string | null;
+    /**
+     * Register a focus group. Arrow keys move within the group.
+     * @param groupId   Unique group identifier
+     * @param widgetIds Ordered list of widget IDs in the group
+     */
+    registerGroup(groupId: string, widgetIds: string[]): void;
+    /**
+     * Unregister a focus group.
+     */
+    unregisterGroup(groupId: string): void;
+    /**
+     * Move focus to the next widget within the same group.
+     * Returns true if focus was moved, false if the widget isn't in a group.
+     */
+    focusNextInGroup(): boolean;
+    /**
+     * Move focus to the previous widget within the same group.
+     */
+    focusPrevInGroup(): boolean;
+    /**
+     * Get the active focusables, filtered by the current trap if any.
+     */
+    private _getActiveFocusables;
+    private _changeFocus;
+}
+
+interface AppOptions extends TerminalOptions {
+    /** Frames per second for the render loop */
+    fps?: number;
+    /** Use alternate screen (full-screen mode). Default: true */
+    fullscreen?: boolean;
+    /** Enable mouse support. Default: false */
+    mouse?: boolean;
+    /** Force fallback (static) rendering */
+    forceFallback?: boolean;
+    /** Title to set on the terminal window */
+    title?: string;
+}
+/**
+ * Widget interface that App expects for the root widget.
+ * This is the minimum contract — the full Widget class in @termuijs/widgets extends this.
+ */
+interface RootWidget {
+    id: string;
+    getLayoutNode(): LayoutNode;
+    syncLayout?(): void;
+    render(screen: Screen): void;
+    mount?(): void;
+    unmount?(): void;
+    /** Check if this widget needs re-rendering (dirty flag) */
+    isDirty?: boolean;
+    /** Clear the dirty flag after rendering */
+    clearDirty?(): void;
+}
+/**
+ * Application lifecycle manager.
+ *
+ * Manages:
+ * - Terminal setup/teardown (alt screen, raw mode, cursor, mouse)
+ * - Screen buffer and renderer initialization
+ * - Input parsing and event dispatch
+ * - Layout computation and rect sync
+ * - Render loop
+ * - Graceful shutdown
+ */
+declare class App {
+    readonly terminal: Terminal;
+    readonly screen: Screen;
+    readonly renderer: Renderer;
+    readonly input: InputParser;
+    readonly focus: FocusManager;
+    readonly events: EventEmitter<EventMap>;
+    readonly layers: LayerManager;
+    private _rootWidget;
+    private _options;
+    private _mounted;
+    private _exitResolve;
+    constructor(rootWidget: RootWidget, options?: AppOptions);
+    /**
+     * Start the application.
+     * Sets up the terminal, starts the render loop, and mounts the root widget.
+     * Returns a promise that resolves when exit() is called.
+     */
+    mount(): Promise<number>;
+    /**
+     * Stop the application and restore terminal state.
+     */
+    unmount(): void;
+    /**
+     * Create an overlay layer for rendering above normal widgets.
+     * @param id     Unique layer identifier (e.g. 'modal', 'select-dropdown', 'toast')
+     * @param zIndex Stacking order (higher = rendered on top). Default: 100
+     */
+    addOverlay(id: string, zIndex?: number): void;
+    /**
+     * Remove an overlay layer.
+     */
+    removeOverlay(id: string): void;
+    /**
+     * Request a re-render on the next frame.
+     */
+    requestRender(): void;
+    /**
+     * Exit the app (convenience method).
+     */
+    exit(code?: number): void;
+    /**
+     * Render in fallback (static) mode for non-interactive environments.
+     */
+    private _renderFallback;
+    /**
+     * Build the bubble chain for keyboard events.
+     * Returns an array: [focused widget, parent, grandparent, ..., root]
+     */
+    private _buildBubbleChain;
+    /**
+     * Find a widget by ID in the widget tree (DFS).
+     * Uses duck-typing to work with any object that has id/children.
+     */
+    private _findWidgetById;
+}
+
+/**
+ * Detect if the terminal should use fallback (non-interactive) rendering.
+ *
+ * Returns true when:
+ * - stdout is not a TTY (piped)
+ * - CI environment variable is set
+ * - TERM is 'dumb'
+ * - NO_COLOR is set
+ */
+declare function shouldUseFallback(): boolean;
+/**
+ * Render a Screen buffer as plain text (no ANSI, no interactivity).
+ *
+ * Reads all cells from the screen and produces a simple text representation.
+ * Strips trailing whitespace from each line and removes empty trailing lines.
+ */
+declare function renderFallback(screen: Screen): string;
+
+/**
+ * Calculate the visual width of a string in terminal columns.
+ *
+ * - CJK characters count as 2 columns
+ * - Emoji count as 2 columns
+ * - Combining/zero-width characters count as 0
+ * - ANSI escape sequences count as 0
+ * - Regular characters count as 1
+ */
+declare function stringWidth(str: string): number;
+/**
+ * Truncate a string to the given visual width, preserving ANSI codes.
+ * Appends an ellipsis character if truncated.
+ */
+declare function truncate(str: string, maxWidth: number, ellipsis?: string): string;
+/**
+ * Strip all ANSI escape sequences from a string.
+ */
+declare function stripAnsi(str: string): string;
+/**
+ * Word-wrap text to a given width, respecting existing newlines.
+ * Does not handle ANSI codes within words (wraps at the character level).
+ */
+declare function wordWrap(str: string, width: number): string;
+
+/** CSI (Control Sequence Introducer) prefix */
+declare const CSI = "\u001B[";
+/** OSC (Operating System Command) prefix */
+declare const OSC = "\u001B]";
+/** ESC character */
+declare const ESC = "\u001B";
+declare const hideCursor = "\u001B[?25l";
+declare const showCursor = "\u001B[?25h";
+declare const saveCursorPosition = "\u001B[s";
+declare const restoreCursorPosition = "\u001B[u";
+declare function moveTo(col: number, row: number): string;
+declare function moveUp(n?: number): string;
+declare function moveDown(n?: number): string;
+declare function moveRight(n?: number): string;
+declare function moveLeft(n?: number): string;
+declare const clearScreen = "\u001B[2J";
+declare const clearLine = "\u001B[2K";
+declare const clearLineToEnd = "\u001B[0K";
+declare const clearLineToStart = "\u001B[1K";
+declare const clearDown = "\u001B[J";
+declare const clearUp = "\u001B[1J";
+declare const enterAltScreen = "\u001B[?1049h";
+declare const exitAltScreen = "\u001B[?1049l";
+/** Begin synchronized update — terminal holds display until end marker */
+declare const beginSyncUpdate = "\u001B[?2026h";
+/** End synchronized update — terminal flushes all pending changes atomically */
+declare const endSyncUpdate = "\u001B[?2026l";
+/** Enable SGR mouse tracking (most compatible modern mode) */
+declare const enableMouse = "\u001B[?1000h\u001B[?1002h\u001B[?1006h";
+/** Disable mouse tracking */
+declare const disableMouse = "\u001B[?1000l\u001B[?1002l\u001B[?1006l";
+declare const enableBracketedPaste = "\u001B[?2004h";
+declare const disableBracketedPaste = "\u001B[?2004l";
+declare const reset = "\u001B[0m";
+declare const bold = "\u001B[1m";
+declare const dim = "\u001B[2m";
+declare const italic = "\u001B[3m";
+declare const underline = "\u001B[4m";
+declare const blink = "\u001B[5m";
+declare const inverse = "\u001B[7m";
+declare const strikethrough = "\u001B[9m";
+declare const resetBold = "\u001B[22m";
+declare const resetDim = "\u001B[22m";
+declare const resetItalic = "\u001B[23m";
+declare const resetUnderline = "\u001B[24m";
+declare const resetBlink = "\u001B[25m";
+declare const resetInverse = "\u001B[27m";
+declare const resetStrikethrough = "\u001B[29m";
+declare function setScrollRegion(top: number, bottom: number): string;
+declare const resetScrollRegion = "\u001B[r";
+declare function setTitle(title: string): string;
+
+declare const ansi_CSI: typeof CSI;
+declare const ansi_ESC: typeof ESC;
+declare const ansi_OSC: typeof OSC;
+declare const ansi_beginSyncUpdate: typeof beginSyncUpdate;
+declare const ansi_blink: typeof blink;
+declare const ansi_bold: typeof bold;
+declare const ansi_clearDown: typeof clearDown;
+declare const ansi_clearLine: typeof clearLine;
+declare const ansi_clearLineToEnd: typeof clearLineToEnd;
+declare const ansi_clearLineToStart: typeof clearLineToStart;
+declare const ansi_clearScreen: typeof clearScreen;
+declare const ansi_clearUp: typeof clearUp;
+declare const ansi_dim: typeof dim;
+declare const ansi_disableBracketedPaste: typeof disableBracketedPaste;
+declare const ansi_disableMouse: typeof disableMouse;
+declare const ansi_enableBracketedPaste: typeof enableBracketedPaste;
+declare const ansi_enableMouse: typeof enableMouse;
+declare const ansi_endSyncUpdate: typeof endSyncUpdate;
+declare const ansi_enterAltScreen: typeof enterAltScreen;
+declare const ansi_exitAltScreen: typeof exitAltScreen;
+declare const ansi_hideCursor: typeof hideCursor;
+declare const ansi_inverse: typeof inverse;
+declare const ansi_italic: typeof italic;
+declare const ansi_moveDown: typeof moveDown;
+declare const ansi_moveLeft: typeof moveLeft;
+declare const ansi_moveRight: typeof moveRight;
+declare const ansi_moveTo: typeof moveTo;
+declare const ansi_moveUp: typeof moveUp;
+declare const ansi_reset: typeof reset;
+declare const ansi_resetBlink: typeof resetBlink;
+declare const ansi_resetBold: typeof resetBold;
+declare const ansi_resetDim: typeof resetDim;
+declare const ansi_resetInverse: typeof resetInverse;
+declare const ansi_resetItalic: typeof resetItalic;
+declare const ansi_resetScrollRegion: typeof resetScrollRegion;
+declare const ansi_resetStrikethrough: typeof resetStrikethrough;
+declare const ansi_resetUnderline: typeof resetUnderline;
+declare const ansi_restoreCursorPosition: typeof restoreCursorPosition;
+declare const ansi_saveCursorPosition: typeof saveCursorPosition;
+declare const ansi_setScrollRegion: typeof setScrollRegion;
+declare const ansi_setTitle: typeof setTitle;
+declare const ansi_showCursor: typeof showCursor;
+declare const ansi_strikethrough: typeof strikethrough;
+declare const ansi_underline: typeof underline;
+declare namespace ansi {
+  export { ansi_CSI as CSI, ansi_ESC as ESC, ansi_OSC as OSC, ansi_beginSyncUpdate as beginSyncUpdate, ansi_blink as blink, ansi_bold as bold, ansi_clearDown as clearDown, ansi_clearLine as clearLine, ansi_clearLineToEnd as clearLineToEnd, ansi_clearLineToStart as clearLineToStart, ansi_clearScreen as clearScreen, ansi_clearUp as clearUp, ansi_dim as dim, ansi_disableBracketedPaste as disableBracketedPaste, ansi_disableMouse as disableMouse, ansi_enableBracketedPaste as enableBracketedPaste, ansi_enableMouse as enableMouse, ansi_endSyncUpdate as endSyncUpdate, ansi_enterAltScreen as enterAltScreen, ansi_exitAltScreen as exitAltScreen, ansi_hideCursor as hideCursor, ansi_inverse as inverse, ansi_italic as italic, ansi_moveDown as moveDown, ansi_moveLeft as moveLeft, ansi_moveRight as moveRight, ansi_moveTo as moveTo, ansi_moveUp as moveUp, ansi_reset as reset, ansi_resetBlink as resetBlink, ansi_resetBold as resetBold, ansi_resetDim as resetDim, ansi_resetInverse as resetInverse, ansi_resetItalic as resetItalic, ansi_resetScrollRegion as resetScrollRegion, ansi_resetStrikethrough as resetStrikethrough, ansi_resetUnderline as resetUnderline, ansi_restoreCursorPosition as restoreCursorPosition, ansi_saveCursorPosition as saveCursorPosition, ansi_setScrollRegion as setScrollRegion, ansi_setTitle as setTitle, ansi_showCursor as showCursor, ansi_strikethrough as strikethrough, ansi_underline as underline };
+}
+
+export { App, type AppOptions, BORDER_CHARS, type BorderChars, type BorderStyle, CTRL_KEYS, type Cell, type Color, ColorDepth, ESCAPE_SEQUENCES, type Edges, EventEmitter, type EventMap, type FocusEvent, FocusManager, type Focusable, InputParser, type KeyEvent, type Layer, LayerManager, type LayoutNode, type MouseEvent, type NamedColor, type Rect, Renderer, type ResizeEvent, type RootWidget, SPECIAL_KEYS, Screen, type Size, type Style, Terminal, type TerminalOptions, ansi, borderSize, cellsEqual, colorToAnsiBg, colorToAnsiFg, colorToRgb, computeLayout, containsPoint, createKeyEvent, createLayoutNode, defaultStyle, detectColorDepth, emptyCell, emptyRect, getBorderChars, intersectRect, isMouseSequence, mergeStyles, normalizeEdges, parseColor, parseMouseEvent, renderFallback, shouldUseFallback, shrinkRect, stringWidth, stripAnsi, styleToCellAttrs, truncate, unionRect, wordWrap };