Project 4: Screen Diff Renderer

A small rendering engine that diffs two frames and emits minimal updates.

Quick Reference

Attribute	Value
Difficulty	Level 2: Intermediate (REFERENCE.md)
Time Estimate	1 week
Main Programming Language	Go
Alternative Programming Languages	Rust, C, Python
Coolness Level	Level 3: Genuinely Clever (REFERENCE.md)
Business Potential	Level 1: Resume Gold (REFERENCE.md)
Prerequisites	Screen Rendering, Buffering, and Diffing
Key Topics	Rendering

1. Learning Objectives

By completing this project, you will:

Build and validate the core behavior described in the real-world outcome.
Apply Screen Rendering, Buffering, and Diffing to a working TUI.
Design a predictable input-to-rendering pipeline with explicit state changes.
Produce a tool that behaves consistently across terminals and restores state on exit.

2. All Theory Needed (Per-Concept Breakdown)

Screen Rendering, Buffering, and Diffing

Fundamentals Rendering in TUIs is about mapping a logical state to a 2D grid of cells and emitting the minimal set of updates. Unlike GUIs, you do not have a compositor; you are the compositor. The screen is a matrix of characters with attributes (color, bold, underline). To avoid flicker and wasted output, you typically keep a back buffer (last frame) and compute a diff to the new frame. The diff tells you which cells changed and where to move the cursor. Many libraries implement this for you, but you need to understand it to debug performance or visual glitches. A frame is a full snapshot of the terminal grid, and your renderer is responsible for ensuring that each frame is consistent and complete.

Deep Dive into the concept A screen buffer is a 2D array of cells, where each cell has a glyph and style attributes. A frame is a complete snapshot of this buffer. When your app state changes, you generate a new frame. If you were to naively clear the screen and print the entire frame every time, performance would degrade on slow terminals and over SSH. This is why most TUI systems use double buffering and diffing.

Diffing can be done at multiple granularities. The simplest method is to compare cell-by-cell and emit updates for every change, moving the cursor as needed. A more efficient method groups contiguous runs of cells in the same row to reduce cursor movements. Another technique is damage tracking: instead of comparing full frames, you track which regions changed as a result of state updates. The tradeoff is complexity vs performance.

A robust renderer also handles terminal-specific features like alternate screen buffers. Alternate screen buffer usage prevents your UI from polluting the shell scrollback; when you exit, the original screen is restored. Libraries like crossterm expose entry and exit commands for alternate screens. citeturn2search2

The critical invariants are: (1) you must know where the cursor is, (2) you must know the current style attributes, and (3) you must restore these on exit. A diffing renderer is essentially a small compiler that transforms an intended frame into a minimal control-sequence program. This is the core of performance optimization in TUIs.

In projects, you will build a simplified diff engine: keep a 2D array of cells for the previous frame, compute a new frame each tick, and emit only the changed cells. You will learn to coalesce updates, manage cursor moves, and reduce redundant style changes.

There are also subtle correctness issues. For example, if you update a cell with a different style, you must ensure the style is set before printing the character, and you must avoid leaking that style into subsequent cells. This means your renderer needs a model of the current style state in the terminal and must emit style reset sequences at the right time. Similarly, when rendering wide characters or combining characters, you must consider how many columns a glyph occupies; otherwise your cursor calculations will drift. Even if you avoid complex Unicode in your own output, the terminal width can vary by locale, so your renderer should treat width as a property of a glyph rather than as a constant.

Resizing adds another layer. When the terminal size changes, your frame dimensions change, and a previously valid cursor position may be out of bounds. A robust renderer clamps or reflows content, re-creates buffers to the new size, and forces a full redraw to prevent artifacts from stale rows. For dashboards, you often choose a strategy: either truncate content to fit the new size or change layout to a stacked mode.

Finally, you must consider how frequently to render. Some TUIs render only on state changes, others render on a fixed tick. Rendering on every tick simplifies animations but can waste bandwidth. Rendering on state change reduces output but requires careful invalidation logic. The projects will give you a chance to compare both approaches and measure their impact.

