// ZTERMINAL — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zterminal is a fast, GPU-accelerated terminal emulator written in Rust, organized as a 5-crate workspace. A terminal engine (zterminal_core) owns the xterm-compatible VT parser, the grid and scrollback, inline-graphics state, and PTY I/O; the application shell (zterminal) owns the OpenGL ES 2.0 glyph-atlas renderer, window/display driver, the native binary-split pane tree, input and keybindings, and a configuration model bridged to an in-process WebView control panel. tmux integration rides on a dedicated wire-protocol client (ztmux-core) that speaks imsg framing directly to the server socket — no tmux subprocess. Configuration is deserialized through a custom derive crate (zterminal_config_derive). ~60k Rust source lines across 118 files + ~6.8k lines of control-panel JavaScript + 626 test functions, in a vendored, self-contained build with no external runtime dependencies, targeting Linux, BSD, macOS, and Windows.

#SUBSYSTEM BREAKDOWN

Source partitioned by role across the workspace, measured in total source lines. The application shell’s event loop and configuration surface lead, followed closely by the VT engine, the GPU renderer, and the display/windowing driver. Percentages are of the 59,947-line Rust slice.

$TOP 20 FILES BY SIZE

The 20 largest source files account for 58.2% of the Rust slice. The event loop and the terminal-state core are by far the largest single files — the two hubs that everything else hangs off.

@DATA-FLOW PIPELINE

Bytes flow from the child PTY through the VT engine into the grid, then onto the GPU. An image scanner sits ahead of the escape parser so Kitty / Sixel / iTerm2 sequences are peeled off and uploaded as textures while ordinary text and control sequences pass through untouched. tmux traffic takes a parallel path over the wire-protocol client.

  child process (shell, vim, htop, …)
       │  PTY
       ▼
  ┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
  │  core/tty/   │────▶│ graphics/scanner │────▶│  core/term/  │
  │  (1,601)     │     │  (peel Kitty /   │     │  (5,392)     │
  │  PTY read/   │     │   Sixel / iTerm2 │     │  VT / xterm  │
  │  write loop  │     │   image seqs)    │     │  parser      │
  └──────────────┘     └────────┬─────────┘     └──────┬───────┘
                                │                       │
                       image bytes                cell writes
                                │                       │
                                ▼                       ▼
                       ┌──────────────┐         ┌──────────────┐
                       │ core/graphics│         │  core/grid/  │
                       │  (2,189)     │         │  (2,519)     │
                       │  placements  │         │  cells +     │
                       │  + GPU queue │         │  scrollback  │
                       └──────┬───────┘         └──────┬───────┘
                              │                        │
                              └───────────┬────────────┘
                                          ▼
                              ┌───────────────────────┐
                              │   renderer/ (4,672)   │
                              │  GLES2 glyph atlas +  │
                              │  image texture blits  │
                              └───────────┬───────────┘
                                          ▼
                              ┌───────────────────────┐
                              │   display/ (4,958)    │
                              │  per-window draw,     │
                              │  panes, overlays      │
                              └───────────────────────┘

  tmux:  crates/ztmux-core (2,359, own repo)  ──imsg / socket──▶  server  (no subprocess)
  input: input/ (2,348)  ──key/mouse → action──▶  event.rs (4,572)  ──▶  term / display

&SUBSYSTEM HIGHLIGHTS

What each major subsystem ships. Nine of these — live tmux config, profile-switchable tmux state, the in-app telemetry dashboard, retroactive output diff, cross-run numeric trend, in-place column sort, live broadcast-divergence, the durable command-block ledger and the cross-command relational JOIN — are terminal-emulator firsts; see Inventions.

~MEASUREMENT NOTES

How the numbers were counted, so they can be reproduced.

• Rust source lines (59,947) & files (113) — wc -l over every *.rs under the five workspace crates’ src/ trees (zterminal, zterminal_core, zterminal_config, zterminal_config_derive, crates/zterminal-ledger), excluding target/ and the zgui-core submodule.
• Code lines (44,844) — tokei, Rust only, excluding comments and blank lines.
• Test functions (600) — count of #[test] / #[tokio::test] attributes across the same trees.
• Control-panel JS (6,481) — wc -l over settings/ + frontend/ JavaScript, excluding the vendored zgui-core component library.
• Dependencies — 41 direct dependencies declared in zterminal/Cargo.toml (29 plain, 3 path deps on the sibling crates, 9 target-gated); 573 total crates resolved in Cargo.lock (full transitive tree).
• Subsystem percentages — each subsystem’s total source lines as a fraction of 59,947; rows sum to 100%.