Section 2: The Minimal Terminal Emulator

Your Section 1 runner relays \x1b[31mred\x1b[0m faithfully and understands nothing. This section is where the bytes acquire meaning.

You will build a terminal core that consumes bytes from a PTY and maintains an in-memory terminal screen — a grid of cells with a cursor, styles, scrollback, modes, and an alternate buffer. It is a library (terminal-core, on top of terminal-protocol) with no I/O, no threads, and no rendering. That constraint is what makes it testable, embeddable, and — in Section 5 — reusable.

No existing terminal emulator core is used here. Not vte, not alacritty_terminal, not termwiz. They appear only in differential testing, after yours works.

The Deliberately Limited Starting Point

Version 1 supports exactly seven things. Resist adding an eighth until all seven are tested.

Then, incrementally, in roughly this order:

 UTF-8 decoding ──▶ CSI sequences ──▶ SGR styling ──▶ cursor movement ──▶ erase ops
        │
        ▼
 save/restore cursor ──▶ scroll regions ──▶ alternate screen ──▶ insert/delete ops
        │
        ▼
 wide characters ──▶ combining characters ──▶ OSC sequences ──▶ window titles
        │
        ▼
 hyperlinks ──▶ bracketed paste ──▶ mouse reporting ──▶ application cursor keys
        │
        ▼
 DEC private modes (the long tail)

Each step gets: the raw bytes, the parser recognition, the state transition, the screen before and after, a focused unit test, and a shell command that generates the sequence. All six. Every time.

The Chapters

The Labs

The Architecture You Are Building

   bytes from the PTY master
        │
        ▼
 ┌────────────────────────────────────────────────────────────────┐
 │  terminal-protocol                                             │
 │  ┌──────────────────┐      ┌────────────────────────────────┐  │
 │  │ VT state machine │─────▶│  Perform trait (your callback) │  │
 │  │ ground/esc/csi/  │      │   print(char)                  │  │
 │  │ osc/dcs/...      │      │   execute(byte)                │  │
 │  │  + UTF-8 decoder │      │   csi_dispatch(params, .., 'm')│  │
 │  │    inside GROUND │      │   esc_dispatch / osc_dispatch  │  │
 │  └──────────────────┘      │   hook / put / unhook  (DCS)   │  │
 │      NO screen. NO I/O.    └────────────────────────────────┘  │
 └────────────────────────────────────────────────────────────────┘
        │  parsed actions
        ▼
 ┌────────────────────────────────────────────────────────────────┐
 │  terminal-core                                                 │
 │    Terminal { screen, cursor, modes, tabs, title, damage }     │
 │      impl Perform for Terminal  ← the meaning lives HERE       │
 │    Screen { primary: Grid, alternate: Grid, scrollback }       │
 │    Grid   { rows, cols, lines }                                │
 │    Cursor { row, col, style, pending_wrap, saved }             │
 │    replies: Vec<u8>   ← answers to DSR/DA, for the CALLER to   │
 │                          write back to the PTY                 │
 │      NO I/O. NO fonts. NO threads.                             │
 └────────────────────────────────────────────────────────────────┘
        │  screen state + damage
        ▼
   a snapshot (text, JSON) or a renderer  ← Section 3

The two boundaries that matter:

1. The parser does not know what sequences mean. It knows CSI with params [2] and final byte J. That 2 means "erase the whole screen" is terminal-core's knowledge. Keeping them separate is what lets you fuzz the parser, reuse it, and test it without a screen.
2. The core does no I/O. Terminal replies (the answer to CSI 6n) are appended to a buffer the caller drains and writes to the PTY. The core never touches a file descriptor.

Why That Separation Matters (The Concrete Payoff)

Deliverables for This Section

• terminal-protocol implements the full VT state machine; feeding input byte-at-a-time produces an identical action stream to feeding it all at once.
• A fuzz target for the parser that has run ≥10 minutes with no panic and no hang.
• terminal-core implements every sequence in the CSI catalog, each with a unit test that shows the screen before and after.
• Pending wrap (deferred DECAWM) implemented and tested explicitly.
• Alternate screen, scroll regions, insert/delete, and save/restore cursor.
• UTF-8, wide characters, and combining marks handled, with the invariant "a wide cell is always followed by its spacer" enforced and property-tested.
• OSC title, OSC 8 hyperlinks, bracketed paste, and SGR mouse reporting.
• terminal-cli produces byte-identical snapshots across runs.
• ≥10 golden test cases from your Lab 5 corpus.
• A debug mode showing raw bytes, UTF-8 events, parser states, actions, cursor moves, dirty rows, buffer changes, and mode changes.

Common Mistakes in This Section

How to Verify Success

# 1. Determinism.
mini-term run --rows 24 --cols 80 -- printf 'hello\n' > a.txt
mini-term run --rows 24 --cols 80 -- printf 'hello\n' > b.txt
diff a.txt b.txt && echo DETERMINISTIC

# 2. Byte-at-a-time equivalence (the parser correctness test).
cargo test -p terminal-core --test golden -- --nocapture
#   every golden case is replayed in both modes and the screens compared

# 3. Colors.
mini-term run --rows 3 --cols 20 --format debug -- printf '\033[31mred\033[0m\n'
#   cells 0..3 of row 0 must carry fg=Red

# 4. Wrapping, the classic.
mini-term run --rows 5 --cols 80 -- python3 -c 'print("x" * 100)'
#   row 0: 80 x's;  row 1: 20 x's;  cursor on row 2 col 0

# 5. Pending wrap, the subtle one.
mini-term run --rows 5 --cols 10 --format debug -- printf '0123456789'
#   cursor must be at row 0, col 9 with pending_wrap SET — NOT row 1 col 0

# 6. No panics on garbage.
head -c 100000 /dev/urandom | mini-term replay --stdin --rows 24 --cols 80

Section Profile: What a Section 2 Graduate Can Do

Next: Separation of Concerns.