> ## 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.
# Smooth Rendering
> How Monolex eliminates terminal flicker and delivers buttery-smooth output
# Smooth, Flicker-Free Terminal
Ever noticed your terminal flickering during fast output? Monolex completely eliminates this problem with a technology called **Atomic State**.
```
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ NO MORE FLICKER ║
║ ║
║ Before Monolex After Monolex ║
║ ┌─────────────┐ ┌─────────────┐ ║
║ │ ▓░▓░▓░▓░▓░ │ │ Hello World │ ║
║ │ FLICKER! │ → │ Smooth text │ ║
║ │ ░▓░▓░▓░▓░▓ │ │ Always clean│ ║
║ └─────────────┘ └─────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
```
***
## The Problem: Why Terminals Flicker
When programs print text really fast, traditional terminals struggle to keep up:
```
┌─────────────────────────────────────────────────────────────────┐
│ TRADITIONAL TERMINAL │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Program says: "Print Hello World" │
│ │
│ Step 1: "H" arrives → Show immediately │
│ Step 2: "e" arrives → Show immediately │
│ Step 3: "l" arrives → Show immediately │
│ Step 4: "l" arrives → Show immediately │
│ Step 5: "o" arrives → Show immediately │
│ ...and so on │
│ │
│ Problem: Screen updates 11 times for "Hello World"! │
│ │
│ Your eyes see: │
│ ┌───────────────────────────────────────────┐ │
│ │ H → He → Hel → Hell → Hello → Hello W... │ │
│ └───────────────────────────────────────────┘ │
│ │
│ Result: FLICKER, JITTER, EYE STRAIN │
│ │
└─────────────────────────────────────────────────────────────────┘
```
This gets worse when AI tools stream thousands of characters per second!
***
## The Solution: Atomic State
Monolex waits for **complete frames** before showing anything:
```
┌─────────────────────────────────────────────────────────────────┐
│ MONOLEX WITH ATOMIC STATE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Program says: "Print Hello World" │
│ │
│ ┌─────────────────┐ │
│ │ WAITING ROOM │ ← Characters wait here │
│ │ ───────────── │ │
│ │ H e l l o │ │
│ │ W o r l d │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ QUALITY CHECK │ ← Is the frame complete? │
│ │ ───────────── │ │
│ │ ✓ All text │ │
│ │ ✓ All colors │ │
│ │ ✓ Cursor pos │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ YOUR SCREEN │ ← Show only when ready! │
│ │ ───────────── │ │
│ │ Hello World │ │
│ └─────────────────┘ │
│ │
│ Result: ONE clean update, NO flicker │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Think of it like a movie theater**: Instead of showing you each frame as it's being drawn, Monolex waits until the entire scene is ready, then displays it perfectly.
***
## How It Works: The Gatekeeper
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ THE GATEKEEPER CONCEPT │
│ │
│ Programs Gatekeeper Your Screen │
│ ───────── ────────── ─────────── │
│ │
│ ┌───────┐ ┌────────┐ ┌───────────┐ │
│ │ App 1 │────────▶│ │ │ │ │
│ └───────┘ │ │ │ Perfect │ │
│ │ ATOMIC │──────────▶│ Display │ │
│ ┌───────┐ │ STATE │ │ │ │
│ │ App 2 │────────▶│ │ │ Always │ │
│ └───────┘ │ │ │ Clean │ │
│ └────────┘ │ │ │
│ ┌───────┐ │ └───────────┘ │
│ │ App 3 │──────────────┘ │
│ └───────┘ │
│ │
│ The Gatekeeper: │
│ • Collects all incoming data │
│ • Checks if frame is complete │
│ • Only lets perfect frames through │
│ │
└─────────────────────────────────────────────────────────────────┘
```
***
## Visual Comparison
```
Time 0ms: |H___________|
Time 1ms: |He__________|
Time 2ms: |Hel_________|
Time 3ms: |Hell________|
Time 4ms: |Hello_______|
Time 5ms: |Hello ______|
Time 6ms: |Hello W_____|
Time 7ms: |Hello Wo____|
Time 8ms: |Hello Wor___|
Time 9ms: |Hello Worl__|
Time 10ms: |Hello World_|
11 screen updates = FLICKER
```
```
Time 0ms: |___________|
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
(waiting...)
Time 10ms: |Hello World|
1 screen update = SMOOTH
```
***
## Smart Detection (4 Patterns)
Monolex uses the **Alacritty VTE Parser** (the same parser used by the popular Alacritty terminal) to understand terminal output. It detects 4 specific patterns to know when a frame is complete:
```
┌─────────────────────────────────────────────────────────────────┐
│ PATTERN DETECTION (4 MECHANISMS) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 1: BSU/ESU (Synchronized Update Protocol) │
│ ───────────────────────────────────────────────── │
│ │
│ Modern programs send explicit signals: │
│ "BEGIN UPDATE" → draw content → "END UPDATE" │
│ │
│ Monolex waits for "END UPDATE" before displaying! │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 2: CURSOR HIDE/SHOW (Ink Pattern) │
│ ───────────────────────────────────────────────── │
│ │
│ Programs often: │
│ 1. Hide cursor ← "I'm about to draw" │
│ 2. Draw content │
│ 3. Show cursor ← "I'm done drawing" │
│ │
│ Monolex detects this and waits for step 3! │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 3: SCREEN CLEAR (Implicit Sync) │
│ ───────────────────────────────────────────────── │
│ │
│ When screen clears: │
│ • Old content gone │
│ • New content definitely coming │
│ • Wait 8ms for complete frame before showing │
│ │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Pattern 4: INCOMPLETE SEQUENCE │
│ ───────────────────────────────────────────────── │
│ │
│ If a command is split across packets: │
│ Packet 1: "Set color to re" │
│ Packet 2: "d" (rest of "red") │
│ │
│ Monolex buffers until the command is complete! │
│ │
└─────────────────────────────────────────────────────────────────┘
```
***
## Real-World Examples
### Example 1: Running a Build Command
```
┌─────────────────────────────────────────────────────────────────┐
│ npm run build │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Without Atomic State: With Atomic State: │
│ ───────────────────── ────────────────── │
│ │
│ [==== ] 40% [==== ] 40% │
│ [===== ] 50% (smooth transition) │
│ [====== ] 60% [==========] 100% │
│ [======= ] 70% │
│ [======== ] 80% Progress bar updates │
│ [========= ] 90% cleanly, no jitter │
│ [==========] 100% │
│ │
│ Each % causes redraw Only meaningful updates shown │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Example 2: AI Streaming Output
```
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code generating response │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Without Atomic State: With Atomic State: │
│ ───────────────────── ────────────────── │
│ │
│ T (waiting...) │
│ Th │
│ The │
│ The The answer is 42. │
│ The a │
│ The an Smooth, complete sentences │
│ The ans appear at natural pauses │
│ The answ │
│ The answe │
│ The answer │
│ ... │
│ │
│ Every character flickers Text appears in readable chunks │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Example 3: Vim/Neovim Editing
```
┌─────────────────────────────────────────────────────────────────┐
│ Opening a file in Vim │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Without Atomic State: With Atomic State: │
│ ───────────────────── ────────────────── │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ │ │ │ │
│ │ partial line 1 │ │ complete file │ │
│ │ par │ → │ with syntax │ │
│ │ ░░░░░ (loading) │ │ highlighting │ │
│ │ │ │ ready instantly │ │
│ └────────────────────┘ └────────────────────┘ │
│ │
│ You see the file being File appears complete │
│ drawn line by line with all colors │
│ │
└─────────────────────────────────────────────────────────────────┘
```
***
## The Result
Your eyes will thank you. No more visual noise or jitter.
Fewer screen updates means your computer works less hard.
Less processing means longer battery life on laptops.
***
## The Journey of One Character
Ever wonder what happens when you type a single letter? Here's the complete journey:
```
╔═══════════════════════════════════════════════════════════════════════════════╗
║ THE JOURNEY OF THE LETTER "A" ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ STEP 1: You press "A" on keyboard ║
║ ───────────────────────────────── ║
║ ║
║ ┌─────────┐ ║
║ │ A │ Your finger presses the key ║
║ └────┬────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 2: Travels to PTY (Background Helper) ║
║ ────────────────────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ PTY DAEMON │ ║
║ │ ──────────── │ ║
║ │ "I received 'A'. Let me pass it │ ║
║ │ to the shell and get the result." │ ║
║ └────┬────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 3: Shell responds with output ║
║ ────────────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ Raw bytes: 0x41 (the letter "A") │ ║
║ │ + cursor position update │ ║
║ │ + maybe some colors │ ║
║ └────┬────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 4: Atomic State processes it ║
║ ───────────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ ATOMIC STATE (Quality Control) │ ║
║ │ ──────────────────────────── │ ║
║ │ □ Parse the bytes │ ║
║ │ □ Understand the content │ ║
║ │ □ Check if frame is complete │ ║
║ │ □ Calculate what changed │ ║
║ │ ✓ Ready to display! │ ║
║ └────┬────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ║
║ STEP 5: Your screen shows "A" ║
║ ───────────────────────────── ║
║ ║
║ ┌─────────────────────────────────────┐ ║
║ │ $ command_A█ │ ║
║ │ │ ║
║ │ Clean, instant, no flicker! │ ║
║ └─────────────────────────────────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
```
All of this happens in **under 16 milliseconds** - faster than you can blink!
***
## Safety Nets: What If Something Goes Wrong?
Monolex has built-in protection for edge cases:
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TIMEOUT PROTECTION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Problem: What if a program hides the cursor but crashes before showing it? │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Program: "Hide cursor!" ─────▶ [crashes] │ │
│ │ │ │
│ │ Traditional terminal: Cursor stays hidden forever! 😱 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Solution: Monolex uses a timeout │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Program: "Hide cursor!" ─────▶ [crashes] │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Monolex: ⏰ 16ms timer starts │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ After 16ms: "No end signal? Show anyway!" 💪 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Your terminal never gets stuck! │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INCOMPLETE COMMAND PROTECTION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Problem: Network splits a command in half │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Complete command: "Set color to GREEN" │ │
│ │ │ │
│ │ Network splits it: │ │
│ │ Packet 1: "Set color to GRE" ───▶ arrives first │ │
│ │ Packet 2: "EN" ───▶ arrives 5ms later │ │
│ │ │ │
│ │ Traditional terminal: Garbled output! 😱 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Solution: Monolex waits for completion │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Packet 1 arrives: "Set color to GRE" │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Monolex: "Incomplete! Wait..." │ │
│ │ │ │ │
│ │ Packet 2 arrives: ▼ │ │
│ │ "EN" ───▶ Complete! Now execute. │ │
│ │ │ │
│ │ Result: Perfect green text! ✨ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
***
## Legacy App Support
Older programs don't know about modern synchronization. Monolex handles them too:
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ VIRTUAL SYNCHRONIZED RENDERING (VSR) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Modern programs: │
│ ──────────────── │
│ Send explicit signals: "BEGIN" → content → "END" │
│ Easy for Monolex to detect frame boundaries! │
│ │
│ │
│ Legacy programs (vim, htop, npm): │
│ ───────────────────────────────── │
│ No explicit signals │
│ Just raw screen commands │
│ │
│ Example (htop refresh): │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ T=0ms: Clear screen │ │
│ │ T=1ms: Move cursor to top │ │
│ │ T=2ms: Draw "CPU: 45%" │ │
│ │ T=3ms: Move cursor down │ │
│ │ T=4ms: Draw "MEM: 2.1G" │ │
│ │ ... │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ │
│ How Monolex handles this (VSR): │
│ ─────────────────────────────── │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. Detects "Clear screen" command │ │
│ │ 2. Says: "New content is definitely coming!" │ │
│ │ 3. Waits 8 milliseconds to collect everything │ │
│ │ 4. Shows the complete htop screen at once │ │
│ │ │ │
│ │ Result: No flash, no flicker - just smooth htop! 🎉 │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
***
## Summary
```
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ATOMIC STATE IN ONE PICTURE ║
║ ║
║ ┌─────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────┐ ║
║ │Programs │ ───▶ │ Waiting │ ───▶ │ Quality │ ───▶ │ Your │ ║
║ │ output │ │ Room │ │ Check │ │ Screen │ ║
║ │ data │ │ (buffer) │ │ (is ready?)│ │(perfect)│ ║
║ └─────────┘ └──────────────┘ └─────────────┘ └─────────┘ ║
║ ║
║ Fast, messy Collected, Only complete Clean, ║
║ data stream organized frames pass smooth ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
```
**You don't need to do anything!** Atomic State works automatically in Monolex. Just enjoy the smooth experience.
***
## Next Steps
Learn about the other technologies that make Monolex blazing fast.
Having issues? Check our troubleshooting guide.
***
## Want to Go Deeper?
For developers and curious minds who want to understand the technical details:
Technical details of Virtual Synchronized Rendering - how frame boundaries are detected.
The explicit frame synchronization protocol that modern programs use.