From b56c5cc6e0fa155dc5d47e6b5780e0ee842a0751 Mon Sep 17 00:00:00 2001 From: Kiyeon Jeon Date: Sun, 26 Jul 2026 03:52:21 +0900 Subject: [PATCH] docs: record the embedding spike - the official path is vt + own renderer The spike (repo datactx-app, brand-independent name pending the rename) proved the toolchain and corrected the plan before any product code: - There is no official Swift package for the full GhosttyKit render path, only third-party binary redistributions of an unstable API. The official embedding path today is libghostty-vt plus your own renderer, demonstrated by ghostty-org/ghostling (official, MIT) - and ghostty's build emits a ready-made ghostty-vt.xcframework, so no third-party repackaging is needed. - Verified here: ghostling builds from source (Zig pinned 0.15.x) and runs; the spike app builds and runs with ghostty-vt probe simd=true roundTrip=true. - Architecture: SwiftTerm pane behind a TerminalPane protocol, libghostty-vt linked and probed but not rendering. The renderer swap becomes an implementation project once the API stabilizes. - cmux was not studied and did not need to be: ghostling is official and MIT, so the GPL-adjacency question never arises. --- .gitignore | 1 + ROADMAP.md | 23 ++++++++++++++++++----- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index 2e232b5..8a82502 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,7 @@ npm-debug.log* # internal docs FEEDBACK.md DEMO.md +GAP-SESSION.md docs/SHOW-HN.md # typescript diff --git a/ROADMAP.md b/ROADMAP.md index 84125cd..fc7bc3c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -421,11 +421,24 @@ see the measure-grain defect in step 6.2. Build one step at a time: on a real dataset; write down what a plain terminal cannot do (results scroll away, no graph, no curation UI). That list is the app's feature spec, and it needs a human at the keyboard, not a score. - 2. **Embedding spike** — minimal Swift app with a GhosttyKit pane - (libghostty-spm) running `claude`; pin and vendor the framework, and keep - the terminal component behind a protocol so SwiftTerm stays a fallback. - Study cmux for architecture only: it is GPL-3.0, so no code may be copied - (QueryPad is MIT). + 2. **Embedding spike** - ✅ Done (2026-07-26, repo `~/dev/personal/projects/datactx-app`, + brand-independent name pending step 9). What the spike corrected before writing code: + there is **no official Swift package for the full GhosttyKit render path** - only + third-party binary redistributions of an API whose own header says it is unstable. The + official embedding path today is **libghostty-vt (the state machine) plus your own + renderer**, demonstrated by `ghostty-org/ghostling` (official, MIT, active) - and + ghostty's build emits a ready-made `ghostty-vt.xcframework` with a modulemap, so no + third-party repackaging is needed at all. + **What was proven on this machine**: ghostling builds from official source (Zig pinned at + 0.15.x, its stated requirement) and runs; and the spike app - one window, a terminal pane + running a login shell - builds and runs with `ghostty-vt probe: simd=true roundTrip=true`, + i.e. Swift <-> Zig interop with the official artifact works (create a terminal, feed VT + bytes through the parser, free). + **The architecture that follows**: the pane is SwiftTerm (mature, pure Swift) behind a + `TerminalPane` protocol - nothing else may import a terminal library - and libghostty-vt + is linked and probed but not yet rendering. When the full embedding API stabilizes, the + swap is an implementation project, not a feasibility question. cmux was not studied and + did not need to be: ghostling is official and MIT, so the GPL question never arises. 3. **Data channel** — MCP over the app-owned local socket plus the first native panel: a result table updating live as the agent queries. 4. **Product skeleton** — per-dataset workspaces, session restore,