opentui_rust 0.2.1

High-performance terminal UI rendering engine with alpha blending and diffed buffers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# OpenTUI Test Harness

This document mirrors the beads_rust harness pattern for conformance and benchmarking.

## Overview

The harness provides:

1. **Conformance tests** - Fixture-based checks for API behavior and rendering outputs
2. **Benchmarks** - Quick regression checks and Criterion benchmarks
3. **Artifact logging** - Optional JSON/text dumps for debugging

## Quick Start

```bash
# Conformance fixtures
scripts/conformance.sh

# Benchmarks
scripts/bench.sh --quick
scripts/bench.sh --criterion
```

## Script Reference

| Script | Purpose | Duration | When to Use |
|---------|---------|----------|-------------|
| `scripts/conformance.sh` | Fixture-based parity checks | ~10-30s | Behavior changes |
| `scripts/bench.sh --quick` | Fast regression checks | ~10-30s | Perf sanity |
| `scripts/bench.sh --criterion` | Full Criterion suite | 2-5min | Perf work |

## Conformance

Conformance tests run fixture-based checks against `tests/conformance/fixtures/opentui.json`.

```bash
scripts/conformance.sh
scripts/conformance.sh --verbose
scripts/conformance.sh --json
scripts/conformance.sh --filter wrap
scripts/conformance.sh --check-fixtures
```

### Regenerating fixtures from legacy (reference capture)

The legacy capture script recomputes `expected_output` using the legacy engine and overwrites
`tests/conformance/fixtures/opentui.json` deterministically.

```bash
# 1) Build the legacy native library (requires Zig 0.15.2)
cd legacy_opentui/packages/core/src/zig
/opt/zig-0.15.2/zig build -Doptimize=ReleaseFast

# 1.5) Record the legacy commit hash used for capture
cd ../../../..
git rev-parse HEAD

# 2) Run the capture (writes fixtures in this repo)
bun run capture:conformance --lib-path ./src/zig/lib/x86_64-linux/libopentui.so
```

Optional flags:
```bash
bun run capture:conformance \
  --lib-path ./src/zig/lib/x86_64-linux/libopentui.so \
  --input ../../../../tests/conformance/fixtures/opentui.json \
  --output ../../../../tests/conformance/fixtures/opentui.json \
  --captured-at 2026-01-25T00:00:00Z \
  --version 0.1.74
```

**Output**
- Summary JSON: `target/test-artifacts/conformance_summary.json`
- Artifacts: `target/test-artifacts/conformance/<test>/`

## Benchmarks

```bash
scripts/bench.sh --quick
scripts/bench.sh --criterion
scripts/bench.sh --save baseline-v1
scripts/bench.sh --baseline baseline-v1
```

**Output**
- Summary JSON: `target/test-artifacts/benchmark_summary.json`
- Artifacts: `target/test-artifacts/benchmark/`
- Criterion reports: `target/criterion/`

### Highlight Benchmarks

The `highlight` benchmark suite targets the syntax highlighting hot paths.

```bash
cargo bench --bench highlight
```

**Targets (guidance, not hard limits):**

| Operation | Target |
|-----------|--------|
| Single line tokenize | <1μs |
| Incremental update (1 line) | <1ms |
| Full highlight (1000 lines) | <50ms |
| Full highlight (10000 lines) | <500ms |
| Theme switch | <100μs |

`highlight_memory_estimate` reports token count and text bytes as a lightweight
allocation proxy for highlight data structures.

## Artifact Logging

Enable detailed artifact logging (tests only):

```bash
HARNESS_ARTIFACTS=1 cargo test --test conformance -- --nocapture
HARNESS_PRESERVE_SUCCESS=1 cargo test --test conformance
```

Artifacts are written to `target/test-artifacts/<suite>/<test>/`.

## Environment Variables

| Variable | Default | Description |
|---------|---------|-------------|
| `HARNESS_ARTIFACTS` | 0 | Enable artifact logging for tests |
| `HARNESS_PRESERVE_SUCCESS` | 0 | Keep artifacts on success |
| `HARNESS_ARTIFACTS_DIR` | target/test-artifacts | Base artifacts directory |
| `CONFORMANCE_TIMEOUT` | 120 | Per-test timeout (seconds) |
| `BENCH_TIMEOUT` | 300 | Benchmark timeout (seconds) |
| `BENCH_CONFIRM` | 0 | Skip full benchmark confirmation |

## Troubleshooting

**Conformance fixtures missing**
```bash
scripts/conformance.sh --check-fixtures
```

**Benchmarks too slow**
```bash
scripts/bench.sh --quick
```