release: promote Rezi to beta (v0.1.0-beta.1) (#414)

* docs: reposition README, roadmap, and status wording for beta

Rewrite the README around the beta line: status and versioning policy,
requirements with the prebuilt binary matrix, a short architecture
overview, and contribution entry points. Refresh ROADMAP.md to reflect
shipped work and the path to 1.0, and update status wording from
pre-alpha to beta across the docs index, widget stability pages,
protocol versioning notes, and constraint guides.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(jsx): pin JSX component parity to the ui.* factory surface

The JSX component layer is maintained by hand. These tests assert that
every ui.* factory has a PascalCase component export, that every
component maps back to a factory, and that every component is
re-exported from the package index, so the wrapper layer cannot drift
silently when core widgets change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore(release): prepare v0.1.0-beta.1

Set all workspace and template versions to 0.1.0-beta.1, sync the
lockfile, and add the changelog entry. Declare Bun support in the
testkit engines field, matching the other runtime packages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: RtlZeroMemory

CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 
 ## [Unreleased]
 
+## [0.1.0-beta.1] - 2026-06-11
+
+### Changed
+
+- **project**: Promoted Rezi from alpha to beta. The core public API is recorded and diffed in CI, widget guarantees are documented as stability tiers, and remaining pre-1.0 breaking changes will be batched and documented with migration notes.
+- **testkit**: Declared Bun support (`bun >= 1.3.0`) in `engines`, matching the other runtime packages.
+
+### Added
+
+- **jsx**: Parity tests that pin the JSX component surface to the `ui.*` factory surface in both directions, so the hand-maintained wrapper layer cannot drift silently.
+
+### Documentation
+
+- **README**: Rewritten for the beta line: status and versioning policy, requirements and the prebuilt binary matrix, an architecture overview, and contribution entry points.
+- **ROADMAP**: Refreshed to reflect shipped work (Bun support, CI benchmark comparisons) and the path to 1.0.
+- **docs**: Status wording updated from pre-alpha to beta across the docs index, widget stability pages, and protocol versioning notes.
+
 ## [0.1.0-alpha.81] - 2026-06-04
 
 ### Release Infrastructure

README.md

@@ -1,33 +1,32 @@
 # Rezi
 
-> **Status: pre-alpha.** Rezi is under active development. Public APIs, native ABI details, and behavior may change between releases. It is not yet recommended for production workloads.
+[![CI](https://github.com/RtlZeroMemory/Rezi/actions/workflows/ci.yml/badge.svg)](https://github.com/RtlZeroMemory/Rezi/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40rezi-ui%2Fcore)](https://www.npmjs.com/package/@rezi-ui/core)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-Rezi is a TypeScript framework for building serious terminal applications on Node.js and Bun. It gives you structured layout, focus and input handling, routing, widgets, testing tools, and a native-backed rendering pipeline powered by the [Zireael engine](https://github.com/RtlZeroMemory/Zireael) written in C.
+Rezi is a TypeScript framework for building terminal applications on Node.js and Bun. It provides structured layout, focus and input handling, routing, widgets, and testing tools, with rendering handled by [Zireael](https://github.com/RtlZeroMemory/Zireael), a terminal engine written in C.
 
 **Links:** [Website](https://rezitui.dev/) · [Docs](https://rezitui.dev/docs/) · [Quickstart](https://rezitui.dev/docs/getting-started/quickstart/) · [Widgets](https://rezitui.dev/docs/widgets/) · [Benchmarks](https://rezitui.dev/docs/benchmarks/)
 
 ![Rezi command console demo](assets/REZICONSOLE3.gif)
 
-## What Rezi Is For
+## Status
 
-Rezi is aimed at dashboards, control planes, internal tools, log viewers, and developer workflows that need more than line-oriented output: multi-panel layouts, routed screens, focusable controls, forms, tables, overlays, testing support, and predictable behavior under keyboard and mouse input.
+Rezi is in **beta**. The core API — the app model, layout, input routing, theming, and the widget surface — is stable enough to build on, and the public API of `@rezi-ui/core` is recorded and diffed in CI. Breaking changes still happen before 1.0, but they are deliberate, batched, and documented in the [changelog](CHANGELOG.md) with migration notes.
 
-## Why Rezi
+Individual widgets carry explicit [stability tiers](docs/widgets/stability.md) (`stable`, `beta`, `experimental`), so the guarantees that apply to what you use are spelled out rather than implied.
 
-- Structured app model for real TUI workflows
-- Declarative widget API without requiring React
-- Native-backed framebuffer diffing and terminal output through Zireael
-- First-party widgets for forms, tables, overlays, routing, charts, and command flows
-- Reproducible rendering and input contracts for behavior-first tests
+## What Rezi Is For
 
-## What Rezi Includes
+Dashboards, control planes, internal tools, log viewers, agent consoles, and developer workflows that need more than line-oriented output: multi-panel layouts, routed screens, focusable controls, forms, tables, overlays, and predictable behavior under keyboard and mouse input.
+
+## Why Rezi
 
-- Layout primitives for rows, columns, grids, panels, spacing, and layered screens
-- Interactive widgets such as buttons, inputs, selects, checkboxes, radios, sliders, tabs, tables, virtual lists, trees, dialogs, dropdowns, and toasts
-- Graphics and data-display widgets including canvas, charts, gauges, sparklines, heatmaps, and image support
-- Application primitives for focus management, keybindings, routing, theming, and controlled state updates
-- Testing utilities for render assertions, routing and focus behavior, and replayable input workflows
-- A native-backed rendering path through Zireael for layout, framebuffer diffing, and terminal output
+- A structured app model instead of a rendering loop you assemble yourself
+- A declarative widget API that does not require React
+- Native framebuffer diffing and terminal output through a fuzz-tested C engine
+- First-party widgets for forms, tables, trees, overlays, charts, file pickers, and command palettes
+- Reproducible rendering and input contracts, so application behavior is testable
 
 ## Example
 
@@ -63,12 +62,6 @@ app.keys({ q: () => app.stop() });
 await app.run();
 ```
 
-Install:
-
-```bash
-npm install @rezi-ui/core @rezi-ui/node
-```
-
 ## Quick Start
 
 ```bash
@@ -85,47 +78,85 @@ cd my-app
 bun run start
 ```
 
-## Public Templates
+Or add Rezi to an existing project:
+
+```bash
+npm install @rezi-ui/core @rezi-ui/node
+```
+
+Three templates are available:
 
-- `minimal` - small single-screen starter for focused utilities
-- `cli-tool` - routed multi-screen starter for product-style terminal tools
-- `starship` - larger command-console showcase with routing, charts, canvas, forms, and overlays
+- `minimal` — single-screen starter for focused utilities
+- `cli-tool` — routed multi-screen starter for product-style terminal tools
+- `starship` — large command-console showcase with routing, charts, canvas, forms, and overlays
 
-## Starship Demo
+Start with `minimal` or `cli-tool`. Use `starship` (`npm create rezi my-console -- --template starship`) when you want the full surface area in one app.
 
-Use the template when you want a larger example of Rezi's app architecture:
+## Requirements
 
-```bash
-npm create rezi my-console -- --template starship
-```
+- Node.js 18+ or Bun 1.3+
+- Linux, macOS, or Windows
 
-The demo intentionally shows the broad surface area. For new applications, start with `minimal` or `cli-tool` unless you specifically want the full showcase.
+`@rezi-ui/native` ships prebuilt binaries for Linux x64/arm64 (glibc), macOS x64/arm64, and Windows x64/arm64, so `npm install` never compiles C. Alpine/musl is not yet supported. Terminal capabilities — color depth, mouse, bracketed paste, synchronized output — are probed at startup, and output adapts to what the terminal reports.
 
-## Feature Maturity
+## How It Works
 
-Rezi is still pre-alpha, but not every feature has the same risk profile. Core layout, input, routing, tables, virtual lists, command palette, and file-picker workflows are the current hardening focus. Richer surfaces such as advanced graphics, charts, code/editor-style widgets, and specialized dialogs should be treated as beta or experimental while the public API settles.
+Your application builds a widget tree in TypeScript. `@rezi-ui/core` lays it out and serializes the result into a compact binary drawlist. The Zireael engine validates the drawlist, diffs it against the previous frame, and writes the minimal terminal update; in the other direction it parses keyboard, mouse, paste, and resize input into event batches that core routes through focus and keybindings. The protocol at this boundary is versioned and [documented](docs/protocol/zrdl.md).
+
+The API stays in TypeScript; the hot path stays in C; both sides are tested in isolation. See [Architecture](docs/architecture/index.md).
 
 ## Packages
 
 | Package | Purpose |
 |---|---|
-| `@rezi-ui/core` | Widget API, layout, routing, focus, forms, themes, testing hooks |
-| `@rezi-ui/node` | Node/Bun backend, terminal I/O, scheduling, native integration |
-| `@rezi-ui/native` | N-API binding to the Zireael engine |
-| `@rezi-ui/jsx` | Optional JSX runtime over the core API |
-| `@rezi-ui/testkit` | Testing utilities |
-| `create-rezi` | Project scaffolding CLI |
+| [`@rezi-ui/core`](https://www.npmjs.com/package/@rezi-ui/core) | Widget API, layout, routing, focus, forms, themes, test renderer |
+| [`@rezi-ui/node`](https://www.npmjs.com/package/@rezi-ui/node) | Node/Bun backend: terminal I/O, scheduling, native engine integration |
+| [`@rezi-ui/native`](https://www.npmjs.com/package/@rezi-ui/native) | N-API binding to the Zireael engine, with prebuilt binaries |
+| [`@rezi-ui/jsx`](https://www.npmjs.com/package/@rezi-ui/jsx) | Optional JSX runtime over the core API |
+| [`@rezi-ui/testkit`](https://www.npmjs.com/package/@rezi-ui/testkit) | Assertions, snapshot helpers, and deterministic fuzz utilities |
+| [`create-rezi`](https://www.npmjs.com/package/create-rezi) | Project scaffolding CLI |
+
+All publishable packages share one version and release together.
+
+## Versioning
+
+Rezi follows semantic versioning, applied through stability tiers during the beta line:
+
+- `stable` widgets and the core app, layout, and routing APIs do not change documented behavior without a changelog callout and a migration note
+- `beta` widgets are tested for their core invariants; contract details may still evolve
+- `experimental` widgets may change at any time
+
+The full tier assignment per widget is in [Widget Stability](docs/widgets/stability.md).
+
+## Testing
+
+Applications are testable without a terminal: `@rezi-ui/core` includes a deterministic test renderer, and `@rezi-ui/testkit` adds assertions, frame snapshots, and seeded fuzz helpers on top of `node:test`. The framework holds itself to the same bar — behavior-contract tests, golden-frame tests, fuzzed parsers on both sides of the native boundary, and a Linux/macOS/Windows × Node 18/20/22 × Bun CI matrix. See the [testing guide](docs/guide/testing.md).
 
 ## Performance
 
-Rezi is designed to stay fast on structured terminal workloads. Benchmark methodology, caveats, and committed result snapshots are documented in [BENCHMARKS.md](BENCHMARKS.md) and [docs/benchmarks.md](docs/benchmarks.md).
+Rezi is designed to stay fast on structured terminal workloads. Benchmark methodology, caveats, and committed result snapshots are documented in [BENCHMARKS.md](BENCHMARKS.md) and on the [benchmarks page](docs/benchmarks.md).
 
 ## Documentation
 
 - [Install](docs/getting-started/install.md)
 - [Quickstart](docs/getting-started/quickstart.md)
-- [Create Rezi](docs/getting-started/create-rezi.md)
-- [Widget Catalog](docs/widgets/index.md)
+- [Widget catalog](docs/widgets/index.md)
 - [Examples](docs/getting-started/examples.md)
 - [Architecture](docs/architecture/index.md)
 - [Benchmarks](docs/benchmarks.md)
+
+## Contributing
+
+Bug reports and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md); the short version:
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+For reporting security issues, see [SECURITY.md](SECURITY.md).
+
+## License
+
+[Apache-2.0](LICENSE)

ROADMAP.md

@@ -2,30 +2,25 @@
 
 This roadmap is directional only. It is not a commitment to scope, ordering, or dates. Release decisions are based on shipped, tested behavior.
 
-## Alpha direction (near term)
+## Beta (current)
 
-- Close remaining `createApp` lifecycle edge cases
+- Hold the documented API surface stable; batch any remaining breaking changes with migration notes
 - Continue frame coalescing and allocation reduction work
-- Add targeted example applications
-
-### Completed in Sprints 1-5
-
-- Widget capability drift -> fixed via protocol registry.
-- Narrow action model -> extended routed action model shipped.
-- Overlay fragmentation -> unified overlay system shipped.
-- DS recipe gap -> recipes wired across major interactive widgets.
-- Animation lifecycle gap -> `onComplete` callback support added to animation hooks.
+- Harden widget composition APIs (`defineWidget`)
+- Expand recipes and real-world examples; refresh the oldest documentation pages
+- Deprecate raw string `expr(...)` constraints in favor of the typed constraint helpers
 
-## Beta direction (medium term)
+## Toward 1.0
 
-- Harden widget composition APIs (`defineWidget`)
-- Expand recipes and patterns documentation
-- Add CI benchmark regression tracking
-- Evaluate plugin/extension architecture
+- Graduate or prune `experimental`-tier widgets so the 1.0 surface is intentional
+- Freeze drawlist and event protocol guarantees together with Zireael
+- Streaming markdown widget and an agent-console template
+- Developer tooling: layout, focus, and frame-timing inspection overlay
+- Code coverage reporting and blocking benchmark regression gates in CI
 
-## Stable direction (longer term)
+## After 1.0
 
-- Explore additional runtime backends (for example Bun, Deno) via `@rezi-ui/core` portability
-- Add platform capabilities as Zireael evolves
-- Improve accessibility coverage
-- Support a community widget ecosystem
+- WebAssembly build of the Zireael engine as a portable fallback and a browser embedding target
+- Plugin and community widget ecosystem
+- Additional runtime backends (for example Deno) via `@rezi-ui/core` portability
+- Accessibility coverage improvements

docs/design-principles.md

@@ -1,6 +1,6 @@
 # Design Principles
 
-This page records the layout rules Rezi follows in the current alpha line.
+This page records the layout rules Rezi follows in the current beta line.
 
 ---
 
@@ -22,7 +22,7 @@ Use the first mechanism that fits the need:
   - `visibilityConstraints`, `widthConstraints`, `heightConstraints`, `spaceConstraints`, `groupConstraints`, `conditionalConstraints`
 - Raw `expr("...")` is the escape hatch for custom rules.
 - `%` size strings and responsive-map layout constraints (`{ sm, md, ... }`) are not part of the public API.
-- `grid.columns` accepts `number | string` in alpha; `columns: expr(...)` is invalid.
+- `grid.columns` accepts `number | string` in the beta line; `columns: expr(...)` is invalid.
 - Layout-driven visibility uses `display: ...` constraints; business logic visibility uses `show(...)`/`when(...)`/`maybe(...)`/`match(...)`.
 
 ---

docs/guide/constraint-recipes.md

@@ -120,9 +120,9 @@ width: conditionalConstraints.ifThenElse(
 
 ---
 
-## 6) Responsive grid (alpha contract)
+## 6) Responsive grid (beta contract)
 
-Because `grid.columns: expr(...)` is intentionally invalid in alpha, build two grids and switch with `display`.
+Because `grid.columns: expr(...)` is intentionally invalid in the beta line, build two grids and switch with `display`.
 
 ```ts
 ui.column({ gap: 1 }, [

docs/guide/constraints.md

@@ -1,6 +1,6 @@
 # Constraints Guide
 
-Rezi's helper-first constraints API is the canonical way to express derived layout relationships in the alpha branch.
+Rezi's helper-first constraints API is the canonical way to express derived layout relationships in the beta line.
 Use `expr("...")` as an advanced escape hatch when helper primitives do not cover the case.
 
 See also:
@@ -19,7 +19,7 @@ See also:
 - Use `display: expr("...")` only as an escape hatch when a helper does not fit the visibility rule.
 - Keep business-logic visibility in `show(...)`, `when(...)`, `match(...)`, or `maybe(...)`.
 - `%` layout size strings and responsive-map layout constraints (`{ sm, md, ... }`) are removed.
-- `grid.columns` supports `number | string` only in alpha. `columns: expr(...)` is intentionally invalid.
+- `grid.columns` supports `number | string` only in the beta line. `columns: expr(...)` is intentionally invalid.
 
 ## Supported References
 
@@ -104,7 +104,7 @@ Notes:
 
 ## Grid Contract (Important)
 
-`grid.columns` does not currently accept `expr(...)` in alpha.
+`grid.columns` does not currently accept `expr(...)` in the beta line.
 
 Supported:
 
@@ -116,7 +116,7 @@ ui.grid({ columns: "14 auto 1fr", gap: 1 }, ...children)
 Not supported:
 
 ```ts
-ui.grid({ columns: expr("max(1, floor(parent.w / 24))") }, ...children) // invalid in alpha
+ui.grid({ columns: expr("max(1, floor(parent.w / 24))") }, ...children) // invalid in the beta line
 ```
 
 For responsive behavior, compose multiple grids and switch with `display: expr(...)`.

docs/guide/debugging-constraints.md

@@ -46,7 +46,7 @@ Fix:
 Cause: prop contract violations, for example:
 - `%` size strings
 - responsive-map layout constraints (`{ sm, md, ... }`)
-- `grid.columns: expr(...)` (invalid in alpha)
+- `grid.columns: expr(...)` (invalid in the beta line)
 
 Fix:
 - Migrate to helper constraints / `expr` where supported

docs/guide/layout-decision-tree.md

@@ -31,7 +31,7 @@ Need to set a size?
 
 5. **2D arrangement**
    - Use: `ui.grid({ columns: number | string, ... })`
-   - For responsive columns in alpha: compose multiple grids and switch via `display`
+   - For responsive columns in the beta line: compose multiple grids and switch via `display`
 
 ---
 

docs/guide/layout.md

@@ -244,8 +244,8 @@ When these child-constraint props are passed to unsupported widget kinds (for ex
 Responsive layout notes:
 
 - Use `fluid(min, max, options?)` to interpolate deterministically between breakpoints (`sm`, `md`, `lg`, `xl`) with floor semantics and clamped bounds.
-- `%` size strings and responsive-map layout constraints (`{ sm, md, lg, xl }`) are removed in the breaking alpha. Use `expr("steps(...)")` or `fluid(...)`.
-- `grid.columns` currently accepts `number | string` only (alpha contract). `columns: expr(...)` is invalid.
+- `%` size strings and responsive-map layout constraints (`{ sm, md, lg, xl }`) were removed during the alpha line. Use `expr("steps(...)")` or `fluid(...)`.
+- `grid.columns` currently accepts `number | string` only (beta contract). `columns: expr(...)` is invalid.
 
 ```typescript
 import { fluid, ui } from "@rezi-ui/core";

docs/index.md

@@ -2,7 +2,7 @@
 
 Rezi is a code-first terminal UI framework for Node.js and Bun. It uses a declarative widget API, deterministic input routing, and native-backed rendering through the [Zireael](https://github.com/RtlZeroMemory/Zireael) C engine.
 
-> **Status: pre-alpha**. Rezi is under active development. Public APIs, ABI details, and behavior may change between releases. It is not yet recommended for production workloads.
+> **Status: beta**. The core API is stable and recorded against a public API report. Breaking changes before 1.0 are batched and documented in the changelog with migration notes. Per-widget guarantees are listed in [Widget Stability](widgets/stability.md).
 
 ## Focus