@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.

Code Editor Syntax Tokenization

@rezi-ui/core also exports reusable tokenizer helpers used by ui.codeEditor(...). These are deterministic, line-based lexical tokenizers that support common language presets:

typescript, javascript, json
go, rust
c, cpp/c++, csharp/c#, java
python, bash
plain fallback

import {
  tokenizeCodeEditorLine,
  tokenizeCodeEditorLineWithCustom,
  type CodeEditorTokenizeContext,
} from "@rezi-ui/core";

const builtIn = tokenizeCodeEditorLine('const n = 1;', {
  language: "typescript",
  lineNumber: 0,
  previousLineState: null,
});

const mixed = tokenizeCodeEditorLineWithCustom("SELECT * FROM users", {
  language: "plain",
  lineNumber: 0,
  previousLineState: null,
  customTokenizer: (line, ctx) => {
    if (line.startsWith("SELECT")) {
      return [{ start: 0, end: 6, kind: "keyword" }];
    }
    return tokenizeCodeEditorLine(line, ctx);
  },
});

Layout Engine

Flexbox-like layout with:

Row and column stacks
Gap spacing between children
Padding and margin
Alignment and justification
Fixed, full/auto, flex, fluid(...), and expr(...) sizing
High-level constraint helpers (e.g. visibilityConstraints, widthConstraints) for common responsive/relational layouts
Per-child alignSelf
flexShrink + flexBasis (including intrinsic min/max content handling)
Wrapped text measurement/render integration
Absolute positioning (position: "absolute" + offsets)
Grid explicit placement + spans (gridColumn/gridRow/colSpan/rowSpan)
Deterministic integer remainder distribution for weighted splits
Layout stability signature coverage for modern container widgets (grid/table/tabs/accordion/modal/virtualList/splitPane/breadcrumb/pagination)
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().

Animation Primitives

Declarative animation hooks and container transitions:

import { defineWidget, ui, useSpring, useTransition } from "@rezi-ui/core";

const AnimatedMeter = defineWidget\<{ target: number; key?: string }>((props, ctx) => {
  const eased = useTransition(ctx, props.target, { duration: 160, easing: "easeOutCubic" });
  const spring = useSpring(ctx, props.target, { stiffness: 180, damping: 22 });

  return ui.box(
    {
      width: Math.round(16 + eased),
      opacity: Math.max(0.35, Math.min(1, spring / 100)),
      transition: { duration: 180, properties: ["size", "opacity"] },
    },
    [ui.text(`Target: ${props.target}`)],
  );
});

Hooks: useTransition, useSpring, useSequence, useStagger.

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.column({}, [
  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);

Performance instrumentation and frame inspection. For standard app entrypoints, prefer createNodeApp(). createNodeApp(...) exposes the underlying backend via app.backend when you need debug/perf instrumentation.

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

const app = createNodeApp({ initialState: {} });
const debug = createDebugController({
  backend: app.backend.debug,
  terminalCapsProvider: () => app.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 (includes `themeTransitionFrames` for animated `setTheme` interpolation)
`App.replaceView(fn)`	Runtime-safe view swap for widget-mode hot reload workflows
`App.replaceRoutes(routes)`	Runtime-safe route table swap for route-managed hot reload workflows

Widgets

Export	Description
`ui`	Widget factory namespace (includes `ui.themed(themeOverride, children)` for scoped theme overrides)
`VNode`	Virtual node type
`*Props`	Widget prop types (TextProps, ButtonProps, etc.)
`tokenizeCodeEditorLine(...)`	Built-in lexical tokenizer for code-editor syntax highlighting
`tokenizeCodeEditorLineWithCustom(...)`	Built-in tokenizer wrapper that prefers custom token output when provided
`normalizeCodeEditorTokens(...)`	Clamps/sorts token ranges into a render-safe form
`CodeEditorSyntaxLanguage`, `CodeEditorSyntaxToken`, `CodeEditorTokenizeContext`, `CodeEditorLineTokenizer`	Tokenizer language and token types

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
`recipe`	Design-system recipe namespace (`button`, `input`, `tabs`, `accordion`, `breadcrumb`, `pagination`, `kbd`, `dropdown`, `tree`, `sidebar`, `toolbar`, etc.)
`WidgetContext.useTheme()`	Composite hook to access current `ColorTokens` (or `null` for legacy themes)

Layout

Export	Description
`SpacingValue`	Spacing value type
`SpacingKey`	Named spacing keys
`SPACING_SCALE`	Spacing scale values
`fluid(...)`	Fluid responsive interpolation helper for layout scalars
`FluidValue`, `FluidValueOptions`	`fluid(...)` value and options types
`ResponsiveValue`, `ViewportBreakpoint`, `ResponsiveViewportSnapshot`	Responsive value and breakpoint types
`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

Animation

Export	Description
`useTransition`, `UseTransitionConfig`	Time-based numeric interpolation hook + config type
`useSpring`, `UseSpringConfig`	Spring-physics numeric animation hook + config type
`useSequence`, `UseSequenceConfig`	Keyframe timeline hook + config type
`useStagger`, `UseStaggerConfig`	Staggered per-item progress hook + config type
`useAnimatedValue`, `UseAnimatedValueConfig`, `AnimatedValue`	Composable transition/spring primitive with value/velocity/activity metadata
`useParallel`, `UseParallelConfig`, `ParallelAnimationEntry`	Parallel transition orchestration hook
`useChain`, `UseChainConfig`	Sequential transition orchestration hook
`PlaybackControl`	Pause/reverse/rate controls for transition/sequence playback
`interpolateRgb`, `interpolateRgbArray`	RGB interpolation helpers for color ramps
`TransitionSpec`, `TransitionProperty`	Container transition prop type + allowed properties

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

Installation

What This Package Contains

Widgets

Code Editor Syntax Tokenization

Layout Engine

Theme System

Animation Primitives

Form Management

Keybindings

Focus Management

Binary Protocols

Testing Utilities

Debug System

API Surface

Application

Widgets

Styling

Layout

Forms

Animation

Testing

Keybindings

Focus

Protocol

Icons

Debug

Runtime Constraints

TypeScript Configuration

On this page