tui

interface ButtonProps extends StyleProps, FlexChildProps, Props {

Props accepted by Button.

Properties

interface ListProps extends StyleProps, FlexChildProps, Props {

Props accepted by List.

Properties

interface TuiFocus {

Focus control surface exposed by a live TUI app.

Readonly Properties

Methods

interface RenderFrameOptions {

Options for deterministic terminal snapshot rendering.

Properties

interface TerminalSize {

Current terminal viewport size in character cells.

Properties

interface RenderOptions {

Options for live fullscreen terminal rendering.

Properties

interface TuiApp {

Handle returned by render() for updating or stopping a fullscreen app.

Methods

Properties

interface TuiInputOptions {

Options for creating a raw terminal input reader.

Properties

type TuiKeyEvent = UiKeyEvent

Keyboard event decoded from terminal input.

type TuiMouseEvent = UiMouseEvent

Mouse event decoded from SGR terminal mouse reporting.

type TuiEvent = TuiKeyEvent | TuiMouseEvent

Terminal input event consumed by TUI applications.

function Button(props: ButtonProps): VNode

Push button primitive rendered as bracketed terminal text.

function List(props: ListProps): VNode

Vertical list primitive with a selected row marker.

function measure(element: VNode, constraints: Constraints): Measured

Measure a terminal component tree under the supplied cell constraints.

function layout(element: VNode, constraints: Constraints): Frame

Lay out and paint a terminal component tree into a structured frame.

function decodeTuiInput(bytes: Uint8Array): TuiEvent[]

Decode one complete terminal input byte chunk into TUI input events.

The decoder understands printable UTF-8, common control keys, arrow/function CSI sequences, and SGR mouse reporting (CSI < code ; x ; y M/m). SGR mouse coordinates are converted to zero-based x/y values. A trailing partial sequence is treated literally; TuiInput reassembles partial live reads.

function createTuiInput(options: TuiInputOptions = {}): TuiInput

Create a raw terminal input reader for TUI applications.

The reader enables raw mode immediately. Call close() when the application exits so terminal state is restored.

function getTerminalSize(): TerminalSize

Return the current terminal viewport size.

The TUI host asks the terminal with ioctl(TIOCGWINSZ) when possible and falls back to environment dimensions in non-interactive contexts.

async function measureTerminalSize(): Promise<TerminalSize>

Measure the visible terminal viewport with an ANSI cursor-position query.

This is slower than getTerminalSize() but handles terminal panes where ioctl(TIOCGWINSZ) or environment dimensions are stale. The function enters raw mode briefly, moves the cursor to a very large coordinate, asks the terminal to report the clamped cursor position, restores the cursor, and returns the reported row/column. If the terminal does not answer quickly, it falls back to getTerminalSize().

function layoutFrame(element: VNode, options: RenderFrameOptions): Frame

Lay a tree out into a styled-cell frame without touching a terminal.

This is the one-shot path: the tree is laid out fresh with no retained state. Pass the result to frameToAnsi()/frameToScreen() from fino:tty/frame, or use renderFrame() for the padded-string form.

function renderFrame(element: VNode, options: RenderFrameOptions): string

Render an element tree to a deterministic terminal frame.

The returned string contains exactly height lines joined with \n, and each line is padded or clipped to width cells.

function frameSink(options: RenderFrameOptions): Sink<string>

Sink that turns each committed tree into a terminal frame string.

The frame is a complete screen image rather than a diff, so this is a snapshot sink like htmlSink(). Pair it with renderStatic() to capture one frame, or with createRoot() to drive a live screen from signals.

import { createRoot } from 'fino:ui';
import { frameSink } from 'fino:tty/tui';

const root = createRoot(App, frameSink({ width: 80, height: 24 }));

function terminalSink(options: RenderFrameOptions): Sink<Frame>

Sink that reconciles each committed tree into a retained terminal node tree and returns the laid-out Frame.

Unlike frameSink(), consecutive commits reuse the mounted tree, so unchanged subtrees keep their measurement caches. Use this when the caller needs the structured frame — cursor placement, hit regions — rather than encoded text.

function render(element: VNode | (() => VNode), options: RenderOptions = {}): TuiApp

Render a fullscreen terminal app and return a lifecycle handle.

This enters the alternate screen, hides the cursor, and paints frames through the retained host with row-level diffing — only rows whose encoded form changed are rewritten. When a frame places a caret (Text caret or a focused Input), the terminal cursor is shown there.

Passing a function instead of a tree makes the app reactive: every signal read while rendering becomes a dependency, and the screen repaints when one changes. update() remains available for callers that drive frames themselves, and takes over from the reactive root when used. Tree handlers receive input before onEvent; only unconsumed events reach the fallback callback. stop() is idempotent and cancels a blocked input read before restoring raw mode, mouse reporting, cursor state, auto-wrap, and the primary screen.

import { createSignal } from 'fino:ui';
import { Text, render } from 'fino:tty/tui';

const ticks = createSignal(0);
const app = render(() => Text({ children: [String(ticks.get())] }));
ticks.set(1);
app.stop();

class TuiInput {

Raw terminal input reader for keyboard and mouse events.

One reader owns stdin raw mode and its readability watch at a time. Calls to read() are sequential: each returns one decoded event, preserving partial escape sequences and UTF-8 between operating-system reads. close() is idempotent, cancels a blocked read, disables mouse reporting when enabled, and restores the terminal mode captured by the constructor.

Constructors

Methods