299 lines
16 KiB
Markdown
299 lines
16 KiB
Markdown
# psyTerm
|
||
|
||
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 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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
|
||
```
|
||
|
||
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
|
||
|
||
cargo build --locked --release
|
||
./target/release/psyterm
|
||
```
|
||
|
||
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 4. An older server must be restarted before
|
||
attaching; `psyterm --shutdown` can stop servers using versions 1–3.
|
||
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
|
||
mkdir -m 700 "$XDG_RUNTIME_DIR/psyterm-dev"
|
||
cargo run --locked -- --socket "$XDG_RUNTIME_DIR/psyterm-dev/server.sock"
|
||
```
|
||
|
||
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
|
||
PSYTERM_REMOTE_BIN=/home/me/bin/psyterm \
|
||
cargo run --locked -- --gui --remote me@workstation
|
||
```
|
||
|
||
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
|
||
|
||
| Input | Action |
|
||
| --- | --- |
|
||
| Ctrl/Cmd+Shift+P | Open the command palette |
|
||
| Click a tab | Switch the server's active tab |
|
||
| `+` or Ctrl+Shift+T | Create a tab |
|
||
| Ctrl+Shift+D or Alt+\ | Add a pane beside the focused pane |
|
||
| Alt+Left / Right | Focus the adjacent pane, then adjacent tab at the edge |
|
||
| Alt+Shift+[ / ] | Switch to the previous / next tab |
|
||
| Alt+Shift+N or Alt+Shift+Right | Create a tab |
|
||
| Alt+Shift+Up / Down | Insert a stacked pane above / below the current pane |
|
||
| Alt+Up / Down | Expand the previous / next stacked pane |
|
||
| Click a collapsed pane title | Expand and focus that 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 |
|
||
| Palette → Rename tab | Edit the selected tab's name |
|
||
| Enter / Esc while renaming | Save / cancel the edit |
|
||
| Save a blank name | Restore automatic pane/tab 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 / PageDown | Scroll one page |
|
||
| Shift+Home / End | Jump to oldest history / live screen |
|
||
|
||
Navigation follows the `shared` bindings in `~/.config/zellij/config.kdl`, with
|
||
Alt+\ from its default `locked` mode. Existing psyTerm shortcuts remain available;
|
||
Zellij's modal Ctrl bindings are left to terminal programs.
|
||
|
||
The command palette searches command names and keywords as you type. Arrow keys
|
||
or Tab select a result; Enter runs it or opens a submenu. Escape returns to the
|
||
parent menu, then closes the palette. “Switch to tab…” and “Focus pane…” offer
|
||
live workspace lists, including collapsed panes. Commands without shortcuts,
|
||
such as restoring automatic pane names, are available here too. Palette input
|
||
never reaches the shell.
|
||
|
||
Typing returns to the live screen. Ctrl+C, Ctrl+D and unbound Alt combinations,
|
||
arrows, 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.
|
||
|
||
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.
|
||
|
||
Tabs use a manual name when set; otherwise they inherit the selected pane's
|
||
effective name. Use **Rename tab** in the command palette to edit the tab label
|
||
inline. Enter saves; Escape or clicking elsewhere cancels. Saving an empty name
|
||
or choosing **Use automatic tab name** restores inheritance immediately. Tab
|
||
names are server-owned and survive pane switches, shell exits within the tab,
|
||
and client reconnects.
|
||
|
||
Tabs form the horizontal dimension; each column within a tab has an ordered
|
||
vertical stack. One pane per stack is expanded, with the other titles above and
|
||
below it. Creating or switching stacked panes uses the same curve as tab changes,
|
||
with vertical motion. Vertical navigation stops at the first/last pane. Side-by-side
|
||
splits create independent columns, each with its own stack. Long collapsed-title
|
||
lists scroll, leaving room for the expanded terminal.
|
||
|
||
Stack order, expanded panes, titles, and all shells live on the server and survive
|
||
GUI detach/reattach. Collapsed shells keep running; their grids are sent only when
|
||
expanded, and their output does not redraw unchanged visible grids.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Tab changes and new panes slide with Neovide's 150 ms exponential window-motion
|
||
curve. Outgoing content remains visible during the transition; only the incoming
|
||
view accepts input and controls the terminal size.
|
||
|
||
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 |
|
||
| --- | --- |
|
||
| `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, command dispatch, focus, and animation scheduling |
|
||
| `commands.rs`, `bindings.rs`, `palette.rs` | Extensible command metadata, optional shortcuts, searchable nested menus |
|
||
| `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 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.
|
||
|
||
Add an action and registry entry in `commands.rs`, then handle it in the workspace
|
||
dispatcher to add a command. Shortcut hints are optional. The same recursive menu
|
||
model supports commands that lead to further choices.
|
||
|
||
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.
|
||
|
||
Dependencies are pinned to published releases, with no local Alacritty checkout
|
||
required. The [vendored GPUI patch](vendor/gpui/PATCH.md) restarts Wayland painting
|
||
when asynchronous output invalidates an idle window; active frames remain paced
|
||
by the compositor. The [xattr patch](vendor/xattr/PATCH.md) fixes GPUI's transitive
|
||
Linux `ENOATTR` compatibility issue. `Cargo.lock` records dependency versions.
|
||
|
||
## Development
|
||
|
||
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
|
||
|
||
# Optional regression check with Weston installed (headless backend, fake seat):
|
||
cargo build --locked
|
||
python3 scripts/check-wayland-idle.py
|
||
```
|
||
|
||
`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.
|
||
|
||
The Wayland regression check creates a private compositor and server. With the
|
||
cursor hidden, it verifies a quiet window does not keep repainting, then sends
|
||
terminal output and checks that painting resumes without a screenshot, resize,
|
||
or desktop input to wake the compositor. It fails on unpatched GPUI 0.2.2.
|
||
|
||
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. Tab-name
|
||
tests cover manual precedence, selected-pane inheritance, resets, and reconnects. Editor
|
||
tests cover Unicode selection and composition; protocol tests pin the previous
|
||
versions’ shutdown handshakes. Stack tests cover insertion, navigation, hidden
|
||
output, reattachment, exit cleanup, and command bursts without intervening snapshots.
|
||
|
||
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.
|
||
New live checks cover palette search/submenus and input isolation, Zellij
|
||
navigation bindings, stack insertion in both directions, collapsed-pane focus,
|
||
exit cleanup, and stack reattachment. A second client's focus changes preserve
|
||
palette input. 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 no arbitrary split trees or floating panes, 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.
|