SPB Git

Repository Public

0001-terminal-engine.md 3.8 KB

# ADR 0001 — Terminal engine: SwiftTerm 1.99.2 (libghostty evaluated, deferred)

Status: Accepted — 2026-11-01 Deciders: NEXTERM implementation (Claude Code session on the build Mac)

# Context

CLAUDE.md asks for a maintained Ghostty integration if technically and legally feasible, with a minimal proof-of-concept before committing, and otherwise a documented alternative. The P0 requirements are real PTY sessions, VT/xterm emulation (alternate screen, wide/combining chars, bracketed paste, mouse), selection, clipboard, search, scrollback, and non-blocking rendering.

# Spike 1 — libghostty (ghostty-org/ghostty main, 1.4.1-dev)

  • Toolchain: Ghostty build.zig.zon requires minimum_zig_version = "0.17.0"; Homebrew ships zig 0.17.0, installed for the spike.
  • Command: zig build -Demit-xcframework=true -Dapp-runtime=none -Doptimize=ReleaseFast
  • Result: 320/337 steps succeeded in 1 min 49 s, then failed at xcrun -sdk macosx metal …/shaders.metal with error: cannot execute tool 'metal' due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain. Log: /tmp/nexterm-spike/ghostty-build.log (reproducible by re-running the command).
  • Integration assessment (from include/ghostty.h, 330 ghostty_* symbols): the C API embeds a full surface and expects the host to implement the apprt callback table (clipboard, config, actions, keyboard, mouse, rendering lifecycle). It is explicitly marked unstable by the Ghostty project and is consumed only by Ghostty's own macOS app. License: MIT.
  • Verdict: feasible but expensive — a multi-day integration on an unstable API, plus a Zig toolchain and the Metal Toolchain component as build prerequisites for every contributor.

# Spike 2 — SwiftTerm v1.99.2 (migueldeicaza/SwiftTerm)

  • License: MIT. Maintenance: last push 2026-11-01 (the day of the spike); 1.7k stars.
  • Swift package with swiftLanguageModes: [.v6], macOS 11+, SPM-native; renders through Metal (shaders embedded as source, so no Metal Toolchain needed — verified in Apple/Metal/MetalShaderSource.swift) with a CoreText fallback.
  • Verified API surface used by NEXTERM: LocalProcessTerminalView (PTY via LocalProcess + forkpty), LocalProcessTerminalViewDelegate (title, OSC 7 cwd, process exit), setProcessOutputHandler, findNext/findPrevious/searchMatchSummary, installColors, changeScrollback, allowMouseReporting, optionAsMetaKey, setCursorStyle, Kitty keyboard protocol, OSC 8 hyperlinks, accessibility service, fuzz corpus shared with Ghostty.
  • Proof of concept (Sources/NEXTERM/App/NEXTERMApp.swift, Phase 0): a SwiftUI window hosting NEXTerminalView; -zsh spawned as session leader on /dev/ttys012; keyboard input via System Events typed echo NEXTERM_OK cols=$COLUMNS lines=$LINES tty=$(tty) and the shell replied NEXTERM_OK cols=112 lines=24 tty=/dev/ttys012 (screenshots /tmp/nexterm-spike/spike{1,3}.png).
  • Build gotcha: SwiftTerm ships a build-tool plugin (SwiftTermBuildInfoPlugin); xcodebuild requires -skipPackagePluginValidation (Xcode IDE asks once to trust the plugin).

# Decision

Use SwiftTerm 1.99.2 as the terminal engine, pinned exactly. Wrap it behind TerminalCore.NEXTerminalView / TerminalSession so the engine is a replaceable implementation detail. Revisit libghostty when its C API is declared stable; the spike script and log are kept as the starting point.

# Consequences

  • No Zig or Metal Toolchain prerequisites; xcodegen + Xcode build everything.
  • Terminal fidelity is SwiftTerm's (xterm-256color, truecolor, alt screen, mouse, bracketed paste, Kitty keyboard/graphics); any gap found during acceptance testing is reported as such.
  • -skipPackagePluginValidation must be passed to xcodebuild (handled by Scripts/build.sh).
Files main
Menu

Theme