What is Atomic State?
Atomic State is MonoTerm’s solution for flicker-free terminal rendering. It ensures your terminal only displays complete, validated frames.The Problem We Solved
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ Have you ever seen this in a terminal? │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ $ npm install │ │
│ │ │ │
│ │ [##########..........] 50% │ │
│ │ ^ │ │
│ │ ┌─────┴──────┐ │ │
│ │ │ FLICKER! │ │ │
│ │ │ FLASH! │ │ │
│ │ └────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Progress bars flicker. Colors flash. Text jumps around. │
│ This happens because the terminal renders INCOMPLETE data. │
│ │
└───────────────────────────────────────────────────────────────────────┘
Why Does This Happen?
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ TRADITIONAL TERMINAL │
│ │
│ Program Terminal │
│ ┌──────────┐ ┌──────────┐ │
│ │ │ "Hello" │ │ │
│ │ vim │────────────→│ xterm │ │
│ │ │ │ │ │
│ └──────────┘ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ RENDER │ │
│ │ INSTANTLY │ │
│ └───────────┘ │
│ │
│ │
│ PROBLEM: What if "Hello" arrives as "Hel" + "lo" in two pieces? │
│ │
│ │
│ Program Terminal │
│ ┌──────────┐ ┌──────────┐ │
│ │ │ "Hel" │ │──→ RENDER "Hel" (incomplete) │
│ │ vim │────────────→│ xterm │ │
│ │ │ "lo" │ │──→ RENDER "lo" (looks weird)│
│ └──────────┼────────────→│ │ │
│ │ └──────────┘ │
│ │
│ │
│ Result: You see "Hel" flash before "Hello" appears = FLICKER │
│ │
└───────────────────────────────────────────────────────────────────────┘
How Atomic State Fixes This
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ MONOTERM ATOMIC STATE │
│ │
│ │
│ Program Atomic State Terminal │
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ │
│ │ │ │ │ │ │ │
│ │ vim │──────→│ WAIT │───────→│ xterm │ │
│ │ │ │ for │ │ │ │
│ └──────────┘ │ complete │ └──────────┘ │
│ │ frame │ │
│ └────────────┘ │
│ │
│ │
│ HOW IT WORKS: │
│ │
│ "Hel" arrives ──────→ WAIT... (incomplete) │
│ │
│ "lo" arrives ──────→ COMPLETE! │
│ │ │
│ SEND TO TERMINAL │
│ │ │
│ RENDER "Hello" (perfect!) │
│ │
│ │
│ Result: Terminal ONLY sees complete frames = NO FLICKER │
│ │
└───────────────────────────────────────────────────────────────────────┘
The “Atomic” Concept
┌──────────────────────────────────────────────────────────────────────────┐
│ │
│ "ATOMIC" = Cannot be split │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ In physics: Atom = smallest unit (indivisible) │ │
│ │ │ │
│ │ In MonoTerm: Atomic Frame = smallest complete screen update│ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ │
│ Traditional: Send anything as soon as it arrives │
│ │
│ DATA ──→ [A] ──→ [B] ──→ [C] ──→ SCREEN │
│ │ │ │ │
│ render render render (3 renders = potential flicker) │
│ │
│ │
│ Atomic State: Wait until complete, then send once │
│ │
│ DATA ──→ [A] ──→ [B] ──→ [C] ──→ [ABC] ──→ SCREEN │
│ │ │ │ │ │
│ wait wait wait RENDER (1 render = no flicker) │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Before and After
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ BEFORE (Traditional) AFTER (Atomic State) │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ $ htop │ │ $ htop │ │
│ │ │ │ │ │
│ │ CPU: [##...] 40% │ │ CPU: [####.] 80% │ │
│ │ │ │ MEM: [###..] 60% │ │
│ │ ^ flicker! │ │ SWP: [#....] 20% │ │
│ │ CPU: [####.] 80% │ │ │ │
│ │ MEM: [###..] 60% │ │ Smooth and stable │ │
│ │ │ │ No flickering │ │
│ │ ^ partial update │ │ Clean updates │ │
│ │ SWP: [#....] 20% │ │ │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
│ │
│ Multiple partial Single complete │
│ renders visible render only │
│ │
└───────────────────────────────────────────────────────────────────────┘
Key Benefits
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ [OK] NO FLICKER │ │
│ │ Progress bars, htop, vim - all render smoothly │ │
│ │ │ │
│ │ [OK] NO GLITCHES │ │
│ │ Colors and text always appear correctly │ │
│ │ │ │
│ │ [OK] FASTER RESPONSE │ │
│ │ Less unnecessary rendering means faster overall │ │
│ │ │ │
│ │ [OK] LESS BATTERY USAGE │ │
│ │ Fewer screen updates = less GPU work │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────┘
How Frames Are Detected
MonoTerm uses the BSU/ESU protocol (DECSET Mode 2026) to detect frame boundaries.┌───────────────────────────────────────────────────────────────────────┐
│ │
│ THREE DETECTION PATTERNS │
│ │
│ │
│ PATTERN 1: BSU/ESU Markers (Standard Protocol) │
│ ─────────────────────────────────────────────── │
│ │
│ BSU ─────→ [content] ─────→ ESU │
│ │ │ │
│ "Start" "Complete" │
│ │
│ │
│ PATTERN 2: Screen Clear Detection │
│ ────────────────────────────────── │
│ │
│ CLEAR ─────→ [wait] ─────→ new content │
│ │ │
│ "Redraw coming" │
│ │
│ │
│ PATTERN 3: Cursor Hide/Show │
│ ─────────────────────────── │
│ │
│ HIDE ─────→ [content] ─────→ SHOW │
│ │ │ │
│ "Updating..." "Done!" │
│ │
└───────────────────────────────────────────────────────────────────────┘
Summary
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ ATOMIC STATE IN ONE PICTURE │
│ │
│ │
│ Program Output Your Screen │
│ │
│ │ ^ │
│ │ │ │
│ ▼ │ │
│ ┌───────────────┐ │ │
│ │ │ │ │
│ │ ATOMIC │ Only when │ │
│ │ STATE │────────────────────────┘ │
│ │ │ complete │
│ │ "Gatekeeper" │ │
│ │ │ │
│ └───────────────┘ │
│ │
│ │
│ Waits for Shows only │
│ complete frames perfect frames │
│ │
│ │
│ "Atomic State is like a quality inspector that only lets │
│ perfect products reach the customer." │
│ │
└───────────────────────────────────────────────────────────────────────┘
Tech Stack
Built with Rust for memory-safe performance, using Alacritty’s VTE Parser for escape sequence processing.