DOCSEARCHbyAlgolia
Submit Docs

rezi

repository·main·Indexed 20 days ago

https://github.com/rtlzeromemory/rezi

A TypeScript framework for building structured terminal applications on Node.js and Bun. It features a declarative widget API, layout management, routing, and focus handling, powered by the Zireael C-based terminal engine. The ecosystem includes @rezi-ui/core for runtime-agnostic UI construction and animations, @rezi-ui/node for application development, and create-rezi for scaffolding projects with minimal, cli-tool, or starship templates.

Tokens
245.3K
Snippets
738
Records
1.1K
Agent score
70%

What's inside rezi

  1. Overview of @rezi-ui/testkit

    main

    The @rezi-ui/testkit package provides essential testing infrastructure for the Rezi ecosystem. It includes:

    • Test utilities: Helpers for writing and managing tests.
    • Deterministic fuzz helpers: Tools for performing fuzz testing using reproducible seeds.
    • Golden fixtures: Standardized data sets used for regression testing and snapshot comparisons.

    Note on Fuzzing: Fuzz seeds used in this package are unsigned 32-bit integers. This allows for deterministic reproduction of edge cases found during fuzzing sessions.

    Most application developers will not need to depend on this package directly, as it is primarily intended for library authors and core contributors working on Rezi components.

  2. Overview of Starship template features and components

    main

    The starship template is an advanced showcase of Rezi's capabilities, demonstrating a multi-deck operations console. It includes:

    Core Architecture

    • Routing + shell: Uses createNodeApp({ routes }) with routerBreadcrumb() and routerTabs() for route-aware navigation and key command dispatch.
    • Layouts: Provides structural components like ui.appShell, ui.page, ui.panel, ui.card, ui.grid, ui.masterDetail, ui.splitPane, and ui.center.
    • Data & Forms: Includes ui.table, ui.tree, ui.virtualList, ui.form, ui.field, ui.actions, ui.select, ui.radioGroup, and ui.slider.
    • Visualization: Features ui.canvas (braille), ui.gauge, ui.progress, ui.sparkline, ui.lineChart, ui.barChart, ui.scatter, and ui.heatmap.
    • Overlays: Manages UI layers via ui.layers, ui.layer, ui.modal, ui.dialog, ui.toastContainer, and ui.commandPalette.
    • Composition Hooks: Advanced animation and lifecycle hooks including defineWidget, useTransition, useSpring, useSequence, useStagger, useInterval, and useAsync.
    • Render Helpers: Logic helpers like show, when, match, maybe, each, and eachInline.

  3. What is Rezi?

    main

    Rezi is a code-first terminal UI framework designed for Node.js and Bun. It provides a declarative widget API and uses deterministic input routing. Rendering is handled via native-backed layout and framebuffer diffing through the Zireael C engine.

    Key Features:

    • ui.* widget factories as the primary API.
    • Deterministic rendering and event routing.
    • Native-backed layout and framebuffer diffing.
    • Explicit control over focus, forms, routing, and themes.
    • Optional JSX support via @rezi-ui/jsx.

  4. Overview of @rezi-ui/core

    main

    @rezi-ui/core is a runtime-agnostic TypeScript core for the Rezi ecosystem. It provides the fundamental building blocks for UI construction, animation, and layout management.

    Key capabilities include:

    • Widget Construction: Access to widget constructors via the ui.* namespace.
    • Declarative Animations: Hooks for managing complex UI motion, including useTransition, useSpring, useSequence, and useStagger.
    • Box Transitions: Specialized props for handling transitions and opacity (e.g., transition, opacity).
    • Core UI Logic: Handles reconciliation, layout, focus management, and routing.
    • Low-level primitives: Manages drawlist building using ZRDL and event batch parsing using ZREV.

    Note: For most application development, you should use the @rezi-ui/node package, which includes this core as a dependency.

  6. Compare Rezi (native) vs OpenTUI performance metrics

    main

    The benchmark results compare Rezi (native) against OpenTUI across several performance dimensions. Key metrics include:

    • Mean: Average execution time.
    • ops/s: Operations per second (throughput).
    • Wall: Wall-clock time.
    • CPU user/sys: CPU time spent in user and system modes.
    • Peak RSS/Heap: Memory usage (Resident Set Size and Heap).
    • Bytes/PTY Bytes: Data throughput in bytes.

    Commonly tested scenarios include:

    • startup: Initial framework boot time.
    • tree-construction: Time to build UI trees with varying item counts (10, 100, 500, 1000).
    • rerender: Time taken for UI re-renders.
    • content-update: Time for content updates.
    • layout-stress: Stress testing layout with specific rows and columns.
    • scroll-stress: Stress testing scrolling with large item counts.
    • virtual-list: Performance of virtualized lists with high item counts.
    • tables: Performance of table rendering.
    • terminal-*: Various terminal-specific operations like frame filling, screen transitions, and input latency.

  7. Recommended patterns for Rezi applications

    main

    Rezi recommends several architectural patterns to ensure applications are testable, predictable, and performant. Key patterns include:

    • Template project structure: Ensures separation of concerns and high testability.
    • Reducer with typed actions: Provides pure, testable, and debuggable state logic.
    • Pure screen view functions: Ensures predictable rendering and easy testing.
    • ui.* + defineWidget(): Enables type-safe composition when local state is required.
    • ui.errorBoundary(): Provides graceful failure isolation.
    • Centralized keybindings: Makes keybindings discoverable and testable while preventing duplication.
    • Decoupled testing: Separate tests for reducers, screens, and keybindings allow for fast, focused testing without requiring a full UI harness.
    • Theme definitions: Ensures consistent styling and supports NO_COLOR environments.
    • Performance optimizations: Use useMemo, proper keys, and virtualList for efficient rendering at scale.
    • Styling isolation: Use borderStyle for pane chrome to prevent style leaking into child widgets, and focusConfig for embedded widgets to avoid redundant focus visuals in custom chrome.

  8. Compare Rezi, OpenTUI, and Bubble Tea performance

    main

    Benchmark results compare the performance of Rezi (native), OpenTUI, and Bubble Tea (Go) across various metrics including startup time, tree construction, rerendering, and terminal operations.

    Common metrics reported in the results include:

    • Mean: Average execution time.
    • ops/s: Operations per second.
    • Wall: Wall-clock time.
    • Peak RSS: Peak Resident Set Size (memory).
    • Peak Heap: Peak Heap memory usage.
    • PTY Bytes: Bytes sent/received via PTY.

  9. Explore Rezi example applications

    main

    The repository contains several example applications designed for different learning paths:

    • examples/hello-counter: Best for beginners. Demonstrates a minimal flow involving state, a view, and a button using the Node backend.
    • examples/raw-draw-demo: Best for low-level rendering exploration. Demonstrates the draw() rendering mechanism.
    • examples/gallery: Best for UI exploration. Provides a widget gallery and a scene library for testing widget demos.

    Note on the Validation Surface: examples/regression-dashboard is a specialized dashboard used to validate layout, rendering, focus, and interaction behavior after framework changes. It is not recommended as a starting point for learning the framework.

  10. Use @rezi-ui/testkit for Rezi application and package tests

    main

    The @rezi-ui/testkit package provides testing utilities, fixtures, and helpers designed for Rezi applications and package-level testing. It includes tools for protocol/drawlist testing, deterministic fuzzing, and snapshot regression testing.

    Key Features

    • Fixtures: Golden byte blobs for protocol and drawlist tests.
    • Golden Helpers: assertBytesEqual and hexdump for stable diffs.
    • Deterministic Fuzz Helpers: runFuzz, fuzzTest, and createRng for seeded fuzz-lite and failure-injection tests.
    • Snapshot Helper: matchesSnapshot for text-frame regression tests.
    • Node.js Integration: Convenience re-exports of node:test and node:assert (available in Node environments only).

    Installation Note

    If you are developing tests outside of the main repository, ensure you install a released version of @rezi-ui/testkit that matches your @rezi-ui/core version.

    import { assert, describe, matchesSnapshot, readFixture, test } from "@rezi-ui/testkit";

