hermes-agent/docs/opentui-upstream-alignment.md

Upstream alignment — how we inherit OpenTUI's performance work for free

Context (maintainer, 2026-06-11): opencode's 100-message cap was a November-era performance workaround, since obsoleted; the next OpenTUI version ships native yoga (≥2× layout performance, more improvements building on it); opencode does not use virtualization.

The invariant that makes alignment free

We are forkless and public-API-only. The windowing layer (S1+S2) drives the STOCK <scrollbox> through documented surface only — onSizeChange, setFrameCallback, scrollTop/viewport/scrollHeight, Solid <Show> mount/unmount. Zero patches to @opentui/core. Every upstream release therefore drops in by bumping three pinned versions in ui-opentui/package.json (@opentui/{core,keymap,solid}, currently 0.4.0). Keep it that way: any new code that needs core behavior goes through a boundary/ wrapper, never a patched dependency.

What native yoga changes for us (and what it doesn't)

• Kills the WASM ratchet (grow-only linear memory → freeable native allocations). This retro-justifies S2 less, but S2's append-time windowing remains correct: transient mounted peaks still cost handles and RSS.
• Does NOT obsolete windowing. The binding constraint is the 65,535-slot native handle table: ~47 handles/row × 3,000 stored rows ≈ 141k handles — over the table at ANY layout speed. Windowing is what makes the 3,000-row scrollback possible; yoga's backend is irrelevant to that math.
• Makes windowing feel even better: 2× layout = cheaper margin remounts = smaller window margins viable and less exposure for the one accepted limit (estimate-height snap under scrollbar jumps). After the bump, re-tune margin/ hysteresis against the scroll cell.

The shim ledger (delete-on-upstream-fix; all in ui-opentui/src/boundary/)

shim	what it papers over	delete when
ffiSafe.ts	u32 draw coords go negative under Node FFI (Bun silently wraps) — ERR_INVALID_ARG_VALUE loop	upstream clamps, or Node FFI path is officially supported
nativeHandles.ts	SyntaxStyle exhaustion crashes mid-mount; degrade-to-unstyled	handle table widened (INDEX_BITS>16) or per-kind tables
renderer.ts exit-signal guard	core 0.4.0 treats SIGPIPE (clipboard spawn) as an exit signal; its own uncaughtException handler allocates a handle and dies (exit-7 masking)	both fixed upstream
clipboard.ts hardening	same SIGPIPE incident class	with the above

Each is (a) isolated, (b) inert if upstream fixes the behavior, (c) worth reporting upstream — four concrete, reproduced, root-caused issues. Filing them is the cheapest alignment lever we have: it converts our workarounds into upstream regression tests. (Needs glitch's go-ahead — public repo activity.)

The upgrade playbook (per upstream release)

1. Branch chore/opentui-X.Y.Z, bump the three pins, npm ci.
2. npm run check (648 tests; the windowing invariants — identical scrollHeight ON/OFF, byte-stable frames across corrections — are literal assertions and will catch behavioral drift).
3. Bench acceptance, sequential: --cell gate (determinism digest; EXPECT a new digest if upstream changed rendering — eyeball the frame, re-bless), --cell mem3000 --msgs 2000 + --cell scroll --msgs 3000 vs current numbers (300–375MB / p99 6–8ms), --cell pipeline (frame pacing ≥22fps).
4. Shim audit: try each boundary shim OFF; delete the ones upstream fixed.
5. Live tmux smoke (scroll sweep / resize / selection-copy), screenshots.
6. Windowing re-tune if layout got faster: margins up or hysteresis down, re-run scroll cell, keep p99 ≤ 17ms gate.

The bench suite IS the upgrade contract — it's exactly the harness that lets us take every upstream improvement within a day of release, with proof.

Questions worth relaying to the maintainer

1. Any plan to widen the 16-bit native handle table (or split per-kind)? That's our hard ceiling, independent of yoga.
2. Is the Node --experimental-ffi path on their support radar, or Bun-only? (Native yoga adds new FFI surface; we run Node.)
3. Would they take the windowing layer's core-agnostic pieces (exact-height spacer pattern, correction-legality rule) as a documented recipe or framework-level utility? We have it production-shaped with tests.