How this fits on projects

Project 4 (Screen Diff Renderer), Project 5 (ncurses Dashboard), Project 9 (Ratatui Dashboard)

Definitions & key terms

Back buffer: The previous frame stored for diffing.
Damage tracking: Tracking which regions changed to reduce diff work.
Alternate screen: A separate buffer that restores the original screen on exit. citeturn2search2

Mental model diagram

State -> Frame A (buffer) -> diff(Frame A, Frame B) -> Emit sequences -> Screen
               ^                                   |
               |                                   v
            Frame B <--------------------------- Next tick

How it works

Generate a full frame from app state.
Compare with the previous frame.
For each changed region, emit cursor moves and text.
Update the stored previous frame.

Minimal concrete example

PSEUDOCODE:
new_frame = render(state)
for each cell in grid:
  if new_frame[cell] != old_frame[cell]:
    move_cursor(cell.x, cell.y)
    set_style(cell.style)
    write(cell.glyph)
old_frame = new_frame

Common misconceptions

“Diffing is only for speed” -> It also prevents flicker and keeps cursor stable.
“You can ignore cursor position” -> Incorrect; cursor drift causes corrupted layouts.

Check-your-understanding questions

Why is a diff-based renderer faster over SSH?
What happens if you fail to restore the cursor or styles on exit?
Why might you prefer damage tracking to full diffing?

Check-your-understanding answers

It emits fewer bytes and avoids full-screen clears.
The user’s terminal remains in a modified state.
It reduces diff cost by focusing on known dirty regions.

Real-world applications

Terminal dashboards, log viewers, system monitors

Where you’ll apply it

Project 4, Project 5, Project 9, Project 11

References

crossterm terminal features (alternate screen) citeturn2search2
“The Pragmatic Programmer” - Ch. “Orthogonality” (designing clear rendering stages)

Key insights Rendering is a compiler: state is compiled into the smallest correct terminal program.

Summary Efficient TUIs rely on diff-based rendering and strict state management to avoid flicker and maintain control over the screen.

Homework/Exercises to practice the concept

Design a diff strategy that minimizes cursor moves.
Create a list of rendering invariants you will enforce in every frame.

Solutions to the homework/exercises

Group contiguous changes by row and emit a single cursor move per group.
Always reset styles, hide/show cursor explicitly, and restore terminal state on exit.

3. Project Specification

3.1 What You Will Build

A small rendering engine that diffs two frames and emits minimal updates.

Included:

The core UI flow described in the Real World Outcome
Deterministic input handling and rendering
Clean exit and terminal state restoration

Excluded:

GUI features, mouse-first workflows, or non-terminal frontends
Networked collaboration or cloud sync

3.2 Functional Requirements

Core Interaction: Implements the main interaction loop and updates the screen correctly.
Input Handling: Handles required keys without blocking and supports quit/exit.
Rendering: Updates only what changes to avoid flicker.
Resize Handling: Adapts to terminal resize or shows a clear warning state.
Errors: Handles invalid input or missing data gracefully.

3.3 Non-Functional Requirements

Performance: Stable refresh without visible flicker under normal usage.
Reliability: Terminal state is restored on exit or error.
Usability: Keyboard-first navigation with clear status/help hints.

3.4 Example Usage / Output

$ ./diff-renderer

$ ./diff-renderer –demo Frame 1 rendered in 120 writes Frame 2 rendered in 14 writes (diffed)


ASCII layout:

[Frame stats] [Mini grid demo]

3.5 Data Formats / Schemas / Protocols

Screen Model: 2D grid of cells with glyph + style
Input Events: Normalized key events (Up, Down, Enter, Esc, Ctrl)
State Snapshot: Immutable model used for rendering each frame

3.6 Edge Cases

Terminal resized to smaller than minimum layout
Rapid key repeat and partial escape sequences
Missing or invalid input file (if applicable)
Unexpected termination (SIGINT)

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ ./diff-renderer

3.7.2 Golden Path Demo (Deterministic)

