Documentation Index
Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
Use this file to discover all available pages before exploring further.
Alacritty-xterm-Monolex Technology Integration
Monolex combines three proven technologies:
- Alacritty VTE: Fast native ANSI parsing
- xterm.js WebGL: GPU rendering
- Monolex: Intelligent synchronization
┌─────────────────────────────────────────────────────────────────────┐
│ ALACRITTY-XTERM-MONOLEX INTEGRATION │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ALACRITTY XTERM.JS MONOLEX │
│ ═══════════════ ════════════ ═══════════════ │
│ VTE Parser WebGL Renderer Intelligent Sync │
│ ANSI Standard GPU Accelerated Cell Conversion │
│ CJK Support DOM-independent Direct Injection │
│ Proven Reliable Fast Rendering Frame Batching │
│ │
│ → Grid Mode v2 (TIER 1-5) │
│ → Significant CPU reduction │
│ │
└─────────────────────────────────────────────────────────────────────┘
Why Each Component
Alacritty VTE Parser
| Aspect | Standard xterm.js | Alacritty VTE |
|---|
| Language | Pure JavaScript | Native Rust |
| Performance | Slower (interpreted) | Faster (native) |
| Test Coverage | Built-in | 1000+ tests |
| Status | Optimized | Battle-tested |
xterm.js WebGL
| Rendering | Performance | Use Case |
|---|
| Canvas 2D | Slowest | Legacy |
| DOM | Slow | Early xterm |
| WebGL | Fast (GPU) | Monolex choice |
┌─────────────────────────────────────────────────────────────────────┐
│ XTERM.JS WEBGL RENDERER INTERNALS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ TextureAtlas (2048×2048 pixels) │
│ ┌────┬────┬────┬────┬────┬────┬────┬────┐ │
│ │ A │ B │ C │... │ a │ b │ c │... │ │
│ ├────┼────┼────┼────┼────┼────┼────┼────┤ │
│ │ 0 │ 1 │ 2 │... │ 한 │ 글 │ 日 │... │ │
│ └────┴────┴────┴────┴────┴────┴────┴────┘ │
│ │
│ Cache: Map<"char+fg+bg+flags" → AtlasEntry> │
│ - First render: Rasterize → Cache → Blit │
│ - Subsequent: Cache lookup → Blit (fast!) │
│ │
│ Render Loop: │
│ for each cell in viewport: │
│ 1. Lookup glyph in atlas cache │
│ 2. If miss: rasterize with Canvas2D → upload to atlas │
│ 3. Add to vertex buffer: (x, y, texCoord, fg, bg) │
│ │
│ gl.drawArrays(GL_TRIANGLES, vertexBuffer) │
│ → Single draw call for entire grid! │
│ │
└─────────────────────────────────────────────────────────────────────┘
Monolex Innovations
- Epoch-Based Resize Sync: Solves resize race conditions
- Cell Bit-Packing: Alacritty → xterm format conversion
- ACK-Based Flow Control: Consumer-driven backpressure
- Parser Backup API: IME inverse cursor support
- Unix Socket Resilience: Handles split ANSI sequences
The Key Insight
Traditional thinking:
"xterm.js includes VTE parser, use it"
→ JS parsing overhead
Monolex insight:
"xterm.js is a RENDERER, not a parser"
→ Use Alacritty for parsing
→ Feed xterm.js prepared cells
→ Significant CPU savings
- Parsing ≠ Rendering
- Best parser = Alacritty (Rust)
- Best renderer = xterm.js (WebGL)
- Connect them = Grid Mode v2
Direct Buffer Injection vs term.write()
Why Grid Mode v2 uses direct buffer injection instead of term.write():
┌─────────────────────────────────────────────────────────────────────┐
│ BUFFER INJECTION VS TERM.WRITE() │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Standard xterm.js path (term.write): │
│ │
│ term.write(ansiString) │
│ │ │
│ ▼ │
│ WriteBuffer.write() (enqueue) │
│ │ │
│ ▼ │
│ InputHandler.parse() (VTE parser, slow) ❌ DUPLICATED │
│ │ │
│ ▼ │
│ BufferSet.update() (state update) │
│ │ │
│ ▼ │
│ RenderService.refresh() (schedule) │
│ │ │
│ ▼ │
│ WebGLRenderer.render() (GPU) │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Grid Mode v2 path (direct injection): │
│ │
│ GridUpdate (from Rust) │
│ │ │
│ ▼ │
│ Buffer Injector │
│ │ │
│ ├── Direct memory write to line data │
│ │ (Content, Foreground, Background slots) │
│ │ │
│ ▼ │
│ _renderRows(startRow, endRow) (sync render) │
│ │ │
│ ▼ │
│ WebGLRenderer.render() (GPU, immediate) │
│ │
│ ✅ VTE parsing already done in Rust │
│ ✅ No double parsing │
│ ✅ Direct memory access │
│ ✅ Sync render (no 1-frame delay) │
│ │
└─────────────────────────────────────────────────────────────────────┘
Data Pipeline
TIER 0: PTY Data Stream (Unix Socket)
│
▼
TIER 1: Alacritty VTE Parser (fast native)
│
▼
TIER 2: ACK-Based Flow Control
│
▼
TIER 3: Cell Converter - Rust
│ Alacritty Cell → XtermCell (3×u32)
▼
TIER 4: Direct Buffer Injection
│ GridUpdate → xterm._core._bufferService
▼
TIER 5: xterm.js WebGL Rendering (GPU)
Result: Fast end-to-end, lower CPU due to native parsing + ACK flow control
The Conversion Point
┌─────────────────────────────────────────────────────────────────┐
│ CELL CONVERSION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Alacritty Cell │
│ │ │
│ ├── Character (Unicode) │
│ ├── Foreground Color │
│ ├── Background Color │
│ └── Flags (bold, italic, etc.) │
│ │ │
│ ▼ (Cell Converter) │
│ │
│ xterm.js Cell (3×u32) │
│ ├── Slot 0: Content (codepoint + width) │
│ ├── Slot 1: Foreground (color + flags) │
│ └── Slot 2: Background (color + flags) │
│ │
└─────────────────────────────────────────────────────────────────┘
| Component | Alacritty | xterm.js | Monolex Handling |
|---|
| Codepoint | char | u32 | Direct cast |
| Width | Flags::WIDE_CHAR | Bits [22:23] | Flag extraction |
| Colors | Color::Named/Indexed/Rgb | 3 modes | Mode detection |
| Text Attrs | 16+ flag bits | 32-bit mask | Bit-shift packing |
Architecture Comparison
Standard xterm.js: Grid Mode v2:
───────────────── ──────────────
TIER 1: JS VTE (slow) TIER 1: Alacritty (fast) ✅
TIER 2: DOM update TIER 2: Batching ✅
TIER 5: Canvas TIER 3: Convert ✅
TIER 4: Inject ✅
TIER 5: WebGL ✅
───────────────── ──────────────
Result: High CPU Result: Lower CPU
Technology Validation
| Technology | Stars | Users | Status |
|---|
| Alacritty | 10K+ | Tens of thousands | Production |
| xterm.js | 18K+ | VS Code, 1000+ projects | Industry standard |
| Monolex | - | Production-ready | 2024 |
Key Components
┌─────────────────────────────────────────────────────────────────┐
│ INTEGRATION COMPONENTS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Component Purpose │
│ ───────────────── ──────────────────────────────────────── │
│ VTE Renderer Alacritty wrapper, Term management │
│ Cell Converter Alacritty → xterm.js cell conversion │
│ AtomicParser BSU/ESU detection, metadata extraction │
│ Buffer Injector Direct xterm.js buffer manipulation │
│ │
└─────────────────────────────────────────────────────────────────┘
