Solo terminal vs xterm.js

The terminal lives with the process. The Rust core reads the PTY, runs every byte through its parser, and keeps the grid, cursor, modes, and scrollback. That's the only copy of the truth.

A viewer is a renderer. It receives structured operations (replace this row, replace these cells, insert rows, move the cursor) and paints them. It never sees an escape sequence, so you can throw it away, reload it, or open three of them without anything drifting.

The terminal lives in the page. xterm.js parses the bytes, keeps the buffer, and renders it, all in JavaScript on the main thread. A request to move parts of it into a web worker was closed as out of scope for now.

For a terminal that belongs to one tab, that's simple and exactly right. You hand it bytes and it does everything else.

Every attach to a terminal gets its own sequence numbers, delivery queue, and credit. The core diffs each frame into patches, coalesces them to about 60 per second per viewer, and sends each viewer only what it hasn't seen.

Frame patches are binary MessagePack with a deduplicated style table. A slow viewer falls behind on its own, and the others don't notice.

Each client is its own terminal. To show one session in two places, you send the same raw bytes to both, and each parses and buffers its own copy.

That works when every client is online from the start. A client that joins late needs the history first, which is where headless and serialize come in.

Delivery runs on exact receipts. Every body carries a random 128-bit token, and the viewer sends it back as soon as the body arrives. Each viewer gets 8 messages or 1 MiB of frame and history data in flight. Credit comes back only for receipts that match an exact body, never for a timeout or a count.

The core never waits on the UI, so a flood can't stall the child process. If a viewer falls too far behind, its queued patches are dropped and it gets a fresh snapshot instead of a backlog.

xterm.js has an official flow control guide, and it's worth reading. A fast program can produce far more than xterm.js can parse, and data past its 50 MB write buffer is discarded.

The guide suggests pausing the PTY with write callbacks and watermarks. Across a network, you carry that accounting yourself with your own ACK messages. The guide also warns that a badly tuned scheme can stall the stream for good.

When a viewer attaches, it says what it already has: run epoch, history generation, and screen sequence. If the core still holds the missing patches (up to 256), the viewer resumes from where it left off. Otherwise it gets a full snapshot.

Patches from an old run or an old attach are rejected, so restarting a process can't paint stale output on top of new output.

The usual pattern is to keep @xterm/headless on the server and use the serialize addon to write the buffer out as escape sequences, then replay them into a fresh client terminal. VS Code's terminal reconnects this way, so it clearly works at scale.

Both pieces are marked experimental. Serialize is a full-state replay rather than a diff, and it recommends restoring into a terminal of the same size. Ordering and staleness after restarts are up to your protocol.

Scrollback belongs to the core: 10,000 lines in compact 256-line pages. A viewer gets a 400-line tail on attach, holds about 2,000 lines around where you're looking, and fetches older pages on demand.

So an agent that's been running all day costs a new viewer about the same to open as one that started a minute ago.

Scrollback lives in the client buffer, and the default is 1,000 lines. VS Code's own setting notes that memory is allocated based on this value, so a bigger number costs more memory in every client.

For a session you open, use, and close, that's rarely a problem.

Solo's renderer draws with WebGL2 from a glyph atlas, with box-drawing characters drawn procedurally, and uploads only the rows that changed. It falls back to Canvas 2D if WebGL2 setup fails, the context is lost, or Linux is software rendering. Theme and font changes apply in place.

Big frames decode in a web worker before they reach the renderer.

xterm.js 6 ships a DOM renderer by default and a WebGL2 renderer as an addon. The canvas renderer was removed in 6.0. An experimental WebGPU renderer is in review but not released.

The WebGL addon is the fast path, and it's mature.