Skip to content

Commit adf4bbf

Browse files
RtlZeroMemoryRtlZeroMemory
authored
Update README.md
1 parent f810b93 commit adf4bbf

1 file changed

Lines changed: 164 additions & 76 deletions

File tree

‎README.md‎

Lines changed: 164 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,96 @@
11
<h1 align="center">Rezi</h1>
22

33
<p align="center">
4-
<strong>Terminal UI framework for TypeScript with a native rendering engine.</strong>
4+
<strong>TypeScript TUI, Near-Native Performance.</strong><br/>
5+
High-level developer experience powered by a deterministic C rendering engine.
56
</p>
67

78
<p align="center">
8-
<a href="https://www.npmjs.com/package/@rezi-ui/core"><img src="https://img.shields.io/npm/v/@rezi-ui/core.svg" alt="npm version"></a>
9-
<a href="https://github.com/RtlZeroMemory/Rezi/actions/workflows/ci.yml"><img src="https://github.com/RtlZeroMemory/Rezi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
10-
<a href="https://rtlzeromemory.github.io/Rezi/"><img src="https://github.com/RtlZeroMemory/Rezi/actions/workflows/docs.yml/badge.svg" alt="docs"></a>
11-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
9+
<a href="https://www.npmjs.com/package/@rezi-ui/core">
10+
<img src="https://img.shields.io/npm/v/@rezi-ui/core.svg" alt="npm version">
11+
</a>
12+
<a href="https://github.com/RtlZeroMemory/Rezi/actions/workflows/ci.yml">
13+
<img src="https://github.com/RtlZeroMemory/Rezi/actions/workflows/ci.yml/badge.svg" alt="CI">
14+
</a>
15+
<a href="https://rtlzeromemory.github.io/Rezi/">
16+
<img src="https://github.com/RtlZeroMemory/Rezi/actions/workflows/docs.yml/badge.svg" alt="docs">
17+
</a>
18+
<a href="LICENSE">
19+
<img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License">
20+
</a>
1221
</p>
1322

1423
<p align="center">
1524
<a href="https://rtlzeromemory.github.io/Rezi/">Docs</a> ·
1625
<a href="https://rtlzeromemory.github.io/Rezi/getting-started/quickstart/">Quickstart</a> ·
1726
<a href="https://rtlzeromemory.github.io/Rezi/widgets/">Widgets</a> ·
18-
<a href="https://rtlzeromemory.github.io/Rezi/api/">API Reference</a> ·
27+
<a href="https://rtlzeromemory.github.io/Rezi/api/">API</a> ·
1928
<a href="BENCHMARKS.md">Benchmarks</a>
2029
</p>
2130

