Architecture

Architecture

Runtime Model

A FreeVision client renders the workspace, while live PTYs can be owned either by the client process or, once detached, by a per-user session server:

FreeVision application (client)
  windows
    panes
      PTY process
      virtual screen

session server (per detached session)
  panes -> PTY + terminal parser + scrollback
  clients -> attached session

Every visible pane has a process-backed PTY and a TScreen instance. The UI polls PTYs, feeds output into the terminal parser, renders virtual screens, and sends keyboard or mouse input back to the focused PTY. A detach hands the PTY masters, process groups, parsers, and scrollback to a background server, so leaving the client does not close local shells or remote SSH connections.

Main Units

Unit	Responsibility
src/superterm.lpr	Program entry point and CLI (--attach, --list-sessions)
src/st_fvui.pas	FreeVision application, menus, panes, focus, and polling
src/st_dialogs.pas	Class/profile managers, session picker, pane list
src/st_layout.pas	Binary V/H split tree and pane rectangles
src/st_pty.pas	POSIX PTYs, fork/exec, I/O, resize, and process cleanup
src/st_screen.pas	VT100/ANSI parser and virtual screen for each pane
src/st_server.pas	Detached session daemon, protocol, and enumeration
src/st_session.pas	Session serialization and restore
src/st_wclass.pas	Window classes ([class.*], legacy [t-*] reader)
src/st_profiles.pas	Profiles ([profile.*], legacy template flattening)
src/st_config.pas	User settings, prefix key, palette, and paths
src/st_templates.pas	Legacy INI and SQLite template loading
src/st_kbd.pas	Custom keyboard driver (ESC timeout, CSI/SS3, mouse)
src/st_video.pas	Wide video output, CP437 glyph mapping, cursor restore
src/st_keys.pas	FreeVision key codes to terminal escape sequences
src/st_debug.pas	Optional runtime logging

Platform Layer

superterm builds and runs natively on GNU/Linux and macOS (Apple Silicon and Intel) from the same source tree. Both are POSIX systems, so the UI, VT engine, layout, configuration, and detach/attach server are shared without change. The only platform-conditional unit is the PTY/process layer (src/st_pty.pas), selected at compile time with {$IFDEF DARWIN}:

• GNU/Linux allocates the PTY with posix_openpt/grantpt/unlockpt/ptsname and reads process titles and cwd from /proc.
• macOS allocates it with BSD openpty + login_tty and reads process titles and cwd with libproc/sysctl. Free Pascal auto-defines DARWIN on a macOS host, so no special build flag is required.

FreeVision Overlay

vendor/fv322/ contains the project-local FreeVision units. The build places them before system FreeVision units so the application receives the local wide-screen and tmux mouse fixes without modifying the installed FPC packages.

Generated compiler output is kept in bin/ and build/; both directories are ignored by Git.

Process Flow

1. A window class or profile pane selects a local command or an SSH connection.
2. st_pty.pas creates a PTY, starts the child process, and applies its terminal size.
3. Output is read from the PTY and parsed into the pane's virtual screen; 256-color/truecolor sequences are approximated to ANSI-16 and modern-CLI glyphs are mapped to CP437.
4. FreeVision renders the screen; st_kbd.pas decodes keyboard and mouse input and routes it to the focused PTY.
5. Resize events update the layout, virtual screen, and child PTY dimensions.
6. The session, profile, and class layers persist the selected layout, titles, and definitions.

Layout Identity

Layouts are recursive trees. A leaf represents a pane, while V and H nodes represent vertical and horizontal splits with a ratio. The current runtime supports up to 16 panes and keeps layout leaves aligned with PTY-backed pane state.

Client/Server Sessions (3.0)

Since 3.0 the session server is not an afterthought of detaching: the launcher builds the workspace, forks the server, hands it the PTYs and attaches to it as the first client. The server owns the PTY masters, the VT parsers and the scrollback; clients own only windows and input.

• Control requests (list, send, capture, window operations) travel over ephemeral socket connections that answer and close without taking an interactive slot, so the CLI works while clients are attached.
• Up to 8 clients share one session. Output and pane exits are broadcast; layout, title, focus, new-pane and kill-pane changes are re-broadcast as server events; each pane is sized to the smallest client request.
• Writes to clients are buffered and never block the server: output is paused by flow control while a client catches up, and a client that makes no progress for a grace period is dropped.
• The wire protocol is append-only with tolerant tails: a pre-3.0 client attaches exclusively and is never sent frames it cannot parse, and a pre-3.0 server simply ignores the new frames.

Session Boundary

Activating a profile recreates the target runtime, terminating the client's own children. Detaching (Ctrl-Q d) instead hands the panes to the session server, which keeps their processes alive; attaching a session (--attach, the startup picker, or Ctrl-Q s) reconnects a client to that server. Window geometry (moved, zoomed, minimized) round-trips exactly through both exit/restore and detach/attach.