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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user