# 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.)