# TUI Framework Spike — Results (ADR-14 / TUI_DESIGN §15)

Date: 2026-08-09 Environment: macOS 27.0 (Apple Silicon), Node v25.9.0 (spike targets Node ≥ 22), pty xterm-256color 100×30 via node-pty, sources run with tsx.

Candidate naming. This spike uses the task's labels, which are swapped relative to TUI_DESIGN §15.1:

Both candidates render the identical shared demo model (shared/demo.ts): ~2 KB of markdown-ish text streamed at ~30 deltas/s per turn (8-char deltas / 33 ms), settled-block scanning, tool one-liners settling mid-stream, a live status line with a real elapsed timer, a composer echoing keystrokes during streaming, and a status bar. Esc interrupts, restores the terminal, and exits cleanly. Instrumentation is shared (shared/metrics.ts).

# 1. Decision table (7 criteria × 2 candidates)

Score: A passes 7/7 (2 pending human confirmation); B passes 5/7, failing #4 (memory) outright and #2 (caret) as-stock.

# 2. Raw numbers (final 180 s runs, identical workload: 20 turns, 381 settled blocks, ~5,400 synthetic keystrokes, 4 resizes)

Corroborating runs: 60 s and 120 s runs show the same shape (A: 67–76 MB flat-ish, p95 ≈ 0.1 ms; B: slope +56 to +70 MB/min, p95 ≈ 2 ms). Raw JSON: out/summary-a.json, out/summary-b.json (60/120 s snapshots preserved as out/summary-*-60s/120s/180s.json), full pty captures in out/capture-*.txt.

# 3. Methodology (and honest limitations)

# 3.1 Harness

driver/run.ts spawns each candidate inside a real pty (node-pty, xterm-256color, 100×30) so raw mode, SIGWINCH, and TTY code paths are genuine. It injects one keystroke every 33 ms (30 cps) from t = 1.5 s, presses Enter every 40 chars (submits the composer as a settled user message — this also exercises settling during streaming), resizes the pty four times mid-stream, and sends Esc at the end. All measurement is in-process in the candidate (shared/metrics.ts), written to out/metrics-<cand>.json on clean Esc teardown.

Note: node-pty 1.1.0's prebuilt spawn-helper ships without its executable bit on this setup; the harness required a one-time chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper.

# 3.2 Latency definition

Latency = process.hrtime.bigint() at the stdin 'data' event → the first stdout.write() whose payload contains the updated composer text ("❯ " + composer). This measures renderer-side latency (what the framework controls) up to the write-enqueue; kernel/pty/terminal paint time is excluded for both candidates equally, so the comparison is fair but the absolute numbers are a lower bound on glass-to-glass latency.

Two measurement artifacts were found and fixed during the spike — worth recording because naive numbers were wildly wrong:

1. Trailing-space needles. Ink/Yoga trims trailing whitespace at line ends, so an expectation created by a space keystroke never matches any frame and jammed the FIFO (apparent p95 of 1.8 s that was pure artifact — echo was actually ~1–2 ms, confirmed via driver/debug-ink-input.tsx). Fix: space keystrokes are not measured; needles are trimEnd()ed. Applied identically to both candidates.
2. CR merged into string input. Under momentary event-loop lag the pty can coalesce \r + the next char into one chunk, which Ink delivers as string input with key.return === false; the raw \r then polluted the composer and the needle. Fix: embedded CR/LF in string input is treated as Enter (matching candidate A's decoder).

After both fixes: 0 unresolved expectations in every reported run for both candidates.

# 3.3 Memory

process.memoryUsage() sampled every 1 s inside each candidate; slope is a least-squares fit over the last two-thirds of the run. Candidate B's growth is consistent with Ink's <Static> design: settled items remain children of the reconciler/DOM tree for the life of the process, so retained state is O(session), exactly the risk TUI_DESIGN §0.3 called out. This attribution is a hypothesis (heap profiling was not done); the measured RSS/heap growth itself is not in question. Some of B's RSS may be reclaimable under GC pressure, but A under the identical GC policy stays ~flat at < 80 MB, so the comparison stands.

# 3.4 What ran headless vs. what needs a human

Everything in §1–§2 ran headless in a pty (this machine, no human at a screen). The following cannot be signed off programmatically and needs a human pass (TUI_DESIGN §15.2 scenario 7):

• Flicker (criterion 1): run each candidate interactively and scrub a recording frame-by-frame on Terminal.app, iTerm2, kitty, Alacritty, VS Code terminal, and inside tmux:
  shCopy

  cd prototypes/tui-spike
  npm install
  asciinema rec -c "npm run a" /tmp/spike-a.cast   # then: npm run b
  # type while it streams; press Esc to finish; scrub the .cast frame-by-frame

• Selection/copy (criterion 5): while a turn is streaming, select the settled ```ts code block with the mouse, copy, paste to a file, and diff against FENCE_TEXT in shared/demo.ts.
• Resize (criterion 7): drag the window narrow/wide mid-stream and confirm no corrupted rows and a clean live region at the new width.
• Caret (criterion 2), B: observe that Ink shows no cursor while candidate A keeps a hardware caret sitting at the composer position.

# 4. Recommendation

Candidate A — the custom ANSI renderer. This confirms TUI_DESIGN §0.3's prior, now with measurements:

1. B fails a hard criterion. Memory is not flat and exceeds the 150 MB cap within ~30 s of this workload (272 MB at 3 min, still climbing). KHAELOR sessions run for hours; O(session) retained render state is disqualifying without forking Ink's <Static>/DOM internals — the exact ~100-file-fork trap Hermes fell into (HERMES §8.1).
2. B has no caret. Stock Ink hides the hardware cursor for its full lifetime. A real composer would need a synthetic caret or hand-written post-frame cursor writes — at which point we are already reimplementing candidate A's paint discipline inside Ink.
3. A's margins are wide everywhere. p95 echo 0.104 ms (154× inside the 16 ms budget) vs 2.07 ms; 78 MB flat vs 272 MB climbing; 1.9 rows repainted per frame vs 8.8; 2.8× fewer bytes written; zero runtime dependencies vs the ink+react surface.
4. Owned-code cost is small. The entire renderer (live region, damage tracking, DEC 2026 frames, coalescing, settled printing, caret parking) is ~120 lines in this spike; the real Phase 2 cost remains the line editor, exactly as §0.3 predicted — and that cost is identical under Ink, which provides no line editor either.

One genuine positive finding for Ink 7 worth recording: it wraps every frame in DEC 2026 synchronized output and its input-to-write latency (p95 2 ms) comfortably meets the budget. If it did not retain settled content and did not hide the cursor, it would have been viable. Per §15.4, the losing candidate's adapter is to be deleted once the human terminal-matrix pass confirms criterion 1 and 5 for candidate A.

# 5. Artifacts

Author: Simon-Pierre Boucher · contact@spboucher.ai