// 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). ~47k Rust source lines across 105 files + ~5k lines of control-panel JavaScript + 305 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 46,761-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,263)  ──imsg / socket──▶  server  (no subprocess)
  input: input/ (2,346)  ──key/mouse → action──▶  event.rs (4,233)  ──▶  term / display

&SUBSYSTEM HIGHLIGHTS

What each major subsystem ships. Three of these — live tmux config, profile-switchable tmux state, and the in-app telemetry dashboard — are terminal-emulator firsts; see Inventions.

~MEASUREMENT NOTES

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

• Rust source lines (46,761) & files (105) — wc -l over every *.rs under the five workspace crates’ src/ trees (zterminal, zterminal_core, zterminal_config, zterminal_config_derive, crates/ztmux-core), excluding target/ and the zgui-core submodule.
• Code lines (35,435) — tokei, Rust only, excluding comments and blank lines.
• Test functions (305) — count of #[test] / #[tokio::test] attributes across the same trees.
• Control-panel JS (4,954) — wc -l over settings/ + frontend/ JavaScript, excluding the vendored zgui-core component library.
• Dependencies — 41 direct dependencies declared in zterminal/Cargo.toml; 535 total crates resolved in Cargo.lock (full transitive tree).
• Subsystem percentages — each subsystem’s total source lines as a fraction of 46,761; rows sum to 100%.