Launch the tool
Perform the primary action once
Observe the expected screen update

3.7.3 If CLI: provide an exact terminal transcript

$ ./diff-renderer

$ ./diff-renderer –demo Frame 1 rendered in 120 writes Frame 2 rendered in 14 writes (diffed)


ASCII layout:

[Frame stats] [Mini grid demo]

3.7.4 Failure Demo (Deterministic)

$ ./diff-renderer --bad-flag
ERROR: unknown option: --bad-flag
exit code: 2

4. Solution Architecture

4.1 High-Level Design

Input -> Event Queue -> State Update -> Render -> Terminal

4.2 Key Components

Component	Responsibility	Key Decisions
Input Decoder	Normalize raw input into events	Handle partial sequences safely
State Model	Hold UI state and selections	Keep state immutable per frame
Renderer	Draw from state to terminal	Diff-based updates
Controller	Orchestrate loop and timers	Non-blocking IO

4.3 Data Structures (No Full Code)

DATA STRUCTURE: Cell
- glyph
- fg_color
- bg_color
- attrs

DATA STRUCTURE: Frame
- width
- height
- cells[width][height]

4.4 Algorithm Overview

Key Algorithm: Render Diff

Build new frame from current state
Compare with old frame
Emit minimal updates for changed cells

Complexity Analysis:

Time: O(width * height)
Space: O(width * height)

5. Implementation Guide

5.1 Development Environment Setup

# Build and run with your toolchain

5.2 Project Structure

