Skip to content

Add widget stability tiers and deterministic daily-driver contracts #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RtlZeroMemory merged 14 commits into from
Feb 13, 2026
Merged

Add widget stability tiers and deterministic daily-driver contracts #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
f0094ea
feat(node): add terminal I/O contract and PTY/ConPTY e2e coverage
RtlZeroMemory Feb 13, 2026
9389a48
docs: remove internal epic wording from terminal I/O contract
RtlZeroMemory Feb 13, 2026
46672c8
test(node): stabilize terminal io contract e2e startup input
RtlZeroMemory Feb 13, 2026
b96df60
test(node): harden terminal io contract e2e against CI flake
RtlZeroMemory Feb 13, 2026
2a28769
test(node): gate full terminal contract e2e off Windows
RtlZeroMemory Feb 13, 2026
6e54de4
test(node): format windows skip message in terminal io e2e
RtlZeroMemory Feb 13, 2026
e736cd2
test(node): bound ConPTY contract commands to avoid CI hangs
RtlZeroMemory Feb 13, 2026
d2ce980
test(node): use cross-platform PTY termination in contract harness
RtlZeroMemory Feb 13, 2026
3529f3a
test(node): skip ConPTY e2e on Windows CI runners
RtlZeroMemory Feb 13, 2026
3bac635
Unify node app config and add deterministic mismatch guards
RtlZeroMemory Feb 13, 2026
087b254
feat(layout): support negative margins and deterministic overlap hit …
RtlZeroMemory Feb 13, 2026
1014673
Add widget stability tiers and daily-driver contracts
RtlZeroMemory Feb 13, 2026
e4de1a6
Add full-catalog widget stability tiers
RtlZeroMemory Feb 13, 2026
d44da23
Merge remote-tracking branch 'origin/main'
RtlZeroMemory Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 76 additions & 66 deletions docs/widgets/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,118 +11,128 @@ app.view((state) =>
);
```

## Stability

Widget stability tiers and guarantees are documented in [Widget Stability](stability.md).

Tier labels used in this catalog:

- `stable`: semver-protected behavior contract with deterministic regression tests.
- `beta`: core invariants are tested; contract may evolve.
- `experimental`: no compatibility guarantees.

## Widget Categories

### Primitives

Foundation widgets for layout and content:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Text](text.md) | Display text with optional styling | No |
| [Box](box.md) | Container with border, padding, and title | No |
| [Row / Column](stack.md) | Horizontal and vertical stack layouts | No |
| [Spacer](spacer.md) | Fixed-size or flexible spacing | No |
| [Divider](divider.md) | Visual separator line | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Text](text.md) | Display text with optional styling | No | `stable` |
| [Box](box.md) | Container with border, padding, and title | No | `stable` |
| [Row / Column](stack.md) | Horizontal and vertical stack layouts | No | `stable` |
| [Spacer](spacer.md) | Fixed-size or flexible spacing | No | `stable` |
| [Divider](divider.md) | Visual separator line | No | `stable` |

### Indicators

Visual feedback and status display:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Icon](icon.md) | Single-character icon from registry | No |
| [Spinner](spinner.md) | Animated loading indicator | No |
| [Progress](progress.md) | Progress bar with variants | No |
| [Skeleton](skeleton.md) | Loading placeholder | No |
| [RichText](rich-text.md) | Multi-styled text spans | No |
| [Kbd](kbd.md) | Keyboard shortcut display | No |
| [Badge](badge.md) | Small status indicator | No |
| [Status](status.md) | Online/offline status dot | No |
| [Tag](tag.md) | Inline label with background | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Icon](icon.md) | Single-character icon from registry | No | `beta` |
| [Spinner](spinner.md) | Animated loading indicator | No | `beta` |
| [Progress](progress.md) | Progress bar with variants | No | `beta` |
| [Skeleton](skeleton.md) | Loading placeholder | No | `beta` |
| [RichText](rich-text.md) | Multi-styled text spans | No | `beta` |
| [Kbd](kbd.md) | Keyboard shortcut display | No | `beta` |
| [Badge](badge.md) | Small status indicator | No | `beta` |
| [Status](status.md) | Online/offline status dot | No | `beta` |
| [Tag](tag.md) | Inline label with background | No | `beta` |

### Form Inputs

Interactive form controls:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Button](button.md) | Clickable button with label | Yes |
| [Input](input.md) | Single-line text input | Yes |
| [Slider](slider.md) | Numeric range input | Yes |
| [Checkbox](checkbox.md) | Toggle checkbox | Yes |
| [Radio Group](radio-group.md) | Single-select options | Yes |
| [Select](select.md) | Dropdown selection | Yes |
| [Field](field.md) | Form field wrapper with label/error | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Button](button.md) | Clickable button with label | Yes | `beta` |
| [Input](input.md) | Single-line text input | Yes | `stable` |
| [Slider](slider.md) | Numeric range input | Yes | `beta` |
| [Checkbox](checkbox.md) | Toggle checkbox | Yes | `beta` |
| [Radio Group](radio-group.md) | Single-select options | Yes | `beta` |
| [Select](select.md) | Dropdown selection | Yes | `beta` |
| [Field](field.md) | Form field wrapper with label/error | No | `beta` |

### Data Display

Tables, lists, and trees:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Table](table.md) | Tabular data with sorting and selection | Yes |
| [Virtual List](virtual-list.md) | Efficiently render large lists | Yes |
| [Tree](tree.md) | Hierarchical data with expand/collapse | Yes |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Table](table.md) | Tabular data with sorting and selection | Yes | `stable` |
| [Virtual List](virtual-list.md) | Efficiently render large lists | Yes | `stable` |
| [Tree](tree.md) | Hierarchical data with expand/collapse | Yes | `beta` |

### Overlays

Modal and popup interfaces:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Layers](layers.md) | Layer stack container | No |
| [Modal](modal.md) | Centered modal dialog | Yes |
| [Dropdown](dropdown.md) | Positioned dropdown menu | Yes |
| [Layer](layer.md) | Generic overlay layer | Varies |
| [Toast](toast.md) | Non-blocking notifications | No |
| [Focus Zone](focus-zone.md) | Focus group for Tab navigation | No |
| [Focus Trap](focus-trap.md) | Constrain focus to region | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Layers](layers.md) | Layer stack container | No | `beta` |
| [Modal](modal.md) | Centered modal dialog | Yes | `beta` |
| [Dropdown](dropdown.md) | Positioned dropdown menu | Yes | `beta` |
| [Layer](layer.md) | Generic overlay layer | Varies | `beta` |
| [Toast](toast.md) | Non-blocking notifications | No | `beta` |
| [Focus Zone](focus-zone.md) | Focus group for Tab navigation | No | `beta` |
| [Focus Trap](focus-trap.md) | Constrain focus to region | No | `beta` |

### Layout

Complex layout components:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Split Pane](split-pane.md) | Resizable split layout | Yes |
| [Panel Group](panel-group.md) | Container for resizable panels | No |
| [Resizable Panel](resizable-panel.md) | Panel within group | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Split Pane](split-pane.md) | Resizable split layout | Yes | `beta` |
| [Panel Group](panel-group.md) | Container for resizable panels | No | `beta` |
| [Resizable Panel](resizable-panel.md) | Panel within group | No | `beta` |

### Advanced

Rich, specialized widgets:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Command Palette](command-palette.md) | Quick command search | Yes |
| [File Picker](file-picker.md) | File browser with selection | Yes |
| [File Tree Explorer](file-tree-explorer.md) | File system tree view | Yes |
| [Code Editor](code-editor.md) | Multi-line code editing | Yes |
| [Diff Viewer](diff-viewer.md) | Unified/side-by-side diff | Yes |
| [Logs Console](logs-console.md) | Streaming log output | Yes |
| [Tool Approval Dialog](tool-approval-dialog.md) | Tool execution review | Yes |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Command Palette](command-palette.md) | Quick command search | Yes | `stable` |
| [File Picker](file-picker.md) | File browser with selection | Yes | `stable` |
| [File Tree Explorer](file-tree-explorer.md) | File system tree view | Yes | `stable` |
| [Code Editor](code-editor.md) | Multi-line code editing | Yes | `beta` |
| [Diff Viewer](diff-viewer.md) | Unified/side-by-side diff | Yes | `beta` |
| [Logs Console](logs-console.md) | Streaming log output | Yes | `beta` |
| [Tool Approval Dialog](tool-approval-dialog.md) | Tool execution review | Yes | `experimental` |

### Charts

Data visualization:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Gauge](gauge.md) | Compact progress with label | No |
| [Sparkline](sparkline.md) | Inline mini chart | No |
| [Bar Chart](bar-chart.md) | Horizontal/vertical bars | No |
| [Mini Chart](mini-chart.md) | Compact multi-value display | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Gauge](gauge.md) | Compact progress with label | No | `beta` |
| [Sparkline](sparkline.md) | Inline mini chart | No | `beta` |
| [Bar Chart](bar-chart.md) | Horizontal/vertical bars | No | `beta` |
| [Mini Chart](mini-chart.md) | Compact multi-value display | No | `beta` |

### Feedback

User feedback and states:

| Widget | Description | Focusable |
|--------|-------------|-----------|
| [Callout](callout.md) | Alert/info message box | No |
| [Error Display](error-display.md) | Error message with retry | Yes |
| [Empty](empty.md) | Empty state placeholder | No |
| Widget | Description | Focusable | Stability |
|--------|-------------|-----------|-----------|
| [Callout](callout.md) | Alert/info message box | No | `beta` |
| [Error Display](error-display.md) | Error message with retry | Yes | `beta` |
| [Empty](empty.md) | Empty state placeholder | No | `beta` |

## Common Patterns

Expand Down
86 changes: 86 additions & 0 deletions docs/widgets/stability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Widget Stability

Rezi uses stability tiers so teams can choose widgets with clear behavior guarantees.

## Tiers

- `stable`: behavior contract and deterministic tests exist; semver guarantees apply to the documented stable surface.
- `beta`: usable and tested for core invariants, but parts of the contract can still evolve.
- `experimental`: no compatibility guarantees; behavior and APIs can change quickly.

## Stable Guarantees

When a widget is marked `stable`, Rezi guarantees:

- deterministic behavior for documented keyboard, pointer, and editing contracts
- deterministic regression tests that pin those contracts in `packages/core/src/**/__tests__`
- no breaking changes to documented stable behavior in minor or patch releases
- any required stable-surface behavior change is treated as semver-major

## Daily Driver Status

These widgets are the EPIC-04 hardening targets and are currently `stable`.

| Widget | Tier | Contract coverage |
|--------|------|-------------------|
| [Input](input.md) | `stable` | Cursor/edit/paste/focus-capture contract tests in `packages/core/src/runtime/__tests__/inputEditor.contract.test.ts` |
| [Table](table.md) | `stable` | Selection/column-width/viewport/row-key tests in `packages/core/src/widgets/__tests__/table.golden.test.ts` and `packages/core/src/app/__tests__/table.renderCache.test.ts` |
| [Virtual List](virtual-list.md) | `stable` | Visible-range/overscan/scroll-clamp/navigation tests in `packages/core/src/widgets/__tests__/virtualList.contract.test.ts` |
| [Command Palette](command-palette.md) | `stable` | Async fetch ordering/stale-cancel/query/nav/escape tests in `packages/core/src/app/__tests__/commandPaletteRouting.test.ts` and `packages/core/src/widgets/__tests__/commandPalette.test.ts` |
| [File Picker](file-picker.md) | `stable` | Expand/collapse/selection/open/toggle contracts in `packages/core/src/app/__tests__/filePickerRouting.contracts.test.ts` |
| [File Tree Explorer](file-tree-explorer.md) | `stable` | Focus/activation/toggle/context-menu contracts in `packages/core/src/app/__tests__/fileTreeExplorer.contextMenu.test.ts` |

## Full Catalog Status

The full catalog is tiered below. `stable` is intentionally conservative and reserved for widgets with hardened behavior contracts.

| Category | Widget | Tier |
|----------|--------|------|
| Primitives | [Text](text.md) | `stable` |
| Primitives | [Box](box.md) | `stable` |
| Primitives | [Row / Column](stack.md) | `stable` |
| Primitives | [Spacer](spacer.md) | `stable` |
| Primitives | [Divider](divider.md) | `stable` |
| Indicators | [Icon](icon.md) | `beta` |
| Indicators | [Spinner](spinner.md) | `beta` |
| Indicators | [Progress](progress.md) | `beta` |
| Indicators | [Skeleton](skeleton.md) | `beta` |
| Indicators | [RichText](rich-text.md) | `beta` |
| Indicators | [Kbd](kbd.md) | `beta` |
| Indicators | [Badge](badge.md) | `beta` |
| Indicators | [Status](status.md) | `beta` |
| Indicators | [Tag](tag.md) | `beta` |
| Form Inputs | [Button](button.md) | `beta` |
| Form Inputs | [Input](input.md) | `stable` |
| Form Inputs | [Slider](slider.md) | `beta` |
| Form Inputs | [Checkbox](checkbox.md) | `beta` |
| Form Inputs | [Radio Group](radio-group.md) | `beta` |
| Form Inputs | [Select](select.md) | `beta` |
| Form Inputs | [Field](field.md) | `beta` |
| Data Display | [Table](table.md) | `stable` |
| Data Display | [Virtual List](virtual-list.md) | `stable` |
| Data Display | [Tree](tree.md) | `beta` |
| Overlays | [Layers](layers.md) | `beta` |
| Overlays | [Modal](modal.md) | `beta` |
| Overlays | [Dropdown](dropdown.md) | `beta` |
| Overlays | [Layer](layer.md) | `beta` |
| Overlays | [Toast](toast.md) | `beta` |
| Overlays | [Focus Zone](focus-zone.md) | `beta` |
| Overlays | [Focus Trap](focus-trap.md) | `beta` |
| Layout | [Split Pane](split-pane.md) | `beta` |
| Layout | [Panel Group](panel-group.md) | `beta` |
| Layout | [Resizable Panel](resizable-panel.md) | `beta` |
| Advanced | [Command Palette](command-palette.md) | `stable` |
| Advanced | [File Picker](file-picker.md) | `stable` |
| Advanced | [File Tree Explorer](file-tree-explorer.md) | `stable` |
| Advanced | [Code Editor](code-editor.md) | `beta` |
| Advanced | [Diff Viewer](diff-viewer.md) | `beta` |
| Advanced | [Logs Console](logs-console.md) | `beta` |
| Advanced | [Tool Approval Dialog](tool-approval-dialog.md) | `experimental` |
| Charts | [Gauge](gauge.md) | `beta` |
| Charts | [Sparkline](sparkline.md) | `beta` |
| Charts | [Bar Chart](bar-chart.md) | `beta` |
| Charts | [Mini Chart](mini-chart.md) | `beta` |
| Feedback | [Callout](callout.md) | `beta` |
| Feedback | [Error Display](error-display.md) | `beta` |
| Feedback | [Empty](empty.md) | `beta` |
Loading
Loading