Configuration

TerminalSurfaceOptions

public struct TerminalSurfaceOptions: Sendable {
    public var backend: TerminalSessionBackend
    public var fontSize: Float?
    public var workingDirectory: String?
    /// Extra environment for the child process (exec backend).
    public var envVars: [String: String]
    /// Replaces the user's default shell as the child command (exec backend);
    /// nil leaves the app-level config's command in place.
    public var command: String?
    /// Keep the surface open after `command` exits; nil leaves the
    /// app-level config's value in place.
    public var waitAfterCommand: Bool?
    public var context: TerminalSurfaceContext
    /// Coalescing window for host-driven resizes; 0 (the default) resizes
    /// synchronously on every metrics change.
    public var resizeThrottleMilliseconds: Double

    public init(
        backend: TerminalSessionBackend = .exec,
        fontSize: Float? = nil,
        workingDirectory: String? = nil,
        envVars: [String: String] = [:],
        command: String? = nil,
        waitAfterCommand: Bool? = nil,
        context: TerminalSurfaceContext = .window,
        resizeThrottleMilliseconds: Double = 0
    )
}

public enum TerminalSessionBackend: Sendable {
    case exec
    case inMemory(InMemoryTerminalSession)
}

public enum TerminalSurfaceContext: Sendable, Equatable {
    case window
    case split
}

TerminalConfiguration

public struct TerminalConfiguration: Sendable, Hashable {
    public init()
    public init(configure: (inout Builder) -> Void)
    public init(
        startingFrom base: TerminalConfiguration,
        configure: (inout Builder) -> Void
    )

    public func appending(_ command: TerminalConfigCommand) -> TerminalConfiguration

    // Font
    public func fontFamily(_ value: String) -> TerminalConfiguration
    public func fontSize(_ value: Float) -> TerminalConfiguration
    public func fontThicken(_ enabled: Bool) -> TerminalConfiguration
    public func fontThickenStrength(_ value: Int) -> TerminalConfiguration

    // Cursor
    public func cursorStyle(_ style: TerminalCursorStyle) -> TerminalConfiguration
    public func cursorStyleBlink(_ enabled: Bool) -> TerminalConfiguration
    public func cursorColor(_ value: String) -> TerminalConfiguration
    public func cursorText(_ value: String) -> TerminalConfiguration
    public func cursorOpacity(_ value: Double) -> TerminalConfiguration

    // Colors
    public func background(_ value: String) -> TerminalConfiguration
    public func foreground(_ value: String) -> TerminalConfiguration
    public func selectionBackground(_ value: String) -> TerminalConfiguration
    public func selectionForeground(_ value: String) -> TerminalConfiguration
    public func boldColor(_ value: String) -> TerminalConfiguration
    public func palette(_ index: Int, color: String) -> TerminalConfiguration
    public func minimumContrast(_ value: Double) -> TerminalConfiguration

    // Background
    public func backgroundOpacity(_ value: Double) -> TerminalConfiguration
    public func backgroundBlur(_ value: Int) -> TerminalConfiguration

    // Layout
    public func windowPaddingX(_ value: Int) -> TerminalConfiguration
    public func windowPaddingY(_ value: Int) -> TerminalConfiguration

    // Escape hatch
    public func custom(_ key: String, _ value: String) -> TerminalConfiguration

    public static let `default`: TerminalConfiguration
    public var rendered: String { get }
}

public enum TerminalCursorStyle: String, Sendable, Hashable {
    case block
    case bar
    case underline
}

public enum TerminalConfigCommand: Sendable, Hashable {
    case fontFamily(String)
    case fontSize(Float)
    case fontThicken(Bool)
    case fontThickenStrength(Int)
    case cursorStyle(TerminalCursorStyle)
    case cursorStyleBlink(Bool)
    case cursorColor(String)
    case cursorText(String)
    case cursorOpacity(Double)
    case background(String)
    case foreground(String)
    case selectionBackground(String)
    case selectionForeground(String)
    case boldColor(String)
    case palette(index: Int, color: String)
    case minimumContrast(Double)
    case backgroundOpacity(Double)
    case backgroundBlur(Int)
    case windowPaddingX(Int)
    case windowPaddingY(Int)
    case custom(key: String, value: String)
}

Each fluent method appends the TerminalConfigCommand case of the same name; rendered emits one key = value line per command. The builder variant has matching with* mutating methods (withFontFamily, withCursorColor, …) for composing a default configuration with many overrides.

TerminalTheme

public enum TerminalColorScheme: Sendable {
    case light
    case dark
}

public struct TerminalTheme: Sendable, Hashable {
    public var light: TerminalConfiguration
    public var dark: TerminalConfiguration

    public init(
        light: TerminalConfiguration,
        dark: TerminalConfiguration
    )
}

TerminalController selects the light or dark configuration when the active color scheme changes.

Metrics

public struct TerminalGridMetrics: Sendable, Equatable {
    public var columns: UInt16
    public var rows: UInt16
    public var widthPixels: UInt32
    public var heightPixels: UInt32
    public var cellWidthPixels: UInt32
    public var cellHeightPixels: UInt32
}

public struct InMemoryTerminalViewport: Sendable, Equatable {
    public var columns: UInt16
    public var rows: UInt16
    public var widthPixels: UInt32
    public var heightPixels: UInt32
    public var cellWidthPixels: UInt32
    public var cellHeightPixels: UInt32
}

public struct TerminalInputModifiers: OptionSet, Sendable {
    public static let shift: TerminalInputModifiers
    public static let ctrl: TerminalInputModifiers
    public static let alt: TerminalInputModifiers
    public static let super_: TerminalInputModifiers
}