Files
psyTerm/README.md
T

6.7 KiB

Terminal

A small GPU-rendered terminal built with GPUI 0.2.2 and alacritty_terminal 0.26.0. The initial target is Linux desktop on Wayland. Alacritty provides the terminal state machine, VTE parser, scrollback, PTY, and shell I/O; GPUI provides the window, text rendering, and desktop input.

Build and run

Use a recent stable Rust toolchain; development currently uses Rust 1.96. Launch from Linux 5.3 or newer (pidfd-based shell cleanup), in a running Wayland desktop with WAYLAND_DISPLAY set and a working Vulkan driver. This build enables GPUI's Wayland backend only.

Representative Fedora dependencies:

sudo dnf install gcc gcc-c++ make cmake pkgconf-pkg-config \
  fontconfig-devel freetype-devel libxkbcommon-devel libxkbcommon-x11-devel \
  libxcb-devel wayland-devel openssl-devel vulkan-loader mesa-vulkan-drivers \
  dejavu-sans-mono-fonts

Representative Ubuntu dependencies:

sudo apt install build-essential cmake pkg-config \
  libfontconfig1-dev libfreetype6-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libxcb1-dev libwayland-dev libssl-dev libvulkan1 mesa-vulkan-drivers \
  fonts-dejavu-core

The package names follow the relevant portions of Zed's Linux dependency script. Your GPU may need its vendor's Vulkan driver instead of Mesa. GPUI 0.2.2 also links the XKB X11 library even when only its Wayland window backend is enabled.

cargo run --locked
# Optimized build:
cargo run --locked --release

The window starts $SHELL, falling back to /bin/sh, and inherits the launch directory. The child receives TERM=xterm-256color and COLORTERM=truecolor. Run exit or close the window to end the session. To select another shell:

SHELL=/bin/bash cargo run --locked

For diagnostics, use RUST_LOG=debug cargo run --locked. If no window appears, check that the process has access to your Wayland session and that Vulkan works on that desktop. To inspect the renderer's CPU work without enabling logs from all dependencies:

RUST_LOG=terminal::timing=debug cargo run --locked

Each frame logs prepare_us and paint_us, the time in microseconds spent in our preparation and painting callbacks. These exclude GPU execution, compositor scheduling, and presentation; they are not measurements of total input latency.

Controls and behavior

Input Action
Drag with the left mouse button Select text
Double-click / triple-click Select a word / line
Ctrl+Shift+C Copy the selection
Ctrl+Shift+V Paste, respecting bracketed-paste mode
Mouse wheel / touchpad Scroll terminal history
Shift+PageUp / Shift+PageDown Scroll one page
Shift+Home / Shift+End Jump to the oldest history / live screen

Typing returns to the live screen. Ctrl+C, Ctrl+D, Alt combinations, arrows, navigation keys, and function keys are sent to the terminal application. In alternate-screen applications, Shift+navigation is passed through and the wheel sends arrow keys when the application enables alternate scrolling.

The renderer supports ANSI and 256-color palettes, truecolor, bold/italic/dim, underlining, reverse video, selection, wide characters and combining marks. Window resizing updates both the terminal grid and PTY size. Alternate-screen applications use Alacritty's terminal modes. Scrollback retains up to 10,000 lines by default. The view selects an installed font in this order: Hermit (including its Hurmit Nerd Font variants), SF Mono, Noto Sans Mono, Iosevka, then another fixed-pitch family. Font advances are checked to avoid choosing a proportional fallback. Text is 15 logical pixels, with a 20-pixel line height and 8-pixel padding.

Structure

Module Responsibility
src/main.rs Application startup and window lifecycle
src/session.rs One shell, PTY event loop, terminal grid, resize, and shutdown
src/terminal.rs One terminal view: focus, selection, scrollback, clipboard, text input, and render coordination
src/render.rs Cached terminal text layout and batched drawing
src/input.rs Xterm-style key encoding and paste framing
src/colors.rs Default palette, runtime color overrides, and cell color attributes
src/fonts.rs Preferred installed fonts and verified fixed-pitch fallback

The session does not depend on GPUI or window layout. Future tabs or split panes can compose multiple views and sessions while reusing the parser and PTY code. Persistent multiplexing would add a session owner outside the window lifecycle.

PTY events wake the UI through an asynchronous channel. Output notifications are coalesced, and the UI yields between event batches so a busy child cannot monopolize the UI task. There is no periodic redraw polling. Typing requests a new frame when shell output arrives, or immediately if it changes selection, scrollback position, or input-method composition.

The renderer retains shaped text for unchanged rows. It groups adjacent ASCII cells into text runs, while keeping wide and combining-character cells aligned to terminal columns. Blank margins are skipped, and matching backgrounds and text decorations are merged into spans to reduce drawing work.

The build uses published crates and does not require a local Alacritty checkout. vendor/xattr carries a small compatibility patch for GPUI's transitive zed-async-tar dependency: Linux now uses libc::ENODATA in place of a removed ENOATTR alias. See the patch notes. The dependency versions are recorded in Cargo.lock.

Development and scope

The development profile retains debug information and assertions, with level-1 optimization and level-2 optimization for GPUI and the font-shaping crates. This keeps cargo run responsive during window resizing; the first build takes longer than a fully unoptimized build. Unicode clusters use cached glyphs in one shared paint layer, preserving cell positions without per-character layers.

cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

Tests cover key and paste encoding, palette behavior, terminal parsing and resizing, and PTY lifecycle. They do not replace testing rendering and input under a real compositor.

This first version has a single shell and window. It does not yet provide panes, tabs, session persistence, configuration files, application mouse reporting, the Kitty keyboard protocol, OSC 52 clipboard access, or clickable hyperlinks. macOS is an intended next target and has not been validated. Font shaping, input methods, and terminal application compatibility still need broader desktop testing.