wterm: The Terminal Emulator That Chooses the DOM on Purpose

A tiny Zig/WASM core, dirty-row updates, and native browser text features make this web terminal feel like a reversal of terminal design, not an imitation of it.

8 min read • View on GitHub • More from vercel-labs

A wide editorial scene showing a terminal built as layered browser text rows in front of a compact machine room below. The visible layer behaves like real DOM content with selection and search, while a small Zig and WASM engine quietly drives updates from underneath. It explains that wterm treats the browser's text layer as the point, not a compromise.
wterm reverses the usual web-terminal instinct: it keeps the visible surface in the DOM and pushes the hard work into a small WASM core.

wterm ("dub-term") renders to the DOM — native text selection, copy/paste, find, and accessibility come for free.

vercel-labs/wterm README, Documentation · wterm
Key Takeaways

The browser terminal that uses the browser

Most web terminals fight the DOM. wterm does the opposite. It keeps the visible surface in HTML, so the browser can do what it already does well: select text, search text, expose text to assistive tech, and let users interact with actual nodes instead of a painted bitmap.

That is the whole bet. The repo is not trying to prove that the DOM can match a GPU in every workload. It is arguing that a terminal for the web should start by exploiting browser-native strengths, then recover the performance it needs with a small WASM core and ruthless update discipline.

A hedcut-style portrait of ctate based on the GitHub avatar. It shows the project's primary creator as a verified reference image, not an imagined face, and anchors the article in a real maintainer.

Why the DOM is the feature, not the fallback

Dimensionwtermxterm.jsghostty-web
Core languageZig compiled to WASMJavaScriptZig compiled to WASM
Rendering modelDOM rowsCanvas first, DOM fallbackDOM via xterm.js-style API
Memory styleDirect reads from WASM memoryJS objects and canvas stateWASM terminal core with larger footprint
Best fitBrowser-native text workflowsMature general-purpose web terminalsCorrectness-focused terminal emulation
API stanceCustom, with React wrapperWidely adopted ecosystem APICompatibility-oriented

The contrast is strategic. xterm.js is the safe baseline: mature, familiar, and widely integrated. ghostty-web is the correctness-heavy WASM wave. wterm chooses a narrower lane by optimizing for the browser as a document surface, not just a display target.

That matters when the terminal is part of a product, not just a widget. If your users need selection, copy, Find, and accessibility to behave like first-class browser features, the DOM is not a fallback. It is the product requirement.

A byte’s journey through wterm

This diagram shows the core trick. A byte does not trigger a full repaint. It becomes a row update, and only the dirty row crosses the bridge into the DOM.

The cleanest way to understand wterm is to follow one character. A byte arrives over the WebSocket transport, lands in the Zig parser, and moves through the parser state machine, which handles Ground, Escape, CSI, and OSC states without allocating a giant pile of transient objects.

From there, the terminal mutates its grid, marks the affected row dirty, and leaves the rest alone. The TypeScript bridge reads the WASM memory directly, checks which rows actually changed, and updates only those DOM rows. That is the performance story in one sentence: less marshaling, less repainting, less churn.

A close-up editorial scene of a single terminal row lighting up while neighboring rows remain still. A byte stream feeds one parser path, then only one row in the grid is repainted. It explains dirty-row tracking and why wterm can stay DOM-based without redrawing everything.
Dirty-row tracking is the bridge between browser-native text and selective repainting. One changed row moves. The rest stay quiet.

The Zig engine under the hood

The engine is intentionally small. The repo’s Zig core uses fixed-size grids, predictable memory layouts, and extern-compatible structs so the browser side can read terminal state without a translation layer that invents its own model of the world.

pub const Cell = extern struct {
    ch: u32,
    fg: u16,
    bg: u16,
    flags: u8,
    _pad: u8,
};

pub const Terminal = struct {
    grid: [MAX_ROWS][MAX_COLS]Cell,
    dirty_rows: [MAX_ROWS]bool,
    // main and alternate screen buffers live here
};

That discipline pays off in two places. First, the parser can stay zero-allocation and deterministic. Second, the TypeScript bridge can use raw offsets and pointers instead of asking WASM to serialize a terminal snapshot into JSON every frame.

This is why Zig makes sense here. The language is not a brand choice. It is a way to keep the memory map legible enough that a web runtime can treat it almost like shared hardware.

The bridge that skips the JSON tax

The bridge layer is where the design turns from clever to useful. `WasmBridge` reads grid pointers and dirty-row bits directly from WASM memory, so the JavaScript side only touches rows that have actually changed.

That matters because the expensive part of a terminal is rarely a single character. It is the cascade of work that happens when an app writes many small updates in rapid succession. wterm cuts the cascade at the bridge, then lets requestAnimationFrame batch the real DOM work into a tight update cycle.

The result is not that DOM becomes free. It is that DOM becomes affordable. That is a different claim, and a much more interesting one.

Why this matters now

wterm fits the current shape of web software better than a classic terminal library would. Browser IDEs, remote shells, AI-agent consoles, and in-browser developer tools all want the same thing: real terminal behavior inside an interface that still feels like the web.

The repo structure makes that ambition obvious. `@wterm/core` handles the bridge, `@wterm/dom` renders the rows, `@wterm/react` wraps the API for app code, and `@wterm/just-bash` hints at a future where the terminal is not just a view onto a machine elsewhere, but part of the machine itself.

Questionwterm answerWhy it matters
Can the browser help with text interaction?Yes, because the terminal lives in the DOM.Selection, copy, Find, and accessibility work like normal page content.
Can performance stay sane?Yes, because only dirty rows update.The browser does less work on each frame.
Can the core stay small?Yes, because Zig keeps the data model strict.Direct reads from WASM become practical.
Is it just another terminal clone?No, it is a browser-native rendering strategy.The project has a different product shape.

What wterm is not

wterm is not trying to win by being the most compatible xterm replacement on day one. It is also not a straight port of a native terminal that happened to land in the browser. Its identity comes from the combination of DOM rendering, a minimal Zig/WASM engine, and a bridge that only moves the rows that changed.

That makes the project feel less like a clone and more like a thesis. The thesis is simple: if the browser is the host, the browser should also be part of the renderer.

The bigger implication

The interesting takeaway is not that terminals belong in the browser. That ship sailed. The interesting takeaway is that the browser itself may be better infrastructure for a terminal than we gave it credit for, as long as the engine underneath is disciplined enough to avoid turning HTML into a repaint storm.

wterm suggests a future where the DOM is not the thing serious apps escape. It is the thing they use on purpose.