project-root/
|-- src/
|-- tests/
|-- assets/
`-- README.md

5.3 The Core Question You’re Answering

“How do I update a terminal screen without redrawing everything?”

5.4 Concepts You Must Understand First

Screen buffers
- How to represent cells with glyph + style?
- Book Reference: “Clean Architecture” - Ch. 4
Cursor control
- How do cursor moves affect output size?
- Book Reference: “The Linux Programming Interface” - Ch. 62

5.5 Questions to Guide Your Design

Diff granularity
- Will you diff by cell or by runs?
- How will you handle style changes?
Optimization
- When do you skip cursor movement?
- How do you handle unchanged rows?

5.6 Thinking Exercise

Design a Run-Length Diff

Sketch how to group contiguous changed cells into runs.

Questions to answer:

What is the worst-case output size?
How do you prevent redundant style resets?

5.7 The Interview Questions They’ll Ask

“What is double buffering in a TUI?”
“Why does diffing reduce flicker?”
“What is damage tracking?”
“How do you minimize cursor moves?”
“What is the complexity of your diff algorithm?”

5.8 Hints in Layers

Hint 1: Start with full redraw Make it correct first, then optimize with diffing.

Hint 2: Track previous frame Store last frame in memory and compare.

Hint 3: Pseudocode

for each row:
  find contiguous changed cells -> emit one move + write

Hint 4: Debugging Add a mode that prints diff regions for inspection.

5.9 Books That Will Help

Topic	Book	Chapter
Rendering design	“Clean Architecture”	Ch. 4-5
Terminal control	“The Linux Programming Interface”	Ch. 62

5.10 Implementation Phases

Phase 1: Foundation

Goals:

Initialize the terminal and input handling
Render the first static screen

Tasks:

Implement setup and teardown
Draw a static layout that matches the Real World Outcome

Checkpoint: The UI renders and exits cleanly.

Phase 2: Core Functionality

Goals:

Implement the main interaction loop
Update state based on input

Tasks:

Add event processing
Implement the main feature (draw, navigate, filter)

Checkpoint: The primary interaction works end-to-end.

Phase 3: Polish & Edge Cases

Goals:

Handle resizing and invalid input
Improve performance and usability

Tasks:

Add resize handling
Add error states and help hints

Checkpoint: No flicker and clean recovery from edge cases.

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Input model	raw vs canonical	raw	Required for key-level input
Render strategy	full redraw vs diff	diff	Avoid flicker and reduce output
State model	mutable vs immutable	immutable	Predictable updates and testing

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Unit Tests	Validate parsing and state transitions	Key decoder tests
Integration Tests	Verify rendering pipeline	Frame diff vs expected
Edge Case Tests	Terminal resize and invalid input	Small terminal size

6.2 Critical Test Cases

Resize: Shrink terminal below minimum and verify warning.
Rapid Input: Hold down keys and ensure no crash.
Exit: Force quit and verify terminal restoration.

6.3 Test Data

Input sequence: Up, Up, Down, Enter
Expected: selection moves and activates without crash

7. Common Pitfalls & Debugging

Problem 1: “Cursor jumps unpredictably”

Why: Missing cursor position tracking.
Fix: Track last cursor position and avoid implicit moves.
Quick test: Render a single updated cell repeatedly.

8. Extensions & Challenges

8.1 Beginner Extensions

Add a help overlay with keybindings
Add a status bar with timestamps

8.2 Intermediate Extensions

Add configurable themes
Add persistent settings file

8.3 Advanced Extensions

Add plugin hooks for new views
Add performance tracing for render time

9. Real-World Connections

9.1 Industry Applications

Terminal dashboards for infrastructure monitoring
Developer tools used over SSH and in containers

htop, ranger, lazygit, nmtui (for UI design reference)

9.3 Interview Relevance

Input handling, event loops, and state modeling questions

10. Resources

10.1 Essential Reading

“Clean Architecture”

10.2 Video Resources

Conference talks on terminal UI architecture (choose one and take notes)

10.3 Tools & Documentation

terminfo, curses, or framework docs used in this project

See other projects in this folder for follow-on ideas

11. Self-Assessment Checklist

11.1 Understanding

I can explain the rendering pipeline for this project
I can explain how input is decoded and normalized
I can explain how my UI state updates per event

11.2 Implementation

All functional requirements are met
All critical test cases pass
Edge cases are handled and documented

11.3 Growth

I documented lessons learned
I can explain this project in a job interview

12. Submission / Completion Criteria

Minimum Viable Completion:

Program runs and matches Real World Outcome
Terminal state restored on exit
Main interaction works

Full Completion:

All minimum criteria plus:
Resize handling and error states
Tests for core parsing and rendering

Excellence (Going Above & Beyond):

Performance profiling results included
Additional features from Extensions completed

Project 4: Screen Diff Renderer

Quick Reference

1. Learning Objectives

2. All Theory Needed (Per-Concept Breakdown)

Screen Rendering, Buffering, and Diffing

3. Project Specification

3.1 What You Will Build

3.2 Functional Requirements

3.3 Non-Functional Requirements

3.4 Example Usage / Output

3.5 Data Formats / Schemas / Protocols

3.6 Edge Cases

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

3.7.2 Golden Path Demo (Deterministic)

3.7.3 If CLI: provide an exact terminal transcript

3.7.4 Failure Demo (Deterministic)

4. Solution Architecture

4.1 High-Level Design

4.2 Key Components

4.3 Data Structures (No Full Code)

4.4 Algorithm Overview

5. Implementation Guide

5.1 Development Environment Setup

5.2 Project Structure

5.3 The Core Question You’re Answering

5.4 Concepts You Must Understand First

5.5 Questions to Guide Your Design

5.6 Thinking Exercise

5.7 The Interview Questions They’ll Ask

5.8 Hints in Layers

5.9 Books That Will Help

5.10 Implementation Phases

Phase 1: Foundation

Phase 2: Core Functionality

Phase 3: Polish & Edge Cases

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

6.3 Test Data

7. Common Pitfalls & Debugging

8. Extensions & Challenges

8.1 Beginner Extensions

8.2 Intermediate Extensions

8.3 Advanced Extensions

9. Real-World Connections

9.1 Industry Applications

9.2 Related Open Source Projects

9.3 Interview Relevance

10. Resources

10.1 Essential Reading

10.2 Video Resources

10.3 Tools & Documentation

10.4 Related Projects in This Series

11. Self-Assessment Checklist

11.1 Understanding

11.2 Implementation

11.3 Growth

12. Submission / Completion Criteria