Build server-backed psyTerm with multiplexing and themed UI

Move terminal sessions, tabs, panes, and state into a persistent headless
server with local socket and SSH clients. Launch GUIs through a managed
single-threaded zygote while keeping rendering responsive.

Add animated cursors, themed chrome, teal pane focus outlines, uniform
tabs, and middle-truncated names. Support program/CWD titles, manual
renaming, home-directory abbreviation, and automatic pane/tab removal
when shells exit.

Document the process architecture, controls, and third-party cursor
sources. Validated with 57 tests, strict Clippy, and live Wayland checks.
This commit is contained in:
2026-11-17 01:08:35 -08:00
parent de1d5776b6
commit d7e9be973c
18 changed files with 5257 additions and 410 deletions
+174 -88
View File
@@ -1,16 +1,17 @@
# Terminal
# psyTerm
A small GPU-rendered terminal built with [GPUI 0.2.2](https://gpui.rs/) and
[alacritty_terminal 0.26.0](https://docs.rs/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.
A Wayland terminal and multiplexer built with [GPUI 0.2.2](https://gpui.rs/)
and [alacritty_terminal 0.26.0](https://docs.rs/alacritty_terminal/0.26.0/).
A separate server owns terminal emulation, shells, tabs, panes, and scrollback.
GUI processes display its snapshots and send input commands. Closing a window
detaches it; the shells keep running for the next local or remote connection.
## 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.
Use recent stable Rust (development uses 1.96) and Linux 5.3 or newer. GUI
processes require a running Wayland desktop and a working Vulkan driver.
The server and SSH bridge do not initialize GPUI, Wayland, or Vulkan, although
the shared executable still needs its dynamically linked libraries installed.
Representative Fedora dependencies:
@@ -30,120 +31,205 @@ sudo apt install build-essential cmake pkg-config \
fonts-dejavu-core
```
The package names follow the relevant portions of
[Zed's Linux dependency script](https://github.com/zed-industries/zed/blob/main/script/linux).
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.
These are the relevant portions of [Zed's Linux dependency script](https://github.com/zed-industries/zed/blob/main/script/linux).
GPUI 0.2.2 links the XKB X11 library even with only its Wayland backend enabled.
Use your GPU vendor's Vulkan driver where appropriate.
```sh
cargo run --locked
# Optimized build:
cargo run --locked --release
cargo build --locked --release
./target/release/psyterm
```
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:
The default command starts or reuses a local server, asks its zygote to fork a
GUI, and returns. Running it again opens another view of the same workspace.
The first attachment to an empty server creates a shell. Shells use the
server's `$SHELL` (falling back to `/bin/sh`), environment, and startup directory;
they receive `TERM=xterm-256color` and `COLORTERM=truecolor`.
The server retains its startup environment. Set shell or GUI environment
preferences before starting that server, or use `--gui` to launch a diagnostic
GUI directly from the current environment. After rebuilding, the server refreshes
its zygote for new GUI windows, preserving existing windows and shells. Changes
to server logic or the protocol still require restarting the server;
`--shutdown` also ends its shell sessions.
This build uses protocol version 2. An older server must be restarted before
attaching; the new `psyterm --shutdown` command can stop a version-1 server.
Finish any running work first, since shutdown ends its sessions, then launch
`psyterm` again to start the updated server.
## Commands and connections
| Command | Behavior |
| --- | --- |
| `psyterm` | Open a local window through the server's zygote |
| `psyterm --remote user@host` | Open a local GUI connected to the remote server over SSH |
| `psyterm --gui` | Launch a GUI directly, bypassing the zygote |
| `psyterm --list` | Inspect tabs and panes in the running local server |
| `psyterm --shutdown` | Stop the local server and end its sessions |
| `psyterm --server` | Run the terminal server in the foreground |
| `psyterm --socket PATH` | Select a separate local server socket; combine with other options |
| `psyterm --bridge` | Proxy the binary protocol between stdin/stdout and a local server |
By default the socket is `$XDG_RUNTIME_DIR/psyterm/server.sock`, with a private
per-user temporary directory as fallback. A custom socket must have a real,
user-owned parent directory with mode `0700`:
```sh
SHELL=/bin/bash cargo run --locked
mkdir -m 700 "$XDG_RUNTIME_DIR/psyterm-dev"
cargo run --locked -- --socket "$XDG_RUNTIME_DIR/psyterm-dev/server.sock"
```
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:
Sockets and log files are private to the current UID; peers are checked with
Linux credentials. Server and zygote logs are beside the socket as
`server.sock.log` and `server.sock.zygote.log`.
SSH uses `BatchMode=yes`: configure key/agent authentication and known-host trust
before connecting. The remote host needs a compatible `psyterm` executable in
its noninteractive SSH `PATH`. Override that executable with
`PSYTERM_REMOTE_BIN`; this direct-launch example uses the current environment:
```sh
RUST_LOG=terminal::timing=debug cargo run --locked
PSYTERM_REMOTE_BIN=/home/me/bin/psyterm \
cargo run --locked -- --gui --remote me@workstation
```
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.
SSH starts `psyterm --bridge` on the remote host, which starts or reuses that
host's server. stdout carries only framed protocol bytes. No TCP listener or
separate network authentication service is exposed. To end remote sessions,
run `psyterm --shutdown` on the remote host, for example through SSH.
## Controls and behavior
## Controls
| 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 |
| Click a tab | Switch the server's active tab |
| `+` or Ctrl+Shift+T | Create a tab |
| Ctrl+Shift+D | Add a pane beside the focused pane |
| Ctrl+Shift+Left / Right | Focus the previous / next pane |
| Ctrl+Shift+W | Close the focused pane and its shell |
| Ctrl+Shift+R | Edit the pane name |
| Enter / Esc while renaming | Save / cancel the edit |
| Save a blank name | Restore automatic pane naming |
| Window `×` | Detach this GUI; keep server sessions running |
| Drag / double-click / triple-click | Select text / word / line |
| Ctrl+Shift+C / V | Copy selection / paste with negotiated 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 |
| Shift+PageUp / PageDown | Scroll one page |
| Shift+Home / End | Jump to 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.
navigation keys, and function keys reach the terminal application.
Alternate-screen applications receive shifted navigation; 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.
Each pane has a name above its terminal content. The server chooses a manual
name first, then the running program's OSC title, then the shell's current
directory. Automatic directory names abbreviate the server’s home directory
with `~`; pane headers and equal-width tabs truncate long names in the middle.
It checks shell directories every 500 ms, including while the shell is idle. Manual names survive program title changes and client disconnects;
returning to automatic naming uses the latest program title or directory.
## Structure
When a shell exits, its pane closes automatically. An empty tab closes too,
and focus moves to an adjacent remaining pane or tab when needed. After the
last shell exits, the window stays open with `+` available to start another tab.
| Module | Responsibility |
Clients share the server's active tab, focused pane, selection, and scrollback
position. The most recent GUI resize sets each pane's grid size. These are
shared views of one workspace, not independent per-client layouts. Tabs and
panes survive GUI disconnects but are stored in daemon memory, not persisted
across server shutdown or machine restart.
## Appearance
The inset terminal surface and titlebar use the dark Sybil palette shared by
Huayra, Attractor, and Sybil. Tabs retain violet accents; pane headers use teal,
with a matching border around the active pane. The titlebar contains equal-width
tabs and connection/window controls. `src/chrome.rs` records the theme sources.
Cursor motion adapts Neovide's four independently sprung corners: leading
corners move first and trailing corners stretch behind. The blink follows
buzzlocker: 500 ms solid after input, 500 ms cubic fade-out, then an immediate
return to solid. An inactive window or pane shows a stationary hollow cursor.
Neovide's MIT license and both sources are recorded in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
Font preference is Hermit (including Hurmit Nerd Font variants), SF Mono,
Noto Sans Mono, Iosevka, then another verified fixed-pitch family. Text uses
15 logical pixels and a 20-pixel line height. Rendering supports ANSI/256
colors, truecolor, bold/italic/dim, underline, reverse video, wide characters,
and combining marks. Alacritty supplies terminal modes and 10,000 lines of
scrollback by default.
## Processes and source
| Component | 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 |
| `server.rs`, `session.rs` | Authoritative workspace, PTYs, child processes, parser, terminal grids, selection, scrolling, and resize |
| `protocol.rs`, `client.rs` | Versioned bounded messages, local socket / SSH transport, snapshot delivery |
| `launcher.rs` | Server startup, private paths, lifecycle locks, and the server-owned GUI zygote |
| `terminal.rs` | Snapshot-only GUI workspace and panes, input, focus, and animation scheduling |
| `pane_name.rs`, `label.rs` | Pane name editor, Unicode composition, and middle-truncated labels |
| `render.rs`, `cursor.rs` | Cached text and batched drawing; cursor motion and blink |
| `chrome.rs`, `colors.rs`, `fonts.rs` | Window chrome, terminal colors, font selection |
| `input.rs`, `main.rs` | Key/paste encoding and CLI/process-role dispatch |
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.
The server starts the zygote on demand and manages its lifetime. The zygote
checks that it is single-threaded and forks GUI children **before** GPUI,
Wayland, Vulkan, font discovery, or executors initialize. Children inherit the
loaded executable mappings and avoid another `exec`; graphics and font setup
still happen in each child. This is a safe prefork foundation, not a guarantee
of the fastest possible launch time. Headless terminal/bridge use does not
start the zygote.
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.
Snapshot queues retain the newest frame for a slow client rather than an
unbounded backlog. GUI rows keep their shaped text until the snapshot changes.
ASCII runs, Unicode glyphs, backgrounds, and decorations are batched; cursor
animation reuses prepared terminal rows. Blink holds use timed wakeups, and
inactive cursors schedule no animation frames.
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 project uses published crates, with no local Alacritty checkout required.
The small [vendored xattr patch](vendor/xattr/PATCH.md) fixes GPUI's transitive
Linux `ENOATTR` compatibility issue. `Cargo.lock` records dependency versions.
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](vendor/xattr/PATCH.md). The dependency
versions are recorded in `Cargo.lock`.
## Development
## 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.
The development profile retains debug information and assertions with level-1
optimization, plus level-2 optimization for GPUI and shaping crates. Preserve
these settings when evaluating responsiveness; full-grid shaping and scene
construction are expensive in a completely unoptimized build.
```sh
cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
RUST_LOG=psyterm::timing=debug cargo run --locked -- --gui
```
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.
`prepare_us` and `paint_us` measure CPU callback time in microseconds. They
exclude GPU execution, compositor scheduling, and presentation, so they are
not end-to-end input-latency measurements.
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.
Tests cover protocol framing, socket ownership, binary bridge flushing,
key/paste encoding, palettes, fonts, cursor curves, rendering assembly, PTY
lifecycle, and server reattachment/layout behavior. Pane tests cover natural
shell exit, empty-tab removal, focus preservation, idle directory changes,
program/manual name precedence, title resets, and rename persistence. Editor
tests cover Unicode selection and composition; protocol tests pin the previous
version's shutdown handshake.
Live Hyprland checks verified GUI→zygote→server ancestry, a single-threaded
zygote, no server GPU descriptors, two simultaneous GUIs, tabs/splits, and shell
survival after detaching. An actual SSH connection to a separate headless
server on localhost verified input and reattachment. Replacing a running
executable refreshed its zygote while the original GUI and shell stayed alive.
These are Linux checks; remote-network latency and macOS remain unverified.
Linux Wayland is the implemented platform; macOS is a future target. Current
limits include side-by-side panes only, shared per-server viewport state, no
disk-restored sessions, no configuration files, no application mouse reporting,
no Kitty keyboard protocol, no OSC 52 clipboard access, and no clickable links.