Repository Public
1# ADR 0001 — Terminal engine: SwiftTerm 1.99.2 (libghostty evaluated, deferred)23**Status:** Accepted — 2026-11-014**Deciders:** NEXTERM implementation (Claude Code session on the build Mac)56## Context7CLAUDE.md asks for a maintained Ghostty integration if technically and legally feasible, with a8minimal proof-of-concept before committing, and otherwise a documented alternative. The P09requirements are real PTY sessions, VT/xterm emulation (alternate screen, wide/combining chars,10bracketed paste, mouse), selection, clipboard, search, scrollback, and non-blocking rendering.1112## Spike 1 — libghostty (ghostty-org/ghostty `main`, 1.4.1-dev)13* Toolchain: Ghostty `build.zig.zon` requires `minimum_zig_version = "0.17.0"`; Homebrew ships14 zig 0.17.0, installed for the spike.15* Command: `zig build -Demit-xcframework=true -Dapp-runtime=none -Doptimize=ReleaseFast`16* Result: **320/337 steps succeeded in 1 min 49 s**, then failed at17 `xcrun -sdk macosx metal …/shaders.metal` with18 `error: cannot execute tool 'metal' due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain`.19 Log: `/tmp/nexterm-spike/ghostty-build.log` (reproducible by re-running the command).20* Integration assessment (from `include/ghostty.h`, 330 `ghostty_*` symbols): the C API embeds a21 full *surface* and expects the host to implement the apprt callback table (clipboard, config,22 actions, keyboard, mouse, rendering lifecycle). It is explicitly marked unstable by the Ghostty23 project and is consumed only by Ghostty's own macOS app. License: MIT.24* Verdict: feasible but expensive — a multi-day integration on an unstable API, plus a Zig toolchain25 and the Metal Toolchain component as build prerequisites for every contributor.2627## Spike 2 — SwiftTerm v1.99.2 (migueldeicaza/SwiftTerm)28* License: MIT. Maintenance: last push 2026-11-01 (the day of the spike); 1.7k stars.29* Swift package with `swiftLanguageModes: [.v6]`, macOS 11+, SPM-native; renders through Metal30 (shaders embedded as source, so no Metal Toolchain needed — verified in31 `Apple/Metal/MetalShaderSource.swift`) with a CoreText fallback.32* Verified API surface used by NEXTERM: `LocalProcessTerminalView` (PTY via `LocalProcess` +33 `forkpty`), `LocalProcessTerminalViewDelegate` (title, OSC 7 cwd, process exit),34 `setProcessOutputHandler`, `findNext/findPrevious/searchMatchSummary`, `installColors`,35 `changeScrollback`, `allowMouseReporting`, `optionAsMetaKey`, `setCursorStyle`, Kitty keyboard36 protocol, OSC 8 hyperlinks, accessibility service, fuzz corpus shared with Ghostty.37* Proof of concept (`Sources/NEXTERM/App/NEXTERMApp.swift`, Phase 0): a SwiftUI window hosting38 `NEXTerminalView`; `-zsh` spawned as session leader on `/dev/ttys012`; keyboard input via39 System Events typed `echo NEXTERM_OK cols=$COLUMNS lines=$LINES tty=$(tty)` and the shell replied40 `NEXTERM_OK cols=112 lines=24 tty=/dev/ttys012` (screenshots `/tmp/nexterm-spike/spike{1,3}.png`).41* Build gotcha: SwiftTerm ships a build-tool plugin (`SwiftTermBuildInfoPlugin`); `xcodebuild`42 requires `-skipPackagePluginValidation` (Xcode IDE asks once to trust the plugin).4344## Decision45Use **SwiftTerm 1.99.2** as the terminal engine, pinned exactly. Wrap it behind46`TerminalCore.NEXTerminalView` / `TerminalSession` so the engine is a replaceable implementation47detail. Revisit libghostty when its C API is declared stable; the spike script and log are kept48as the starting point.4950## Consequences51* No Zig or Metal Toolchain prerequisites; `xcodegen` + Xcode build everything.52* Terminal fidelity is SwiftTerm's (xterm-256color, truecolor, alt screen, mouse, bracketed paste,53 Kitty keyboard/graphics); any gap found during acceptance testing is reported as such.54* `-skipPackagePluginValidation` must be passed to `xcodebuild` (handled by `Scripts/build.sh`).55