@rezi-ui/core

The runtime-agnostic TypeScript core package. Contains all widgets, layout, themes, forms, and keybindings with no Node.js-specific dependencies.

Installation

npm install @rezi-ui/core @rezi-ui/node

The @rezi-ui/node package brings in core as a dependency. For custom backends, you can install core directly:

npm install @rezi-ui/core

What This Package Contains

Widgets

All widget constructors are exported through the ui namespace:

import { ui } from "@rezi-ui/core";

ui.text("Hello")
ui.button({ id: "btn", label: "Click" })
ui.column({ gap: 1 }, [...])
ui.table({ id: "tbl", columns: [...], data: [...] })

See the Widget Catalog for the complete list.

Layout Engine

Flexbox-like layout with:

Row and column stacks
Gap spacing between children
Padding and margin
Alignment and justification
Fixed, flex, and percentage sizing
Constraint propagation

Theme System

Semantic color token system with built-in presets:

import { darkTheme, lightTheme, nordTheme, draculaTheme } from "@rezi-ui/core";

app.setTheme(nordTheme);

Create custom themes with createThemeDefinition().

Form Management

Form state management with validation:

import { ui, useForm } from "@rezi-ui/core";

const form = useForm(ctx, {
  initialValues: { email: "", password: "" },
  validate: (values) => {
    const errors: Record<string, string> = {};
    if (!values.email) errors.email = "Required";
    return errors;
  },
  onSubmit: (values) => handleLogin(values),
});

const view = ui.vstack([
  form.field("email", { label: "Email", required: true }),
  form.field("password", { label: "Password", required: true }),
  ui.input(form.bind("email", { id: "email-inline" })),
]);

Keybindings

Modal keybinding system with chord support:

import { parseKeySequence } from "@rezi-ui/core";

app.keys({
  "ctrl+s": { handler: () => save(), description: "Save document" },
  "ctrl+q": { handler: () => app.stop(), description: "Quit application" },
  "g g": { handler: () => scrollToTop(), description: "Scroll to top" }, // Chord: press g twice
});

app.modes({
  normal: {
    "i": { handler: () => app.setMode("insert"), description: "Enter insert mode" },
    "j": { handler: () => moveCursorDown(), description: "Move cursor down" },
  },
  insert: {
    "escape": { handler: () => app.setMode("normal"), description: "Exit insert mode" },
  },
});

const allBindings = app.getBindings();
const normalModeBindings = app.getBindings("normal");
const pending = app.pendingChord; // string | null

Focus Management

Automatic focus traversal with:

Tab/Shift+Tab navigation
Focus zones for grouping
Focus traps for modals
Focus restoration

Binary Protocols

Builders and parsers for the Zireael engine binary formats:

ZRDL: Drawlist builder for rendering commands
ZREV: Event batch parser for input events

Testing Utilities

High-level test helpers are exported from @rezi-ui/core:

import { createTestRenderer, TestEventBuilder, ui } from "@rezi-ui/core";

const renderer = createTestRenderer({ viewport: { cols: 80, rows: 24 } });
const frame = renderer.render(
  ui.column({}, [
    ui.text("Hello"),
    ui.button({ id: "submit", label: "Submit" }),
  ]),
);

frame.findText("Hello");
frame.findById("submit");
frame.findAll("button");
frame.toText();

const events = new TestEventBuilder();
events.pressKey("Enter").type("hello@example.com").click(10, 5).resize(120, 40);

Debug System

Performance instrumentation and frame inspection. For standard app entrypoints, prefer createNodeApp(). createNodeBackend() is used here only for advanced debug-controller wiring.

import { createDebugController, categoriesToMask } from "@rezi-ui/core";
import { createNodeBackend } from "@rezi-ui/node";

const backend = createNodeBackend();
const debug = createDebugController({
  backend: backend.debug,
  terminalCapsProvider: () => backend.getCaps(),
  maxFrames: 1000,
});
await debug.enable({
  minSeverity: "info",
  categoryMask: categoriesToMask(["frame", "error", "perf"]),
});

API Surface

Application

Export	Description
`createApp`	Create application instance (low-level; for normal apps prefer `createNodeApp` from `@rezi-ui/node`)
`App`	Application interface type
`AppConfig`	Configuration options

Widgets

Export	Description
`ui`	Widget factory namespace
`VNode`	Virtual node type
`*Props`	Widget prop types (TextProps, ButtonProps, etc.)

Styling

Export	Description
`rgb`	RGB color helper
`Rgb`	RGB color type
`TextStyle`	Text style type
`darkTheme`, `lightTheme`, etc.	Built-in themes
`createThemeDefinition`	Custom theme creation
`ColorTokens`	Theme token types

Layout

Export	Description
`SpacingValue`	Spacing value type
`SpacingKey`	Named spacing keys
`SPACING_SCALE`	Spacing scale values
`Align`, `JustifyContent`	Alignment types

Forms

Export	Description
`useForm`	Form state hook
`form.bind(...)`, `form.field(...)`	One-line input/field wiring helpers on `useForm` return
`bind`, `bindChecked`, `bindSelect`	Standalone binding helpers for plain state objects
`FormState`, `UseFormReturn`	Form types

Testing

Export	Description
`createTestRenderer`	Runs commit/layout/render pipeline with query helpers (`findText`, `findById`, `findAll`, `toText`)
`TestEventBuilder`	Fluent builder for readable ZREV integration-test input sequences
`encodeZrevBatchV1`	Low-level deterministic ZREV v1 encoder for test events
`makeBackendBatch`	Helper to wrap encoded bytes as `BackendEventBatch`

Keybindings

Export	Description
`parseKeySequence`	Parse key string
`KeyBinding`, `KeyContext`	Keybinding types
`CHORD_TIMEOUT_MS`	Chord timeout constant

Focus

Export	Description
`createLayerRegistry`	Layer management
`pushLayer`, `popLayer`	Layer stack operations
`hitTestLayers`	Layer hit testing

Protocol

Export	Description
`parseEventBatchV1`	Parse ZREV event batch
`createDrawlistBuilderV1`	Create ZRDL builder
`BinaryReader`, `BinaryWriter`	Binary utilities

Icons

Export	Description
`icons`	Icon registry
`resolveIcon`, `getIconChar`	Icon resolution
`FILE_ICONS`, `STATUS_ICONS`, etc.	Icon categories

Debug

Export	Description
`createDebugController`	Debug controller
`createFrameInspector`	Frame inspection
`createEventTrace`	Event tracing
`createErrorAggregator`	Error aggregation

Runtime Constraints

This package enforces strict runtime constraints:

No Node.js APIs : The package must not import Buffer, worker_threads, node:* modules, or any Node-specific APIs.

Deterministic Behavior : Same inputs must produce identical outputs. No random values, no time-dependent behavior in the core logic.

Explicit results for binary APIs : Parsers and builders return result objects (ParseResult, DrawlistBuildResult) rather than throwing on malformed input.

TypeScript Configuration

The package is compiled with strict TypeScript settings:

{
  "strict": true,
  "noImplicitAny": true,
  "exactOptionalPropertyTypes": true,
  "noUncheckedIndexedAccess": true,
  "noPropertyAccessFromIndexSignature": true
}

@rezi-ui/node - Node.js/Bun backend
@rezi-ui/native - Native addon
@rezi-ui/testkit - Testing utilities

@rezi-ui/core

On this page