# migueldeicaza/swiftterm architecture

> Architecture diagram of the GitHub repository migueldeicaza/swiftterm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/migueldeicaza/swiftterm
- Repository: https://github.com/migueldeicaza/swiftterm

## Overview

SwiftTerm is a reusable Swift VT/xterm terminal-emulation library, with headless, Apple, and WebAssembly hosting options. The main workflow is a host feeding terminal bytes to the engine; the parser updates screen and scrollback state, which a host renderer presents. Terminal-generated replies and user input travel back through the host interface. Separate capabilities include selection/search, Unicode and bidirectional text, graphics, local process I/O, and session playback. The README documents these product branches; sampled excerpts are limited, so uncertain internal wiring is omitted.

Main entry points: [`Sources/SwiftTerm/Terminal.swift`](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Terminal.swift) (Terminal core), [`Sources/SwiftTerm/Apple/AppleTerminalView.swift`](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/AppleTerminalView.swift) (Apple terminal views), [`Sources/SwiftTerm/LocalProcess.swift`](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/LocalProcess.swift) (Local process), [`Sources/SwiftTermWebWasm/WasmTerminalHost.swift`](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/WasmTerminalHost.swift) (WASM terminal host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Terminal engine"]
  node_terminal["Terminal core<br/>[Terminal.swift]"]
  node_parser["Escape parser"]
  node_buffer[("Screen buffers<br/>[BufferSet.swift]")]
  node_cells["Packed cells<br/>[CellStorage.swift]"]
  node_unicode["Unicode and BiDi<br/>[Bidi.swift]"]
  node_graphics["Terminal graphics"]
  node_selection["Selection service"]
  node_search["Search service"]
end

subgraph group_apple["Apple interfaces"]
  node_appleview["Apple terminal views"]
  node_renderer["Apple rendering"]
  node_metal["Metal renderer"]
  node_macview["macOS view"]
  node_iosview["iOS view"]
end

subgraph group_hosting["Hosts and sessions"]
  node_headless["Headless terminal"]
  node_process["Local process<br/>[LocalProcess.swift]"]
  node_pty["PTY transport<br/>[Pty.swift]"]
  node_termcast["Termcast record/playback"]
end

subgraph group_wasm["WebAssembly"]
  node_wasmhost["WASM terminal host"]
  node_exports["WASM ABI exports<br/>[Exports.swift]"]
  node_snapshot["Render snapshots"]
  node_webclient["TypeScript client<br/>[terminal.ts]"]
end

node_host(("Terminal host"))
node_browser(("Browser host"))

node_host -->|"feeds bytes"| node_terminal
node_terminal -->|"parses input"| node_parser
node_parser -->|"updates screen"| node_buffer
node_buffer -->|"stores cells"| node_cells
node_terminal -->|"sends replies"| node_host
node_terminal -->|"provides terminal state"| node_appleview
node_appleview -->|"requests rendering"| node_renderer
node_renderer -.->|"uses optionally"| node_metal
node_appleview -->|"supports selection"| node_selection
node_appleview -->|"supports search"| node_search
node_macview -->|"specializes view"| node_appleview
node_iosview -->|"specializes view"| node_appleview
node_headless -->|"hosts engine"| node_terminal
node_process -->|"uses PTY"| node_pty
node_process -->|"delivers process output"| node_terminal
node_terminal -->|"forwards input"| node_process
node_termcast -->|"records session"| node_process
node_wasmhost -->|"hosts engine"| node_terminal
node_exports -->|"dispatches calls"| node_wasmhost
node_wasmhost -->|"encodes snapshots"| node_snapshot
node_webclient -->|"calls ABI"| node_exports
node_browser -->|"loads client"| node_webclient
node_unicode -->|"supports text handling"| node_terminal
node_graphics -->|"handles graphics protocols"| node_terminal

click node_terminal "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Terminal.swift"
click node_parser "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/EscapeSequenceParser.swift"
click node_buffer "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/BufferSet.swift"
click node_cells "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/CellStorage.swift"
click node_unicode "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Bidi.swift"
click node_graphics "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/KittyGraphics.swift"
click node_selection "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/SelectionService.swift"
click node_search "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/SearchService.swift"
click node_appleview "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/AppleTerminalView.swift"
click node_renderer "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/TerminalRenderOwner.swift"
click node_metal "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/Metal/MetalTerminalRenderer.swift"
click node_macview "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Mac/MacTerminalView.swift"
click node_iosview "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/iOS/iOSTerminalView.swift"
click node_headless "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/HeadlessTerminal.swift"
click node_process "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/LocalProcess.swift"
click node_pty "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Pty.swift"
click node_termcast "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/Termcast/TermcastRecorder.swift"
click node_wasmhost "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/WasmTerminalHost.swift"
click node_exports "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/Exports.swift"
click node_snapshot "https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/SnapshotEncoder.swift"
click node_webclient "https://github.com/migueldeicaza/swiftterm/blob/main/Web/src/terminal.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_terminal,node_parser,node_buffer,node_cells,node_unicode,node_graphics,node_selection,node_search,node_browser toneBlue
class node_appleview,node_renderer,node_metal,node_macview,node_iosview toneAmber
class node_headless,node_process,node_pty,node_termcast toneMint
class node_wasmhost,node_exports,node_snapshot,node_webclient toneRose
class node_host toneIndigo
```

## Components

### Terminal engine

- [Terminal core](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Terminal.swift): `Sources/SwiftTerm/Terminal.swift`
- [Escape parser](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/EscapeSequenceParser.swift): `Sources/SwiftTerm/EscapeSequenceParser.swift`
- [Screen buffers](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/BufferSet.swift): `Sources/SwiftTerm/BufferSet.swift`
- [Packed cells](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/CellStorage.swift): `Sources/SwiftTerm/CellStorage.swift`
- [Unicode and BiDi](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Bidi.swift): `Sources/SwiftTerm/Bidi.swift`
- [Terminal graphics](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/KittyGraphics.swift): `Sources/SwiftTerm/KittyGraphics.swift`
- [Selection service](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/SelectionService.swift): `Sources/SwiftTerm/SelectionService.swift`
- [Search service](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/SearchService.swift): `Sources/SwiftTerm/SearchService.swift`

### Apple interfaces

- [Apple terminal views](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/AppleTerminalView.swift): `Sources/SwiftTerm/Apple/AppleTerminalView.swift`
- [Apple rendering](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/TerminalRenderOwner.swift): `Sources/SwiftTerm/Apple/TerminalRenderOwner.swift`
- [Metal renderer](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Apple/Metal/MetalTerminalRenderer.swift): `Sources/SwiftTerm/Apple/Metal/MetalTerminalRenderer.swift`
- [macOS view](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Mac/MacTerminalView.swift): `Sources/SwiftTerm/Mac/MacTerminalView.swift`
- [iOS view](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/iOS/iOSTerminalView.swift): `Sources/SwiftTerm/iOS/iOSTerminalView.swift`

### Hosts and sessions

- [Headless terminal](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/HeadlessTerminal.swift): `Sources/SwiftTerm/HeadlessTerminal.swift`
- [Local process](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/LocalProcess.swift): `Sources/SwiftTerm/LocalProcess.swift`
- [PTY transport](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTerm/Pty.swift): `Sources/SwiftTerm/Pty.swift`
- [Termcast record/playback](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/Termcast/TermcastRecorder.swift): `Sources/Termcast/TermcastRecorder.swift`

### WebAssembly

- [WASM terminal host](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/WasmTerminalHost.swift): `Sources/SwiftTermWebWasm/WasmTerminalHost.swift`
- [WASM ABI exports](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/Exports.swift): `Sources/SwiftTermWebWasm/Exports.swift`
- [Render snapshots](https://github.com/migueldeicaza/swiftterm/blob/main/Sources/SwiftTermWebWasm/SnapshotEncoder.swift): `Sources/SwiftTermWebWasm/SnapshotEncoder.swift`
- [TypeScript client](https://github.com/migueldeicaza/swiftterm/blob/main/Web/src/terminal.ts): `Web/src/terminal.ts`

### Other components

- **Terminal host**
- **Browser host**

## Connections

- Terminal host → Terminal core: feeds bytes
- Terminal core → Escape parser: parses input
- Escape parser → Screen buffers: updates screen
- Screen buffers → Packed cells: stores cells
- Terminal core → Terminal host: sends replies
- Terminal core → Apple terminal views: provides terminal state
- Apple terminal views → Apple rendering: requests rendering
- Apple rendering → Metal renderer: uses optionally
- Apple terminal views → Selection service: supports selection
- Apple terminal views → Search service: supports search
- macOS view → Apple terminal views: specializes view
- iOS view → Apple terminal views: specializes view
- Headless terminal → Terminal core: hosts engine
- Local process → PTY transport: uses PTY
- Local process → Terminal core: delivers process output
- Terminal core → Local process: forwards input
- Termcast record/playback → Local process: records session
- WASM terminal host → Terminal core: hosts engine
- WASM ABI exports → WASM terminal host: dispatches calls
- WASM terminal host → Render snapshots: encodes snapshots
- TypeScript client → WASM ABI exports: calls ABI
- Browser host → TypeScript client: loads client
- Unicode and BiDi → Terminal core: supports text handling
- Terminal graphics → Terminal core: handles graphics protocols