syntaxis/core/crates/tui/BENCHMARKS.md

# Performance Benchmarks for syntaxis-tui

This document describes the performance benchmarking infrastructure for the syntaxis-tui TUI application.

## Overview

Performance benchmarks are implemented using the **criterion** benchmarking framework. They measure critical paths in the TUI to ensure responsiveness and smooth user experience.

## Performance Targets

- **Rendering**: <16ms per frame (60 FPS target)
- **Event Handling**: <1ms for keyboard events
- **State Mutations**: <0.5ms for navigation, <0.1ms for flag operations
- **Memory**: No allocations in hot paths where possible

## Benchmark Suites

### 1. rendering_performance
**Purpose**: Measure rendering latency and layout computation efficiency

**Benchmarks**:
- Empty projects list rendering
- Project list rendering with 5, 10, 20 projects
- Various terminal sizes (40x10, 80x24, 120x40, 200x60)
- Layout computation at different scales

**Target**: <16ms per complete render cycle for responsive 60 FPS

### 2. event_handling
**Purpose**: Measure event processing latency to ensure UI responsiveness

**Benchmarks**:
- Keyboard event creation and parsing
- Event routing and dispatch
- List navigation with wrapping
- Screen transitions (projects → detail → security)
- Dirty flag operations (set, clear, conditional checks)

**Target**: <1ms for event handling (allows 250ms event poll timeout in main loop)

### 3. state_mutations
**Purpose**: Measure the performance of state mutation operations

**Benchmarks**:
- String mutations (project name, description)
- Vector operations (create, access, resize)
- Enum variant creation
- Option<T> operations
- Numeric mutations (index wrapping, counting)
- Combined mutations (screen transitions with state reset)

**Target**: <0.5ms for most operations, <0.1ms for primitive operations

## Running Benchmarks

### Run all benchmarks
```bash
cd crates/syntaxis-tui
cargo bench
```

### Run specific benchmark suite
```bash
cargo bench --bench rendering_performance
cargo bench --bench event_handling
cargo bench --bench state_mutations
```

### Generate HTML reports
```bash
# Reports are automatically generated in: target/criterion/
# Open in browser: target/criterion/report/index.html
```

### Compare with baseline
```bash
# First run creates baseline
cargo bench --bench state_mutations

# Later runs compare against baseline
cargo bench --bench state_mutations -- --baseline main
```

## Key Metrics to Monitor

### Rendering Performance
Monitor these metrics to catch performance regressions:
- **Empty render**: Should be <1ms (test backend overhead)
- **Small project list (5)**: Should be <2ms
- **Medium project list (10)**: Should be <3ms
- **Large project list (20)**: Should be <5ms

### Event Handling
- **Keyboard event parsing**: <0.1ms
- **Navigation computation**: <0.2ms
- **Screen transitions**: <0.3ms
- **Dirty flag ops**: <0.01ms

### State Mutations
- **String operations**: <0.5ms
- **Vector access**: <0.1ms
- **Enum creation**: <0.01ms
- **Complex mutations**: <1ms

## Integration with CI/CD

Benchmarks can be integrated into CI/CD pipelines:

```bash
# Fail if performance degrades beyond 5%
cargo bench -- --output-format bencher | tee output.txt

# Compare baseline (requires previous baseline commit)
```

## Design Pattern Impact on Performance

These benchmarks validate the R-* patterns' performance characteristics:

1. **R-STATE-SEPARATION**: Mutation methods overhead is <0.1ms
2. **R-WIDGET-COMPOSITION**: Pure rendering functions with TestBackend
3. **R-EVENT-LOOP**: Dirty flag check is <0.01ms
4. **R-RESPONSIVE-LAYOUT**: Layout computation is <1ms for any size

## Interpreting Results

### Green (Good)
- All benchmarks meet targets
- No regressions (within 5% variance)
- Memory usage stable

### Yellow (Warning)
- Approaching performance targets (>10% margin)
- Small regressions (5-10%)
- Should investigate and optimize

### Red (Critical)
- Missing performance targets
- Large regressions (>10%)
- May indicate algorithm changes or memory leaks

## Future Optimization Opportunities

1. **Memoization**: Cache layout computations for same size
2. **String pooling**: Reuse strings in hot paths
3. **Vector pre-allocation**: Pre-allocate vectors for known sizes
4. **Rendering optimization**: Cache widget styles

## References

- Criterion documentation: https://bheisler.github.io/criterion.rs/book/
- Rust performance book: https://nnethercote.github.io/perf-book/
- Ratatui performance: Check ratatui issue #1234

## Notes

- Benchmarks use `TestBackend` to avoid terminal I/O overhead
- Criterion uses statistical analysis to detect real performance changes
- HTML reports include graphs and detailed timing distributions
- Sample sizes are tuned for quick feedback (1000-10000 iterations)