Upload ARCHITECTURE.md

ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# 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 |