Architecture

Architecture

Runtime Model

The application is currently a single native process that owns its PTYs:

FreeVision application
  windows
    panes
      PTY process
      virtual screen

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.

Main Units

Unit	Responsibility
src/superterm.lpr	Program entry point
src/st_fvui.pas	FreeVision application, menus, windows, panes, events
src/st_pty.pas	PTY creation, process execution, input/output, resize
src/st_screen.pas	Virtual screen, UTF-8, ANSI/VT parsing, scrollback
src/st_layout.pas	Recursive vertical/horizontal split tree and geometry
src/st_config.pas	User settings, terminal definitions, SSH commands
src/st_templates.pas	Named templates, INI and SQLite loading/saving
src/st_session.pas	Legacy session save/restore
src/st_keys.pas	Key events translated to terminal sequences
src/st_debug.pas	Optional runtime diagnostics

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. Configuration selects a local command or SSH terminal definition.
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.
4. FreeVision renders the screen and routes keyboard/mouse events.
5. Resize events update the layout, virtual screen, and child PTY dimensions.
6. Session and template layers persist the selected layout 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.

Current Boundary

The current process owns all live PTYs. Switching templates recreates the target runtime, and exiting terminates its children. There is no detached server, Unix socket, or live client attach operation yet.

A future persistent model would separate the server-owned state from clients:

server
  sessions
    windows
      panes -> PTY + screen
  clients -> attached session