describe("zrev parser", () => {
  test("accepts valid v1 fixture", async () => {
    const bytes = await readFixture("zrev-v1/valid/key.bin");
    assert.ok(bytes.byteLength > 0);
  });
});

test("snapshot rendered frame text", () => {
  matchesSnapshot("hello\nworld", "example-frame");
});

  11. Use @rezi-ui/node instead of @rezi-ui/native

    main

    The @rezi-ui/native package is a Rust + napi-rs Node-API addon that hosts the Zireael C engine. It provides a minimal, safe JS API for the Node backend.

    Note: Most applications should not use this package directly. Instead, install and use @rezi-ui/node, which manages this package as a dependency.

  12. What is Rezi and how does it differ from React?

    main

    Rezi is a code-first terminal UI framework for Node.js and Bun that uses a declarative widget API.

    Unlike React, Rezi does not use a virtual DOM. Instead, it uses a binary drawlist protocol (ZRDL) to send rendering commands to a native C engine (Zireael) for high-performance terminal I/O.

    Key architectural differences:

    • No Virtual DOM: Rendering is handled via a binary protocol to a native engine.
    • Stateless View Functions: The root view function is pure and stateless. Stateful logic is encapsulated in reusable widgets using defineWidget with hooks like useState, useRef, and useEffect.
    • Deterministic Rendering: Designed for terminal-specific constraints with no side effects in the view function.