# Stand: libghostty-Integration in MiniTerm

Stand 2026-06-21. MiniTerm baut pro Aufruf eigenständige macOS-`.app`s (eigene
Bundle-ID → eigenes Dock-Icon/⌘-Tab). Bisher SwiftTerm als Terminal. Ziel:
SwiftTerm durch **libghostty** (GPU/Metal-Renderer von Ghostty) ersetzen.

## Erreicht
- **libghostty gebaut** (volle macOS-Variante mit Metal-Renderer, Surface-/App-API),
  liegt als `vendor/libghostty/` (lib/`libghostty.a` arm64 ~135 MB, `include/`,
  `patches/`, `README.md`). Quelle Ghostty **v1.3.1** + Zig **0.15.2**.
- **In MiniTerm integriert, kompiliert, linkt, läuft** — Test-`.app` startet ohne
  Crash mit GPU-gerenderter Login-Shell. Mausrad/Scrollback funktioniert.

## Warum der Build aufwändig war
- Zig 0.15.2 linkt auf dem **Host (macOS 26.5)** kein natives Binary (libSystem-
  Inkompatibilität mit dem 26er-SDK; Auto-Erkennung von `26.x` scheitert).
  Neuere Zig (0.16/0.17) linken, bauen aber Ghostty 1.3.1 nicht (API-Drift).
- Lösung: Build in **macOS-15-VM** (tart, cirruslabs-Image, Apple-Silicon-Host)
  mit aktivem **CLT (15.5-SDK)** → Zig linkt. `metal`-Shader-Compiler nur per
  `DEVELOPER_DIR` aus dem installierten Xcode geholt.
- 3 Build-Patches an Ghostty (in `vendor/libghostty/patches/…patch`):
  build.zig (macOS-`libghostty.a`-Install frei, shared `.so` raus),
  GhosttyXCFramework.zig (nur macOS-Slice, kein iOS), MetallibStep.zig
  (metal via Xcode-`DEVELOPER_DIR`).
- libghostty.a aus VM herauskopiert; Host-Swift linkt sie problemlos (Cross-SDK
  unkritisch). VM + Scratch danach abgeräumt.

## Neue/geänderte Dateien
- `Sources/CGhostty/` — C-Modul (`include/ghostty.h` + `module.modulemap`,
  leeres `shim.c`) für die libghostty-C-API.
- `Sources/MiniTerm/Ghostty.swift` — `GhosttyApp` (einmalig `ghostty_init`,
  Config laden/finalize, `ghostty_runtime_config_s`-Callbacks, `ghostty_app_tick`
  via wakeup) + `GhosttySurfaceView` (NSView, `ghostty_surface_new` mit
  nsview-Zeiger; Größe/Content-Scale/Fokus; Tastatur inkl. Shift+Enter→
  `ghostty_surface_text`; Maus/Scroll).
- `Sources/MiniTerm/main.swift` — Engine-Wahl per Info.plist **`MTEngine`**
  (Default `ghostty`, `swiftterm` = Fallback, auch wenn libghostty-Init scheitert).
- `Package.swift` — CGhostty-Target + linkerSettings:
  `-L vendor/libghostty/lib -lghostty` + Frameworks AppKit/Metal/MetalKit/
  QuartzCore/CoreText/CoreGraphics/CoreVideo/IOSurface/Carbon, `-lc++`.

## Offen / bewusst weggelassen
- **Kein Scrollbalken** — der ist in Ghostty.app host-seitig (`SurfaceScrollView`),
  nicht in libghostty; unsere View bildet ihn nicht nach (Scrollback per Mausrad
  geht). Nachrüstbar.
- **Clipboard-Callbacks no-op** — kein ⌘C/⌘V über libghostty.
- **Font-Family** wird nicht gesetzt (nur `font_size`; Family ginge nur über eine
  Ghostty-Config-Datei via `ghostty_config_load_file`).
- **arm64-only** (kein x86_64-Slice).
- Visuelle Vollprüfung (Tippen/Resize/Reflow) durch Marcus noch offen.

## Reproduzieren ohne VM
`vendor/libghostty/lib/libghostty.a` + `include/` genügen zum Bauen. Neu bauen
nur nötig bei Ghostty-Update → Rezept in `vendor/libghostty/README.md`.