terminalX/vendor/libghostty-spm/README.md

GhosttyKit

Swift Package wrapping Ghostty's terminal emulator library for Apple platforms.

Pre-built libghostty static library distributed as an XCFramework binary target.

Platforms

• macOS 13+
• iOS 15+
• Mac Catalyst 15+

Products

Library	Description
GhosttyKit	Re-exports the libghostty C API (ghostty.h)
GhosttyTerminal	Swift wrapper — native views, SwiftUI integration, input handling, display link
GhosttyTheme	485 terminal color themes from iTerm2-Color-Schemes (MIT License)
ShellCraftKit	Sandboxed shell emulation framework (depends on GhosttyTerminal)

Installation

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/Lakr233/libghostty-spm.git", from: "1.2.0"),
]

Then add the product you need:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "GhosttyTerminal", package: "libghostty-spm"),
    ]
)

Usage

The example apps are the best starting point for real integration:

• Example/GhosttyTerminalApp/ — macOS AppKit demo with delegate callbacks
• Example/MobileGhosttyApp/ — iOS UIKit demo with keyboard, safe area, themes, and text selection

SwiftUI (iOS 15+ / macOS 13+ / Mac Catalyst 15+)

import SwiftUI
import GhosttyTerminal

struct ContentView: View {
    @StateObject private var terminal = TerminalViewState()
    private let session = InMemoryTerminalSession(
        write: { data in
            // Handle bytes produced by the terminal.
        },
        resize: { viewport in
            // Keep your host backend in sync with the terminal grid.
        }
    )

    var body: some View {
        TerminalSurfaceView(context: terminal)
            .navigationTitle(terminal.title)
            .onAppear {
                terminal.configuration = TerminalSurfaceOptions(
                    backend: .inMemory(session)
                )
            }
    }
}

UIKit / AppKit

import GhosttyTerminal

let terminalView = TerminalView(frame: .zero)
terminalView.delegate = self
terminalView.controller = TerminalController(configFilePath: path)
terminalView.configuration = TerminalSurfaceOptions(
    backend: .inMemory(session)
)

TerminalView is a type alias that resolves to UITerminalView (iOS/Catalyst) or AppTerminalView (macOS).

Prompt and scrollback navigation

TerminalViewState, TerminalView, and TerminalSurface expose the same programmatic navigation APIs:

terminal.jumpToPrompt(by: -1) // Previous prompt.
terminal.jumpToPrompt(by: 1)  // Next prompt.
terminal.scrollToRow(0)        // First absolute scrollback row.

Prompt navigation requires Ghostty shell integration, which records prompt boundaries. A host-managed backend must preserve or emit equivalent OSC 133 prompt markers. Arbitrary Ghostty actions remain available through performBindingAction(_:).

Notes

• TerminalViewState is the SwiftUI state container.
• TerminalView is the UIKit/AppKit view typealias.
• TerminalController owns app lifecycle, config resolution, themes, and surface creation.
• InMemoryTerminalSession provides the host-managed backend used by the sandboxed example apps.
• GhosttyThemeCatalog exposes bundled iTerm2 color schemes.

Building from Source

The package includes a pre-built XCFramework. To rebuild libghostty from the Ghostty source:

# Requires: zig compiler
./Script/build.sh

This applies patches from Patches/ghostty/, builds for all target architectures, and assembles the XCFramework.

Release Versioning

Bare semantic-version tags such as 1.3.1 are GhosttyKit Swift package versions. They are independent from Ghostty's upstream tags. The matching storage.1.3.1 release stores the XCFramework consumed by that package tag.

Release builds use the immutable upstream Ghostty commit recorded in Ghostty.ref. Updating Ghostty requires a reviewed change to that file, so a package release cannot silently switch to a different upstream tag or commit. Manual releases require an explicit package version; scheduled releases only increment the package patch version when main is newer than the latest package tag.

Trimmed Build

The bundled libghostty is a trimmed build optimized for sandboxed, embedded use on Apple platforms.

Component	Upstream Ghostty	libghostty-spm	Reason
Terminal emulation core	Yes	Yes	Full VT parser, state machine, grid — retained
Metal renderer	Yes	Yes	GPU rendering via CAMetalLayer / IOSurface — retained
Font rasterization & shaping	Yes	Yes	CoreText font backend — retained
Configuration system	Yes	Yes	All terminal config options — retained
Input handling (key, mouse, IME)	Yes	Yes	Full keyboard/mouse/touch/IME pipeline — retained
Text selection & clipboard	Yes	Yes	Selection, copy/paste APIs — retained
Custom shaders (GLSL)	Yes	No	glslang and spirv-cross removed (-Dcustom-shaders=false). Shadertoy/post-processing shaders are a desktop feature unnecessary for embedded use.
Terminal inspector (ImGui)	Yes	No	dcimgui removed (-Dinspector=false). Debug inspector UI replaced with no-op stubs.
Sentry crash reporting	Yes	No	Disabled (-Dsentry=false).
Native app runtime	Yes	No	Cocoa/GTK/Wayland app shell disabled (-Dapp-runtime=none). The host app provides its own runtime.
Standalone executable	Yes	No	No terminal .app or CLI binary emitted (-Demit-exe=false).
Documentation generation	Yes	No	Skipped (-Demit-docs=false).
Frame data generator	Build-time tool	Pre-compiled	framedata.compressed shipped pre-built; framegen C tool dependency removed.
Host-managed I/O backend	No	Added	New GHOSTTY_SURFACE_IO_BACKEND_HOST_MANAGED for non-PTY, sandbox-safe terminal I/O.
iOS Metal rendering fixes	No	Added	IOSurface +1px tolerance, synchronous present, 64-byte row alignment for iOS.
iOS platform fixes	No	Added	Deployment target lowered, private API removed, kqueue fix for simulator.

License

MIT License. See LICENSE for details.

The bundled libghostty binary is built from Ghostty, which has its own license terms.

Sponsor

• LookInside helps you inspect a running iOS or macOS app UI from your Mac.
• This project/repository is sponsored by AFK AI, INC.