retty-ui

Imperative TUI core + React 19 bindings. Pure TypeScript, zero native dependencies.

Build terminal UIs the same way you build web UIs — declarative React 19 components, OR a small imperative API if React feels like overkill for your agent. Layout is computed by yoga-layout-tui (pure-TS flexbox, no Zig, no WASM, no native binary).

┌────────────────────────────────────┐
│  src/react/    (React 19 binding)  │
└────────────┬───────────────────────┘
             │
┌────────────▼───────────────────────┐
│  src/core/     (imperative core)   │
│  - Renderable, Canvas, Renderer    │
│  - Box, Text, TextArea, ScrollBox  │
└────────────┬───────────────────────┘
             │
┌────────────▼───────────────────────┐
│  yoga-layout-tui  (pure-TS flexbox)│
└────────────────────────────────────┘

The imperative core is shared between the command-style API (retty-ui) and the React reconciler (retty-ui/react). The React layer is a thin adapter that maps props to command-style setters — the actual work (layout, render, IME / focus / cursor state) stays in the core.

Install

bun add retty-ui

Requires Bun 1.3+ as the runtime.

Quick start — command-style

import { Box, Renderer, rgb, ScrollBox, Text, TextArea } from "retty-ui";

const renderer = new Renderer({ alternate: true });

const root = new Box({ style: { flexDirection: "column", height: 24, width: 80 } });

const header = new Box({ style: { height: 3 }, borderStyle: "double", borderColor: rgb(59, 142, 234) });
header.add(new Text("Retty TUI ", { color: rgb(59, 142, 234), bold: true }));
root.add(header);

const logs = new ScrollBox({ style: { flexGrow: 1, borderStyle: "single" } });
for (let i = 1; i <= 5; i++) logs.add(new Text(`[boot] line ${i}`));
root.add(logs);

const input = new Box({ style: { minHeight: 3, flexDirection: "row" }, borderStyle: "round" });
const ta = new TextArea({ placeholder: "Type a message… (Ctrl+C to exit)", style: { flexGrow: 1 } });
input.add(new Text("$ ", { bold: true }));
input.add(ta);
root.add(input);

renderer.mount(root);
ta.focus();
renderer.start();

Run with bun run demo.ts (or bunx retty-ui if you prefer the bundled CLI).

Quick start — React 19

import { useRef, useState } from "react";
import { Box, render, ScrollBox, Text, TextArea, useApp, useInput } from "retty-ui/react";

function App() {
  const [logs, setLogs] = useState<string[]>(["hello"]);
  const [input, setInput] = useState("");
  const ta = useRef<TextArea>(null);
  const { unmount } = useApp();

  useInput((_, key) => {
    if (key.ctrl && key.name === "c") unmount();
  });

  return (
    <Box style={{ flexDirection: "column", height: 24, width: 80 }}>
      <Box style={{ height: 3 }} borderStyle="double" borderColor="#3b8eea">
        <Text text="Retty TUI " color="#3b8eea" bold />
      </Box>

      <ScrollBox style={{ flexGrow: 1 }} borderStyle="single">
        {logs.map((line, i) => <Text key={i} text={line} />)}
      </ScrollBox>

      <Box style={{ minHeight: 3, flexDirection: "row" }} borderStyle="round">
        <Text text="$ " bold />
        <TextArea
          ref={ta}
          value={input}
          placeholder="Type a message…"
          onChange={setInput}
          onSubmit={(v) => {
            setLogs((p) => [...p, `[you]: ${v}`]);
            setInput("");
            ta.current?.focus();
          }}
        />
      </Box>
    </Box>
  );
}

render(<App />, { alternate: true });

Components

| Component | Purpose | Key props | |---|---|---| | Box | Container (flexbox layout, optional border) | style, borderStyle, borderColor | | Text | Single/multi-line text | text, color, bold/italic/dim/… | | TextArea | Input box with IME composing + cursor | value, onChange, onSubmit, placeholder | | ScrollBox | Scrollable viewport over child nodes | scrollBy, scrollTo, scrollToBottom |

Border styles: "single" | "double" | "round" | "classic" | "none".

Hooks (React)

| Hook | Purpose | |---|---| | useApp() | Returns { unmount } — exit the rendered app cleanly | | useInput(cb, opts?) | Subscribe to every keystroke (fan-out, all listeners receive all keys) | | useFocus() | Returns { isFocused, focus, blur } | | useMouse(cb) | Subscribe to mouse events (requires mouse: true in render options) | | usePaste(cb) | Subscribe to bracketed paste events | | useEffectEvent(fn) | Stable callback ref (React useEffectEvent polyfill) |

Imperative core (advanced)

If you don't want React, the imperative core exposes:

• Renderer — alternate-screen + double-buffered diff renderer
• Canvas — direct cell-buffer access (for custom paints)
• inputManager — raw mode + key/mouse/paste decoding
• renderHeadless(tree) — render to a string (tests, snapshots)
• layoutText(s, maxWidth) — soft-wrap text into { lines, width, height }
• Node, Edge, Direction, MeasureMode, Align, Display, FlexDirection, Gutter, Justify, Overflow, PositionType — re-exports of the yoga-layout-tui enums

See AGENTS.md for build / test / typecheck commands and architectural notes.

Why an imperative core?

The v0.1 React-centric version had three structural bugs (double data source, measure-cache lock-up, force-render storms). The v0.2 imperative core fixed them by owning state (IME composing, focus, cursor) outside React. v0.3 keeps the same core and just swaps the Zig FFI yoga layer for a pure-TS one.

License

MIT