31+
---
32+
2233
> **Status: Alpha** — under active development. APIs may change between releases.
2334
24-
Rezi is a TypeScript terminal UI framework for Node.js and Bun. You write declarative widget trees in TypeScript; Rezi computes layout, emits binary drawlists, and delegates framebuffer diffing and terminal output to [Zireael](https://github.com/RtlZeroMemory/Zireael), a purpose-built C rendering engine.
35+
---
2536

26-
The result: TypeScript ergonomics with rendering performance in the same class as native TUIs.
37+
## Showcase — EdgeOps Control Plane
2738

28-
Dashboard demo
39+
A production-style terminal control console built entirely with Rezi.
2940

30-
![Rezi core demo](Assets/REZICONSOLE3.gif)
41+
![Rezi demo](Assets/REZICONSOLE3.gif)
42+
43+
---
44+
45+
## What is Rezi?
46+
47+
Rezi is a high-performance terminal UI framework for **TypeScript**.
48+
49+
You write declarative widget trees in TypeScript.
50+
Rezi computes layout and emits a compact binary drawlist (ZRDL).
51+
A native C engine — [Zireael](https://github.com/RtlZeroMemory/Zireael) — diffs framebuffers and writes only changed cells to the terminal.
52+
53+
The result:
54+
55+
- TypeScript ergonomics
56+
- Deterministic rendering
57+
- Near-native performance
58+
- No React runtime
59+
- No virtual DOM overhead
60+
61+
---
62+
63+
## Why Rezi?
64+
65+
Most JavaScript terminal frameworks generate ANSI escape sequences in userland on every update. Rendering cost scales with tree size and update frequency.
66+
67+
Rezi moves the hot path out of JavaScript.
68+
69+
1. **Application code** builds a declarative widget tree.
70+
2. **@rezi-ui/core** computes layout and encodes a compact binary drawlist.
71+
3. **Zireael (C engine)** diffs framebuffer state and writes only changed cells.
72+
73+
Rendering remains ergonomic at the top — and native-speed at the bottom.
74+
75+
In PTY-mode benchmarks (120×40 viewport), Rezi operates within ~2×–5× of a native Rust baseline (ratatui) and significantly outperforms React-based terminal frameworks:
76+
77+
| Scenario | ratatui (Rust) | Rezi | Ink |
78+
|---|---:|---:|---:|
79+
| `terminal-rerender` | 74 µs | 322 µs | 16.39 ms |
80+
| `terminal-frame-fill` (1 dirty line) | 197 µs | 567 µs | 17.73 ms |
81+
| `terminal-frame-fill` (40 dirty lines) | 211 µs | 610 µs | 17.66 ms |
82+
| `terminal-virtual-list` | 126 µs | 584 µs | 18.88 ms |
83+
| `terminal-table` | 178 µs | 493 µs | 17.44 ms |
84+
85+
Full methodology and reproduction steps:
86+
👉 **[BENCHMARKS.md](BENCHMARKS.md)**
3187

3288
---
3389

3490
## Quick Start
3591

92+
Get running in under a minute:
93+
3694
```bash
3795
npm create rezi my-app
3896
cd my-app
@@ -47,7 +105,9 @@ cd my-app
47105
bun start
48106
```
49107

50-
Starter template (current): `dashboard` (EdgeOps control-plane console).
108+
Starter template: **EdgeOps control-plane dashboard**
109+
110+
---
51111

52112
## Example
53113

@@ -77,13 +137,17 @@ app.keys({ q: () => app.stop() });
77137
await app.start();
78138
```
79139

140+
Install:
141+
80142
```bash
81143
npm install @rezi-ui/core @rezi-ui/node
82144
```
83145

84-
### JSX (no React)
146+
---
147+
148+
### JSX (No React Runtime)
85149

86-
`@rezi-ui/jsx` maps JSX syntax directly to Rezi VNodes — no React runtime involved.
150+
`@rezi-ui/jsx` maps JSX directly to Rezi VNodes.
87151

88152
```tsx
89153
/** @jsxImportSource @rezi-ui/jsx */
@@ -99,7 +163,11 @@ app.view((s) => (
99163
<Text style={{ bold: true }}>Counter</Text>
100164
<Row gap={2}>
101165
<Text>Count: {s.count}</Text>
102-
<Button id="inc" label="+1" onPress={() => app.update((prev) => ({ count: prev.count + 1 }))} />
166+
<Button
167+
id="inc"
168+
label="+1"
169+
onPress={() => app.update((prev) => ({ count: prev.count + 1 }))}
170+
/>
103171
</Row>
104172
</Column>
105173
));
@@ -112,110 +180,130 @@ await app.start();
112180
npm install @rezi-ui/jsx @rezi-ui/core @rezi-ui/node
113181
```
114182

115-
## Why Rezi?
183+
---
116184

117-
Most JavaScript terminal frameworks generate ANSI escape sequences in userland on every update. This works, but rendering cost scales with tree size and update frequency.
185+
## Features
118186

119-
Rezi takes a different approach:
187+
### Widgets
188+
49 built-in widgets:
189+
- Layout primitives (box, row, column, text)
190+
- Forms (input, button, checkbox, select, slider)
191+
- Data display (table, tree, virtual list)
192+
- Overlays (modal, dropdown, toast, command palette)
193+
- Advanced (code editor, diff viewer, file picker)
194+
- Charts (gauge, sparkline, bar chart)
120195

121-
1. **Your code** builds a declarative widget tree in TypeScript.
122-
2. **Rezi** computes layout and encodes a compact binary drawlist (ZRDL).
123-
3. **Zireael** (native C engine) diffs framebuffer state and writes only changed cells to the terminal.
196+
### Focus & Input
197+
- Automatic tab navigation
198+
- Focus traps for modals
199+
- Global keybindings
200+
- Vim-style and chord sequences
201+
- Mouse support (click, scroll, drag)
124202

125-
This keeps authoring ergonomic while moving the hot rendering path to native code. In our PTY-mode benchmark suite (`120x40` viewport), Rezi is ~2x–5x from a native Rust baseline (ratatui) and 30x–50x ahead of Ink:
203+
### Theming
204+
Six built-in themes:
205+
`dark`, `light`, `dimmed`, `high-contrast`, `nord`, `dracula`
126206

127-
| Scenario | ratatui (Rust) | Rezi | Ink |
128-
|---|---:|---:|---:|
129-
| `terminal-rerender` | 74 µs | 322 µs | 16.39 ms |
130-
| `terminal-frame-fill` (1 dirty line) | 197 µs | 567 µs | 17.73 ms |
131-
| `terminal-frame-fill` (40 dirty lines) | 211 µs | 610 µs | 17.66 ms |
132-
| `terminal-virtual-list` | 126 µs | 584 µs | 18.88 ms |
133-
| `terminal-table` | 178 µs | 493 µs | 17.44 ms |
134-
135-
Full methodology, caveats, and reproduction steps: **[BENCHMARKS.md](BENCHMARKS.md)**
136-
137-
## Features
207+
Switch at runtime:
138208

139-
**49 built-in widgets** — primitives (box, row, column, text), form inputs (input, button, checkbox, select, slider), data display (table, virtual list, tree), overlays (modal, dropdown, toast, command palette), advanced (code editor, diff viewer, file picker, logs console), and charts (gauge, sparkline, bar chart).
209+
```ts
210+
app.setTheme("nord");
211+
```
140212

141-
**Focus management** — automatic Tab/Shift+Tab navigation, focus zones, focus traps for modals, and mouse click-to-focus.
213+
### Deterministic Rendering
214+
- Same state + same events = same frames
215+
- Versioned binary protocol
216+
- Pinned Unicode version
217+
- Strict update semantics
142218

143-
**Keybindings** — global shortcuts, modal modes (Vim-style `g g`, Emacs-style `C-x C-s`), and chord sequences.
219+
### Record & Replay
220+
Capture input sessions as deterministic bundles for debugging and testing.
144221

145-
**Theming** — six built-in themes (dark, light, dimmed, high-contrast, nord, dracula) with semantic color tokens. Switch at runtime with `app.setTheme()`.
222+
---
146223

147-
**Mouse support** — click to focus, scroll wheel for lists and editors, drag to resize split panes. Detected automatically.
224+
## Who is Rezi for?
148225

149-
**Composition** — `defineWidget` provides stateful reusable components with hooks (`useState`, `useRef`, `useEffect`).
226+
Rezi is built for:
150227

151-
**Deterministic rendering** — same state + same events = same frames. Pinned Unicode version, versioned binary protocols, strict update semantics.
228+
- Real-time dashboards
229+
- Developer tooling
230+
- Control planes
231+
- Log viewers
232+
- Terminal-first applications
233+
- Teams who want TypeScript ergonomics without sacrificing performance
152234

153-
**Record & replay** — capture input sessions as deterministic bundles for testing and debugging.
235+
---
154236

155237
## Architecture
156238

239+
Rezi separates authoring from rendering:
240+
157241
```
158-
Application Code
242+
Application Code (TypeScript)
159243
│
160244
▼
161-
@rezi-ui/core Runtime-agnostic: widgets, layout, themes,
162-
│ keybindings, forms, protocol builders
245+
@rezi-ui/core Layout, widgets, protocol builders
163246
│ ZRDL drawlist
164247
▼
165-
@rezi-ui/node Node.js/Bun backend: worker thread, event loop,
166-
│ SharedArrayBuffer transport
248+
@rezi-ui/node Node.js/Bun backend
249+
│
250+
▼
251+
@rezi-ui/native N-API binding
252+
│
167253
▼
168-
@rezi-ui/native N-API addon (napi-rs) binding to Zireael
254+
Zireael (C engine) Framebuffer diff, ANSI emission
169255
│
170256
▼
171-
Zireael (C engine) Framebuffer diff, ANSI emission, terminal I/O
172-
│ ZREV events
173-
▲
174-
Terminal
257+
Terminal
175258
```
176259

177-
Data flows down as drawlists (ZRDL). Input events flow up as event batches (ZREV). Both are versioned, little-endian binary formats validated at the boundary.
260+
Data flows down as drawlists (ZRDL).
261+
Input events flow up as event batches (ZREV).
262+
Both are versioned binary formats validated at the boundary.
263+
264+
---
178265

179266
## Packages
180267

181268
| Package | Description |
182269
|---|---|
183-
| [`@rezi-ui/core`](https://www.npmjs.com/package/@rezi-ui/core) | Widgets, layout, themes, keybindings, forms. Runtime-agnostic — no Node.js APIs. |
184-
| [`@rezi-ui/node`](https://www.npmjs.com/package/@rezi-ui/node) | Node.js/Bun backend with worker and inline execution modes. |
185-
| [`@rezi-ui/native`](https://www.npmjs.com/package/@rezi-ui/native) | N-API addon binding to the Zireael C rendering engine. |
186-
| [`@rezi-ui/jsx`](https://www.npmjs.com/package/@rezi-ui/jsx) | JSX runtime mapping to Rezi VNodes. No React. |
187-
| [`@rezi-ui/testkit`](https://www.npmjs.com/package/@rezi-ui/testkit) | Test utilities, fixtures, and golden test helpers. |
188-
| [`create-rezi`](https://www.npmjs.com/package/create-rezi) | Project scaffolding CLI. |
270+
| `@rezi-ui/core` | Runtime-agnostic widgets, layout, themes |
271+
| `@rezi-ui/node` | Node.js/Bun backend |
272+
| `@rezi-ui/native` | N-API binding to Zireael |
273+
| `@rezi-ui/jsx` | JSX runtime (no React) |
274+
| `@rezi-ui/testkit` | Testing utilities |
275+
| `create-rezi` | Project scaffolding CLI |
189276

190-
## Requirements
277+
---
191278

192-
- **Runtime**: Node.js 18+ (18.18+ recommended) or Bun 1.3+
193-
- **Platforms**: Linux x64/arm64, macOS x64/arm64, Windows x64
194-
- **Terminal**: 256-color or true-color support recommended
279+
## Requirements
195280

196-
Prebuilt native binaries are published for all supported platforms. If a prebuilt binary is unavailable, the package falls back to compiling from source (requires a C toolchain).
281+
- **Node.js 18+** (18.18+ recommended) or **Bun 1.3+**
282+
- Linux x64/arm64
283+
- macOS x64/arm64
284+
- Windows x64
285+
- 256-color or true-color terminal recommended
197286

198-
## Documentation
287+
Prebuilt native binaries are published for supported platforms.
288+
If unavailable, the package compiles from source (requires a C toolchain).
199289

200-
| Resource | Link |
201-
|---|---|
202-
| Docs home | [rtlzeromemory.github.io/Rezi](https://rtlzeromemory.github.io/Rezi/) |
203-
| Getting started | [Install](https://rtlzeromemory.github.io/Rezi/getting-started/install/) · [Quickstart](https://rtlzeromemory.github.io/Rezi/getting-started/quickstart/) · [JSX](https://rtlzeromemory.github.io/Rezi/getting-started/jsx/) |
204-
| Guides | [Concepts](https://rtlzeromemory.github.io/Rezi/guide/concepts/) · [Layout](https://rtlzeromemory.github.io/Rezi/guide/layout/) · [Input & Focus](https://rtlzeromemory.github.io/Rezi/guide/input-and-focus/) · [Styling](https://rtlzeromemory.github.io/Rezi/guide/styling/) |
205-
| Widget catalog | [49 widgets](https://rtlzeromemory.github.io/Rezi/widgets/) |
206-
| API reference | [TypeDoc](https://rtlzeromemory.github.io/Rezi/api/) |
207-
| Architecture | [Overview](https://rtlzeromemory.github.io/Rezi/architecture/) · [Protocol](https://rtlzeromemory.github.io/Rezi/protocol/) |
290+
---
208291

209292
## Contributing
210293

211-
See [CONTRIBUTING.md](CONTRIBUTING.md). Short version:
212-
213294
```bash
214295
git clone https://github.com/RtlZeroMemory/Rezi.git
215-
cd Rezi && git submodule update --init --recursive
216-
npm ci && npm run build && npm test
296+
cd Rezi
297+
git submodule update --init --recursive
298+
npm ci
299+
npm run build
300+
npm test
217301
```
218302

303+
See [CONTRIBUTING.md](CONTRIBUTING.md).
304+
305+
---
306+
219307
## License
220308

221-
[Apache-2.0](LICENSE)
309+
Apache-2.0

0 commit comments

Comments
 (0)