Skip to content

docs: record the embedding spike - the official path is vt + own renderer #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kiyeonjeon21 merged 1 commit into from
Jul 25, 2026
Merged

docs: record the embedding spike - the official path is vt + own renderer #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ npm-debug.log*
# internal docs
FEEDBACK.md
DEMO.md
GAP-SESSION.md
docs/SHOW-HN.md

# typescript
Expand Down
23 changes: 18 additions & 5 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down