ratatui-testlib 0.1.0

# ratatui-testlib Documentation

This directory contains research and documentation for the ratatui-testlib project.

## Sixel Support Research (Phase 3 MVP)

### Quick Answer

**Q: Can vt100 crate handle Sixel graphics?**
**A: NO. Use termwiz/vtparse instead.**

### Documentation Files

1. **SIXEL-SUPPORT-VALIDATION.md** (in project root)
   - Complete validation report
   - Source code analysis of vt100 and termwiz
   - Final recommendation with evidence
   - **START HERE** for executive summary

2. **sixel-research.md**
   - Detailed technical analysis
   - Sixel sequence format reference
   - Integration strategies
   - Risk assessment for MVP

3. **sixel-poc.rs**
   - Working proof-of-concept code
   - Demonstrates Sixel detection and position tracking
   - Complete with tests
   - **COPY THIS** for implementation reference

4. **crate-comparison.md**
   - Side-by-side comparison: vt100 vs termwiz
   - Feature matrix
   - Performance analysis
   - Integration complexity assessment

## Key Findings

### vt100 Crate
- ❌ NO Sixel support
- ❌ NO DCS callbacks
- ✅ Good for text-only terminals
- ✅ Lightweight and simple
- **Verdict:** Cannot meet MVP requirements

### termwiz/vtparse Crate
- ✅ FULL Sixel support
- ✅ Complete DCS hooks
- ✅ Proven in production (wezterm)
- ✅ Working proof-of-concept
- **Verdict:** RECOMMENDED for ratatui-testlib

## Evidence

### Source Code Analysis
- Examined vt100-rust repository (all source files)
- Examined wezterm/termwiz repository (vtparse module)
- Searched for Sixel/DCS handling
- Analyzed callback interfaces

### Test Validation
- Found Sixel test case in vtparse (line 1118)
- Created working POC with cursor tracking
- Validated dimension parsing
- Tested multiple Sixel sequences

### Proof of Concept Results
```
SIXEL DETECTED at row=4, col=19
Parameters: []
Raster attributes found: 100x50 pixels (13 x 4 cells)
Occupies: rows 4-7, cols 19-31
```

## Implementation Guide

### 1. Add Dependency
```toml
[dependencies]
termwiz = { version = "0.23", default-features = false }
```

### 2. Implement VTActor
See `sixel-poc.rs` for complete example.

### 3. Track Sixel Regions
```rust
pub struct SixelRegion {
    pub start_row: usize,
    pub start_col: usize,
    pub width_cells: usize,
    pub height_cells: usize,
}
```

### 4. Integration Time
- Estimated: 4-6 hours
- POC creation: 2 hours (already done)
- Full integration: 2-4 hours
- Testing: 1-2 hours

## File Locations

```
ratatui-testlib/
├── SIXEL-SUPPORT-VALIDATION.md  (Main report - start here)
└── docs/
    ├── README.md                 (This file)
    ├── sixel-research.md         (Detailed technical analysis)
    ├── sixel-poc.rs              (Working proof-of-concept)
    └── crate-comparison.md       (vt100 vs termwiz comparison)
```

## Quick Reference

### Sixel Sequence Format
```
ESC P q <params> <data> ESC \
^^^^^   ^^^^^^^  ^^^^^^ ^^^^^
DCS     Sixel    Image  Terminator
        mode='q' data
```

### Detection in termwiz
```rust
impl VTActor for MyTerminal {
    fn dcs_hook(&mut self, mode: u8, params: &[i64], ...) {
        if mode == b'q' {
            // Sixel detected!
            // Cursor position available
            // Parameters in params array
        }
    }
}
```

### What You Get
- ✅ Sixel sequence start detection
- ✅ Cursor position at start
- ✅ Sixel parameters extraction
- ✅ Raster attributes (width/height)
- ✅ Pixel-to-cell conversion
- ✅ Occupied region calculation

## Next Steps

1. Read SIXEL-SUPPORT-VALIDATION.md for complete analysis
2. Review sixel-poc.rs for implementation pattern
3. Add termwiz dependency to Cargo.toml
4. Implement VTActor trait for ratatui-testlib
5. Add Sixel region tracking
6. Write integration tests

## Questions?

All questions answered in:
- SIXEL-SUPPORT-VALIDATION.md (comprehensive report)
- sixel-research.md (technical deep-dive)
- crate-comparison.md (detailed comparison)

## Confidence Level

**VERY HIGH (95%+)**

- Source code analysis complete
- Working proof-of-concept validates requirements
- Production usage in wezterm demonstrates stability
- Clear path to implementation
- Low risk, high confidence

---

**Status:** ✅ Research Complete
**Recommendation:** ✅ Use termwiz/vtparse
**Next Phase:** Implementation (MVP Phase 3)