ARCHITECTURE.md

Spectral Terminal Emulator Architecture

Design Philosophy

Spectral is designed to be the fastest terminal emulator while solving the font rendering problems that plague other GPU-accelerated terminals (especially Ghostty's "too thin" font issue on non-macOS platforms).

Key Differentiators

1. MSDF Font Rendering: Multi-channel signed distance fields for GPU-native font rasterization with configurable per-pixel thickening across all platforms
2. Compute Shader Glyph Generation: Glyph rasterization happens on GPU, not CPU — eliminating the biggest bottleneck in existing terminals
3. SIMD-Optimized Parser: VT100/ANSI escape sequence parsing with SIMD byte scanning for CSI/OSC/DCS sequences
4. Unified wgpu Backend: Single Rust codebase renders via Metal on macOS, Vulkan on Linux, DirectX 12 on Windows
5. Cross-Platform Font Thickening: font-thicken and font-thicken-strength work identically on macOS, Linux, and Windows via MSDF threshold adjustment

Crate Structure

spectral/
├── spectral-core/     # Terminal grid, cell model, VT parser, damage tracking
├── spectral-pty/      # PTY abstraction (Unix/Windows)
├── spectral-font/     # Font discovery, MSDF atlas, metrics
└── spectral-render/   # wgpu renderer, compute shaders, frame pacing

Renderer Architecture

PTY bytes → SIMD VT Parser → Terminal Grid → Damage Tracker
                                            ↓
                                    Renderable Content Iterator
                                            ↓
                              Font Shaper (HarfBuzz/swash)
                                            ↓
                              Glyph Cache (HashMap<GlyphKey, AtlasSlot>)
                                            ↓
                              MSDF Compute Pass (missing glyphs)
                                            ↓
                              Texture Atlas Update
                                            ↓
                              GPU Render Pass (Instanced Quads)
                                            ↓
                              wgpu Surface Present

Performance Targets

Benchmark	Target
ASCII cat /dev/urandom	>150 MB/s (faster than Kitty's 121)
Key-to-screen latency	<8ms (120Hz refresh, no batching)
Startup time	<100ms cold
Memory (100k scrollback lines)	<50MB
Font atlas (complete Unicode BMP)	<16MB GPU