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

cd crates/syntaxis-tui
cargo bench

Run specific benchmark suite

cargo bench --bench rendering_performance
cargo bench --bench event_handling
cargo bench --bench state_mutations

Generate HTML reports

# Reports are automatically generated in: target/criterion/
# Open in browser: target/criterion/report/index.html

Compare with baseline

# 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:

# 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)