zterm/AGENTS.md

zterm

GPU-accelerated Wayland terminal emulator. Single Rust crate, edition 2024.

Build & Run

cargo run              # dev build, Wayland only
cargo build --release  # release
cargo test             # tests

Features

Feature	Effect
webm (default)	Enable WebM video via ffmpeg-next 8.x
render_timing	Enable per-frame parse/render timing instrumentation
production	log/release_max_level_off — zero logging overhead

Disable webm: --no-default-features --features render_timing

Architecture

• Single process: owns PTY, terminal state, rendering. No multi-process IPC.
• Kitty-style shared parser (SharedParser in vt_parser.rs): 1MB ring buffer. I/O thread writes directly into it; main thread parses in-place. Lock released during parsing so I/O continues.
• Split tree (SplitNode in main.rs): binary tree of panes. Layout computed via recursive layout() pass.
• GPU rendering (renderer.rs): wgpu + WGSL shaders. Instanced rendering with sprite atlas. Per-pane GPU buffers.
• Kitty graphics protocol (graphics.rs): PNG, GIF, WebM inline images.

Key files

File	Contents
src/main.rs	App state machine, event loop, split tree, tab/pane management, keybindings
src/terminal.rs	Terminal grid, scrollback buffer, cursor, colors, cell attributes, Handler impl
src/vt_parser.rs	SharedParser (ring buffer + I/O), Parser (VT escape sequence parsing), Handler trait
src/renderer.rs	wgpu renderer, glyph atlas, font loading, instanced rendering pipeline
src/graphics.rs	Kitty graphics protocol parser (PNG/GIF/WebM)
src/config.rs	JSON config from ~/.config/zterm/config.json, keybinding resolver
src/pty.rs	PTY master, fork/exec child shell, SIGWINCH resize
src/pipeline.rs	wgpu pipeline builder
src/keyboard.rs	Kitty keyboard protocol, key encoding
zterm.terminfo	Custom terminfo — install with tic -x -o ~/.terminfo zterm.terminfo
src/bin/bench_process.rs	Benchmark binary

Shaders

WGSL files: src/glyph_shader.wgsl, src/image_shader.wgsl, src/quad_shader.wgsl, src/statusline_shader.wgsl, src/shader.wgsl (edge glow).

Config

~/.config/zterm/config.json — auto-created on first run. Fields: font_family, font_size, tab_bar_position, background_opacity, scrollback_lines, inactive_pane_fade_ms, inactive_pane_dim, edge_glow_intensity, pass_keys_to_programs, keybindings.

Style

• .rustfmt.toml: max_width = 80
• .gitignore excludes Cargo.lock and /benches (unusual for Rust)

Testing

Tests live inline in source files: vt_parser.rs, simd_utf8.rs, graphics.rs, vt_test_osc.rs. Run with cargo test.

Setup

• Wayland compositor required (X11 not supported)
• FFmpeg 5.x–8.x system libraries (for webm feature)
• terminfo: install zterm.terminfo so shells know the terminal type
• Nerd Font recommended for statusline icons (folder, branch, etc.)