Originally published on MistLab. Part 3 of Building an SSH Terminal.

Part 3 of "Building an SSH Terminal". Code excerpts are from MistTerm v1.2.26, an open-source (AGPL) SSH terminal client by MistLab; they are trimmed

TL;DR

Bracketed paste is an xterm mode (DEC private mode 2004). Once a program enables it, the terminal wraps each paste in ESC[200~ … ESC[201~, so pasted newlines are inserted as text instead of acting as Enter. Readline turns it on by default from version 8.1. Separately, Linux's n_tty caps a canonical-mode line at 4095 bytes plus the newline. Large pastes should be sent in chunks that never split a UTF-8 character.

To a terminal, pasting is typing very fast. The clipboard text is written to the PTY exactly as if the user had typed it. Nothing in the byte stream separates "typed" from "pasted". That causes three separate problems. The shell cannot tell a pasted newline from a pressed Enter. The kernel limits how long one line can be. And splitting a large paste into chunks can cut a multi-byte character in half.

Problem 1: a pasted newline is an Enter. How does bracketed paste work?

Paste three lines into bash without any protocol and bash runs each line as soon as its newline arrives. That is inconvenient for a multi-line snippet. It is dangerous for text copied from a web page, which can contain content you never saw rendered, a newline included.

The fix is bracketed paste, an xterm extension documented in ctlseqs. A program that wants it enables DEC private mode 2004 (CSI ? 2004 h). From then on, the terminal wraps each paste:

ESC [ 2 0 0 ~   <pasted text>   ESC [ 2 0 1 ~

Bracketed paste: the program asks for mode 2004, the terminal wraps the paste

A program that sees the start marker treats everything up to the end marker as literal text. Readline inserts it into the line buffer without executing it, zsh's line editor (since zsh 5.1) does the same, and Vim, documented under :help xterm-bracketed-paste, inserts it without auto-indent.

In GNU Readline, the library behind bash's prompt, bracketed paste became on by default in readline 8.1. The NEWS entry reads "Bracketed paste mode is enabled by default", and the source shows the switch:

/* readline-8.1, rlprivate.h */
#define BRACKETED_PASTE_DEFAULT 1
/* readline-8.1, readline.c */
int _rl_enable_bracketed_paste = BRACKETED_PASTE_DEFAULT;

In readline 8.0 the same variable is initialized to 0. Bash 5.1 ships readline 8.1, so on current distributions an interactive bash asks for mode 2004 unless the user has set enable-bracketed-paste off in .inputrc. Readline also leaves the mode off for terminals it considers unsuitable (see terminal.c), such as TERM=dumb.

The terminal's side of the contract is small but has to be exact. MistTerm checks the mode bit the remote program set (Part 1), normalizes line endings, and wraps the payload:

// src/ui/terminal_paste.rs
/// Normalize newlines to `\n`; when bracketed paste is on, wrap in
/// `ESC[200~ … ESC[201~` and strip forged markers from the body
/// (so pasted content cannot "end the paste" early and be run as commands).
pub fn build_paste_payload(text: &str, bracketed: bool) -> Vec<u8> {
    let normalized = text.replace("\r\n", "\n").replace('\r', "\n");
    if !bracketed {
        return normalized.into_bytes();
    }
    let body = normalized.replace("\x1b[200~", "").replace("\x1b[201~", "");
    let mut out = Vec::with_capacity(body.len() + BP_START.len() + BP_END.len());
    out.extend_from_slice(BP_START);
    out.extend_from_slice(body.as_bytes());
    out.extend_from_slice(BP_END);
    out
}

The marker stripping is the security-relevant line. If clipboard text contains a literal ESC[201~, a naive terminal forwards it, the program believes the paste ended, and whatever follows is interpreted as typed input, newline and all. The unit test pins this behavior:

let p = build_paste_payload("ls\x1b[201~rm -rf x\n", true);
assert_eq!(p, b"\x1b[200~lsrm -rf x\n\x1b[201~");

Bracketed paste only helps if the receiving program enabled it. In a program that did not (a plain cat, a script reading with read, a REPL without support), a pasted newline is still an Enter. That is a property of the program, not something a terminal can change.

Problem 2: why are long pasted lines cut at 4095 bytes?

Programs that leave the TTY in canonical mode (POSIX termios ICANON) do not edit lines themselves. cat, the shell builtin read and Python's input() when stdin is not readline-enabled all fall in this group. The kernel's line discipline buffers input until a newline and implements Backspace, Ctrl-U and similar editing. That buffer is finite.

On Linux the buffer is defined in drivers/tty/n_tty.c:

#define N_TTY_BUF_SIZE 4096

n_tty_receive_buf_common handles the full-buffer case. In canonical mode, when the buffer is full and contains no complete line, the kernel keeps one slot free by re-using the last position. That lets a terminating newline still be accepted, while further characters are discarded. The effective result is that one canonical-mode line holds at most 4095 bytes plus its newline. Anything beyond is silently lost, and the reading program never knows.

Canonical-mode line buffer on Linux

Two details are easy to get wrong:

• The MAX_CANON constant in Linux's <linux/limits.h> is 255. It is not the limit that n_tty enforces. POSIX only requires MAX_CANON to be at least 255.
• The number is Linux-specific. macOS and the BSDs have a different TTY implementation, and macOS's <sys/syslimits.h> declares MAX_CANON as 1024. We have not measured macOS's actual behavior, so this series makes no claim about it beyond the header value.

A terminal cannot work around this. The limit is in the server's kernel, below sshd. What a terminal can do is warn. SSH gives the client no way to query the remote termios state, so MistTerm uses the best signal it has. If the remote program has not enabled bracketed paste and some line in the clipboard is longer than 4095 bytes, it shows a warning before sending:

let bracketed = self.terminal.is_bracketed_paste();
// In line mode (cat/read, …) a single line > 4095 bytes is truncated by the
// tty layer; the terminal can't avoid that, so tell the user.
if !bracketed && exceeds_canon_line_limit(&normalized) {
    self.pending_toast_error = Some(/* suggest SFTP upload or pasting in vim */);
}

This is a heuristic. A program in raw mode without bracketed paste would trigger a spurious warning. The text is still sent unchanged either way. Interactive shells and editors that enable bracketed paste run the TTY in non-canonical mode and read the bytes themselves, so they are not subject to this limit.

Problem 3: chunking without breaking characters

A paste of several megabytes cannot go to the session thread as one message (Part 2). MistTerm queues it and writes it in pieces of at most PASTE_CHUNK = 4096 bytes. Cutting a byte buffer at an arbitrary offset can split a UTF-8 sequence: a CJK character is three bytes and an emoji four. Most receivers reassemble the bytes correctly, but treating each write as a unit of text is common enough that it is worth not producing broken fragments. UTF-8 makes the boundary easy to find, because continuation bytes always match 10xxxxxx:

Backing up to a UTF-8 character boundary

/// Next chunk length: at most `max`, never splitting a UTF-8 multi-byte
/// character (unless a single character exceeds `max`).
pub fn next_chunk_len(buf: &[u8], max: usize) -> usize {
    if buf.len() <= max {
        return buf.len();
    }
    let mut n = max;
    // UTF-8 continuation bytes look like 10xxxxxx; back up to a character start.
    while n > 0 && (buf[n] & 0xC0) == 0x80 {
        n -= 1;
    }
    if n == 0 { max } else { n }
}

Note that the check is on buf[n], the first byte of the next chunk. If that byte is a continuation byte, the cut is inside a character, and the loop moves back to that character's lead byte.

The send loop is driven by the UI frame clock, not by a blocking loop. A chunk is removed from the pending buffer only after it was accepted by the session queue. If the queue is full, the same chunk is retried after 20 ms, up to 500 times (about ten seconds without progress). Otherwise the next chunk follows 5 ms later:

const GAP: Duration = Duration::from_millis(5);
const RETRY_GAP: Duration = Duration::from_millis(20);
const MAX_RETRIES: u32 = 500; // give up after ≈10 s without progress

If it finally gives up, the user is told how many bytes were not sent. A paste is never silently truncated by the terminal itself.

Summary

• Pasted newlines are indistinguishable from Enter unless the program enables bracketed paste (mode 2004). Readline enables it by default from 8.1 onward.
• A terminal implementing bracketed paste must strip ESC[200~/ESC[201~ from the pasted text, or the clipboard can break out of the paste.
• Linux canonical-mode lines are capped at 4095 bytes plus newline by n_tty. MAX_CANON (255) is not that limit, and other kernels differ.
• Chunk large writes on UTF-8 boundaries, and only drop a chunk after it has been accepted.

FAQ

How does bracketed paste work?

A program enables DEC private mode 2004 with CSI ? 2004 h. The terminal then wraps each paste in ESC[200~ and ESC[201~, and the program treats everything between them as literal text.

Is bracketed paste enabled by default in bash?

Readline enables it by default from 8.1, and bash 5.1 ships readline 8.1. Users can turn it off with enable-bracketed-paste off in .inputrc.

Why must a terminal strip ESC[201~ from pasted text?

If the clipboard contains the end marker, the rest of the paste would be treated as typed input, including its newlines.

Why are pasted lines longer than 4095 bytes cut off on Linux?

In canonical mode, Linux's n_tty line discipline holds at most 4095 bytes plus the newline. MAX_CANON (255) is not that limit. A terminal cannot work around it, but it can warn. Related in this series

• SSH Flow Control, and Why an SSH Client Must Keep Reading While It Writes
• Why Non-ASCII Input Breaks over SSH: Locales, SendEnv and the env Request

← Part 2 · Series index · Part 4 →

Originally published at https://mistlab.dev/stories/ssh-terminal-03-paste.html. Part of Building an SSH Terminal.

Originally published on MistLab. Part 2 of Building an SSH Terminal.

Part 2 of "Building an SSH Terminal". Code excerpts are from MistTerm v1.2.26, an open-source (AGPL) SSH terminal client by MistLab; they are trimmed

TL;DR

SSH flow control gives each direction of each channel a window: the number of bytes the sender may still send before the receiver grants more with SSH_MSG_CHANNEL_WINDOW_ADJUST (RFC 4254 §5.2). When the send window is zero, the client must keep reading the server's output. Otherwise it and the remote program can wait on each other forever. Keep network I/O off the GUI thread, and bound every wait.

Part 1 treated the terminal as a pipe that hands bytes to a parser. Those bytes come from, and keystrokes go to, an SSH channel on a server PTY. Two properties of that path decide how an interactive client is built: the channel is flow-controlled, and the GUI thread must never wait on the network.

The data path

Data path between the UI, the session thread and the remote shell

When you type l, the UI encodes the key and hands the bytes to the session layer. The SSH library encrypts them into an SSH_MSG_CHANNEL_DATA message (RFC 4254 §5.2). On the server, sshd writes the payload into the master side of a pseudo-terminal. The line discipline in the kernel's tty layer processes it (echo, line editing in canonical mode, signals such as Ctrl+C → SIGINT), and the shell reads from the slave side. Output takes the same path back.

Setting up that path takes three channel requests, all defined in RFC 4254. pty-req (§6.2) carries the terminal type, the size in characters and pixels, and encoded terminal modes. Optional env requests (§6.4) follow; Part 4 covers them. Finally shell (§6.5) starts the user's login shell. Resizing later uses window-change (§6.7). Despite the name, "window" there means the terminal window. It has nothing to do with the flow-control window below.

How does the SSH channel window work?

SSH multiplexes many channels over one TCP connection. To stop one fast channel from swamping the connection or the peer's memory, RFC 4254 §5.2 gives each direction of each channel a window: the number of bytes the sender may still transmit. Sending data consumes window. The receiver adds window back with SSH_MSG_CHANNEL_WINDOW_ADJUST after it has consumed data. When the window reaches zero, the sender must stop until an adjust arrives.

SSH channel window: writes stall at zero until the peer adjusts

For a terminal, the interesting case is a large write: a big paste, or a file upload streamed through the terminal (Part 5). The client keeps writing until its send window is exhausted and then has to wait. What it does while waiting matters.

The server only re-opens the client's window after its side has consumed input, which means the remote program has to be reading. Interactive programs are often busy writing at the same time: a shell echoing the pasted text, or a progress display. If the client is not reading the server's output, the client never re-grants window in the other direction. The server stops sending, the remote program blocks on its own write(), stops reading its input, and the client's send window stays at zero. Neither side can make progress. A writer has to keep reading.

Avoiding the write deadlock: write with drain

MistTerm puts this rule in one function used for all large PTY writes, write_pty_with_drain in src/ssh/manager.rs. The session runs in non-blocking mode (sess.set_blocking(false)), so a write either makes progress or returns immediately. The core of the loop:

const MAX_NO_PROGRESS: usize = 6_000;   // × 150µs sleep ≈ 0.9 s without progress → error
const CHUNK_CEIL: usize = 256 * 1024;

while !rest.is_empty() {
    let len_before = rest.len();
    let win = channel.write_window().remaining as usize;
    if win == 0 {
        // no send window: read output instead, so the peer can make progress
        Self::pump_channel_reads(channel, read_buffer, message_tx, session_id, upload_bypass, None)?;
    } else {
        let chunk = rest.len().min(win).min(CHUNK_CEIL).max(1);
        match channel.write(&rest[..chunk]) {
            Ok(0) => { /* drain reads */ }
            Ok(n) => {
                rest = &rest[n..];
                if !rest.is_empty() { /* drain reads between chunks */ }
            }
            Err(e) if Self::is_retryable_write_error(&e) => { /* drain reads */ }
            Err(e) => return Err(e),
        }
    }
    if rest.len() < len_before {
        no_progress = 0;
    } else {
        no_progress += 1;
        if no_progress > MAX_NO_PROGRESS { return Err(/* TimedOut */); }
        thread::sleep(Duration::from_micros(150));
    }
}

(The real code maps a closed channel to ConnectionAborted at each drain point and handles a library return value larger than the request. These are elided here.)

Three design choices are visible:

1. Never write more than the window. The chunk size is capped by write_window().remaining and by a fixed ceiling, so a write call never has more queued than the protocol allows.
2. Read whenever writing cannot proceed. A zero window, a zero-byte write and a would-block error all lead to pump_channel_reads. Output is forwarded to the terminal as it arrives, so the window in the other direction keeps flowing.
3. Bound the wait. The no-progress counter only grows when a whole iteration moved no bytes. After about 0.9 s of zero progress the write fails and returns control. Without that, a dead peer would hang the session thread forever.

Keep the network off the UI thread

The second rule concerns threads. egui is an immediate-mode GUI: the UI thread redraws every frame, and any blocking call on that thread freezes the window. SSH I/O blocks by nature. A write can sit in the drain loop above, and a library call can wait on the socket.

MistTerm gives each interactive session a dedicated OS thread, the shell pump, which alone owns the channel. The UI communicates with it only through bounded queues:

let (pump_tx, pump_rx) = sync_channel::<ShellPumpCommand>(SHELL_PUMP_QUEUE_CAP); // 512
let (interrupt_tx, interrupt_rx) = sync_channel::<Vec<u8>>(8);
let (resize_tx, resize_rx) = sync_channel::<(u32, u32)>(RESIZE_QUEUE_CAP);       // 16

Each loop iteration of the pump thread first drains the priority queue, then applies pending resizes, then waits up to 8 ms for one command. On timeout it services keepalive and reads output. Adjacent keystroke commands are merged into one write of up to 32 KiB before being sent, so a burst of typing costs one queue entry rather than hundreds.

The UI side never blocks on these queues. Every enqueue uses try_send:

/// Uses `try_send` (non-blocking): if the pump thread is stuck in
/// `write_pty_with_drain` or a long read and the queue is full, the caller
/// (the UI thread) is not blocked; an error is returned so the upper layer
/// can drop or degrade.
fn pump_send(&self, cmd: ShellPumpCommand) -> Result<(), String> {
    self.pump_tx.try_send(cmd).map_err(/* "shell pump queue full (cap=512) …" */)
}

This is a trade-off. A blocking send never loses input, but it ties UI responsiveness to the network. try_send keeps the window responsive and, under extreme backlog, reports a dropped command instead. With a 512-entry queue and keystroke merging, a full queue means the session is already effectively stalled.

The 8-entry priority queue exists for control bytes that must jump the queue, through send_priority_interrupt. In v1.2.26 its caller is the ZMODEM cancel path (Part 5). It sends eight CAN bytes, eight backspaces and Ctrl+C, so an aborted transfer is cancelled ahead of whatever file data is still queued.

Summary

• An SSH shell is three RFC 4254 requests (pty-req, env, shell) plus window-change for resizes.
• Channel data is window-limited in both directions. A client that only writes during a large transfer can deadlock with the remote program. Read whenever the write cannot proceed.
• Bound every wait, and keep all network I/O on a dedicated thread. The GUI talks to it through bounded, non-blocking queues.

Next: paste. Same big write, different ways it fails — bracketed paste, and the 4095-byte line.

FAQ

What is the SSH channel window?

A per-channel, per-direction count of bytes the sender may still transmit (RFC 4254 §5.2). Sending consumes it, and the receiver adds to it with SSH_MSG_CHANNEL_WINDOW_ADJUST after consuming data.

Why can a large paste hang an SSH session?

If the client only writes, it stops reading the server's output. The server stops sending, the remote program blocks on its own output and stops reading input, and the client's send window stays at zero.

Is the SSH window-change request related to flow control?

No. window-change (RFC 4254 §6.7) reports a new terminal size. The flow-control window is unrelated.

Which channel requests start an interactive SSH shell?

pty-req, optional env requests, then shell, all defined in RFC 4254. Related in this series

• What Happens When You Paste into a Terminal: Bracketed Paste, the 4095-Byte Line, and UTF-8 Boundaries
• Finding ZMODEM in a Terminal Byte Stream: How rz/sz Works Inside an SSH Client

← Part 1 · Series index · Part 3 →

Originally published at https://mistlab.dev/stories/ssh-terminal-02-ssh-channel.html. Part of Building an SSH Terminal.

Originally published on MistLab. This is Part 1 of the series Building an SSH Terminal.

Part 1 of "Building an SSH Terminal". Code excerpts are from MistTerm v1.2.26, an open-source (AGPL) SSH terminal client by MistLab, written in Rust; excerpts are trimmed.

TL;DR

A terminal emulator turns a byte stream from a program into pixels in three stages. A parser (a resumable state machine) splits the stream into printable characters and control sequences defined by ECMA-48 and xterm. A grid of character cells applies their meaning: cursor, scrolling regions, modes, wide characters, the alternate screen. A renderer then draws the grid. MistTerm uses alacritty_terminal for the parser and grid, and draws the grid itself with egui.

Type ls --color and colored file names appear. It feels immediate, but inside the terminal there are three distinct stages between the network and the screen. The remote program writes a stream of bytes with control sequences mixed in. A parser turns that stream into actions. Those actions mutate a grid of character cells. A renderer draws the grid. This article walks through each stage, what the standards say, and how MistTerm wires a mature emulator core into its own GUI.

How does a program talk to a terminal? Only through a byte stream

There is no API between a terminal and the program running in it. Programs such as bash, vim and top write bytes to standard output, and that is all. Printable characters are displayed. Everything else is an instruction to the terminal, encoded with conventions that go back to the DEC VT100 and were later standardized, in part, as ECMA-48 (ISO 6429):

• C0 controls — single bytes below 0x20: carriage return \r, line feed \n, backspace \b, tab \t, bell BEL.
• Escape sequences — ESC (0x1B) followed by one or more bytes.
• CSI sequences — ESC [, optional parameters, optional intermediates, a final byte in 0x40–0x7E. ESC[31m sets the foreground to red (SGR), ESC[2J erases the display, ESC[10;5H moves the cursor to row 10, column 5.
• OSC strings — ESC ] … terminated by BEL or the string terminator ESC \; used for window titles, hyperlinks and the like.
• DEC private modes — CSI ? Pm h to set and CSI ? Pm l to reset. Mode 1049 switches to the alternate screen (why vim and less seem to "take over" the screen and give it back on exit). Mode 2004 enables bracketed paste, which is the subject of Part 3.

ECMA-48 defines the syntax and many of the functions. The de facto reference for what a modern terminal is expected to do is xterm's Control Sequences document (ctlseqs), because most software assumes "xterm-compatible". That assumption is negotiated through $TERM: when MistTerm opens a session it requests a PTY with the terminal type xterm-256color, and programs on the server look that name up in the terminfo database to decide which sequences to emit.

// src/ssh/client.rs
channel
    .request_pty(
        "xterm-256color",
        None,
        Some((cols, rows, px_w, px_h)),
    )

Stage 1: how a VT parser state machine works

A byte stream has no message boundaries. One read() may end with ESC[3 and the next begin with 1m. The parser therefore has to keep state across calls and consume input one byte at a time.

The widely used model is Paul Williams' DEC-compatible parser (documented at vt100.net), which defines a dozen or so states — ground, escape, CSI entry/param/intermediate/ignore, OSC string, DCS states and so on — and a transition table for every byte value. Transitions emit actions: print a character, execute a C0 control, dispatch a completed escape, CSI or OSC sequence. Some transitions apply "anywhere": ESC always starts a new sequence, and CAN or SUB abort one.

A simplified VT parser state machine

In Rust this layer is the vte crate from the Alacritty project, whose parser is based on Williams' state machine. It deliberately stops at turning bytes into callbacks. It does not know what "erase in line" means.

Stage 2: the grid, where the semantics live

The meaning of each action is where most of the work is. The visible screen is a rows × columns array of cells. Each cell holds a character plus attributes (foreground, background, bold, underline, inverse, wide-character flags, …). Around it sit the cursor position and its saved copy, the set of active modes, scrolling margins, tab stops, the alternate screen, and scrollback history. The subtle rules are the ones applications notice:

• After DECSTBM sets a scrolling region, a line feed on its bottom margin scrolls only that region.
• The alternate screen has no scrollback.
• Writing in the last column leaves the cursor in a "pending wrap" state. The wrap happens only when the next printable character arrives.
• A double-width character occupies two cells. Overwriting either half must clear the other.

Whether tmux, vim and htop draw correctly depends on these details. Writing a parser takes an afternoon. Getting the grid semantics right takes years of comparing against xterm and test suites such as vttest.

That is why MistTerm does not implement them itself. alacritty_terminal packages the parser, grid and semantics from the Alacritty terminal as a library. MistTerm's adapter (src/terminal/alacritty.rs) feeds it bytes in one line:

pub fn feed(&mut self, data: &[u8]) {
    if !data.is_empty() {
        self.content_epoch = self.content_epoch.wrapping_add(1);
    }
    self.parser.advance(&mut self.term, data);
}

parser is an alacritty_terminal::vte::ansi::Processor and term is a Term. advance consumes a whole chunk and keeps any half-finished sequence for the next call. content_epoch is MistTerm's own counter. The UI compares it between frames and skips re-layout when nothing changed.

Mode queries go straight to Term. For example, this is how the paste code knows whether the remote program has asked for bracketed paste:

/// Whether the remote program enabled bracketed paste (DECSET 2004; bash/zsh/vim do).
pub fn is_bracketed_paste(&self) -> bool {
    self.term
        .mode()
        .contains(alacritty_terminal::term::TermMode::BRACKETED_PASTE)
}

The grid size must match the remote PTY. When the window is resized, the local Term is resized and the server is told through the SSH window-change channel request (RFC 4254 §6.7; request_pty_size in the ssh2 crate). Otherwise remote programs keep wrapping at the old width.

Stage 3: drawing the grid

Alacritty itself renders glyphs with OpenGL. MistTerm is a full desktop application with side panels, an SFTP browser and dialogs, built on egui (an immediate-mode GUI) with the wgpu backend. So the terminal area is drawn with egui's text layout too.

From PTY bytes to pixels in MistTerm

For each visible row, cells are converted into an egui LayoutJob. Consecutive cells with identical styling are merged into one run, so the layout engine handles a few dozen text segments instead of thousands of single characters:

let same_run = |a: &TextFormat, b: &TextFormat| {
    a.color == b.color
        && a.extra_letter_spacing == b.extra_letter_spacing
        && a.line_height == b.line_height
        && a.font_id == b.font_id
};
// …
for (ch, color, _bg, flags) in row {
    if flags.intersects(wide_spacer) {
        flush_run(&mut job, &mut run_text, &mut run_fmt);
        job.append("\u{200b}", 0.0, cell_fmt(color, 0.0));
        continue;
    }
    let spacing = if flags.contains(Flags::WIDE_CHAR) { cell_w.max(0.0) } else { 0.0 };
    // same format as the current run → push; otherwise flush and start a new run
}

Two details here exist because of CJK text:

1. Spacer cells. A wide character is stored as the character itself (flagged WIDE_CHAR) followed by a spacer cell (WIDE_CHAR_SPACER). The spacer must not draw anything, but every row has to keep the same number of cells. MistTerm emits a zero-width space for it.
2. Forcing the advance width. A monospace font's CJK glyph is not guaranteed to be exactly twice the width of its ASCII glyphs. Laid out naively, the error accumulates along the line and the text drifts away from the cursor. Adding extra_letter_spacing to wide characters forces each one to occupy exactly two cell widths.

Backgrounds are handled separately:

// Glyph layer background is always transparent; ANSI and selection backgrounds are
// painted by the UI, so egui's background expansion can't overlap adjacent lines.
let cell_fmt = |color: Color32, extra_spacing: f32| TextFormat {
    font_id: FontId::monospace(font_size),
    color,
    background: Color32::TRANSPARENT,
    line_height: Some(line_height),
    extra_letter_spacing: extra_spacing,
    valign: egui::Align::BOTTOM,
    ..Default::default()
};

A text engine paints a "background color" around each glyph's bounding box, which can bleed into neighboring lines. A terminal needs solid blocks aligned exactly to the cell grid. So MistTerm paints background rectangles itself from grid coordinates, and the text layer only draws foreground glyphs.

What is left to build

With the emulator core borrowed, what remains is the glue: where the bytes come from, where keystrokes go, when to repaint, and selection, search and scrollback in the GUI. The next article starts with where the bytes come from: the SSH channel, the remote PTY and flow control.

Summary

• A terminal and its program share only a byte stream. Control sequences follow ECMA-48 and xterm conventions, and $TERM tells the program which dialect to speak.
• Parsing is a resumable state machine (Williams' model, implemented by vte).
• The grid carries the hard semantics: margins, wrap state, modes, wide characters, alternate screen. alacritty_terminal provides a mature implementation.
• Rendering into a general GUI needs care: merge runs, give wide characters explicit spacing, and paint backgrounds per cell.

FAQ

What is the difference between the parser and the grid in a terminal emulator?

The parser only turns bytes into actions such as "print a character" or "dispatch a CSI sequence". The grid gives those actions their meaning: it holds the character cells, the cursor, scrolling margins, modes and the alternate screen.

What does TERM=xterm-256color do?

It tells programs on the server which terminal type to assume. They look the name up in the terminfo database to decide which control sequences to emit. MistTerm requests a PTY with that terminal type.

Why do CJK characters drift out of alignment in some terminals?

A monospace font's CJK glyph is not guaranteed to be exactly twice as wide as its ASCII glyphs, so small errors accumulate along a line. MistTerm forces each wide character to occupy exactly two cell widths.

Why does vim give the screen back when it exits?

It switches to the alternate screen with DEC private mode 1049 and switches back on exit. The alternate screen has no scrollback. Related in this series

• SSH Flow Control, and Why an SSH Client Must Keep Reading While It Writes
• What Happens When You Paste into a Terminal: Bracketed Paste, the 4095-Byte Line, and UTF-8 Boundaries

Series index · Part 2 →

Originally published at https://mistlab.dev/stories/ssh-terminal-01-emulation.html. Part of Building an SSH Terminal.