Architecture

How the package wraps Ghostty, owns terminal state, bridges native input, and keeps sandboxed apps in control of I/O.

Layers

libghostty      Zig/C       Static library inside GhosttyKit.xcframework.
   |
GhosttyKit      Swift      Re-export of ghostty.h for direct C API access.
   |
GhosttyTerminal Swift      Controller, configuration, native views, input, surface lifecycle.
   |
GhosttyTheme    Swift      Theme catalog and TerminalConfiguration conversion helpers.
   |
ShellCraftKit   Swift      Sandboxed command engine backed by InMemoryTerminalSession.

Controller and surface

TerminalController is the source of truth for Ghostty app lifecycle and resolved configuration. It composes the base config source, per-session TerminalConfiguration, active TerminalTheme, and current color scheme into one rendered Ghostty config.

A platform view asks the controller to create a TerminalSurface. The surface owns the bridge to Ghostty’s renderer, callback table, display link, and host-managed I/O hooks.

Platform views

Platform	Type	Input model
iOS / Catalyst	`UITerminalView`	`UITextInput`, hardware presses, touch scrolling, input accessory bar.
macOS	`AppTerminalView`	`NSTextInputClient`, key events, mouse and scroll events.
SwiftUI	`TerminalSurfaceView`	Wraps the platform view and syncs SwiftUI color scheme.

Host-managed I/O

Example apps use GHOSTTY_SURFACE_IO_BACKEND_HOST_MANAGED. Ghostty produces user input bytes through callbacks, and the host feeds output bytes back through ghostty_surface_write_buffer. InMemoryTerminalSession owns this bridge for Swift callers.

iOS input chain

Hardware keys arrive through pressesBegan and are translated into ghostty_input_key_s.
Software keyboard text arrives through insertText(_:) and deletion through deleteBackward().
Marked text flows through TerminalTextInputHandler and calls Ghostty preedit APIs.
The accessory bar dispatches terminal keys and sticky Ctrl/Alt/Cmd modifiers.
Long-press selection requests are delegated to the host with a viewport snapshot.

Trimmed build

Component	Bundled state	Reason
Terminal core	Included	VT parser, state machine, grid.
Metal renderer	Included	CAMetalLayer / IOSurface rendering.
CoreText font backend	Included	Apple text shaping and rasterization.
Custom shaders	Disabled	Embedded apps get a smaller dependency graph.
Inspector UI	Disabled	Host apps own diagnostics UI.
Native app runtime	Disabled	UIKit/AppKit/SwiftUI hosts provide the runtime.
Host-managed I/O backend	Added	Sandbox-friendly terminal transport.
iOS platform fixes	Added	Metal row alignment, simulator fixes, deployment-target adjustments.

Architecture rules

TerminalController owns the Ghostty app object and config resolution.
Platform views own native input and layer sizing.
TerminalSurface owns Ghostty surface lifetime and display-link ticks.
Host apps own process execution and byte transport for sandboxed demos.
Catalyst follows the UIKit branch in platform conditionals.