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

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.

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.