TUI architecture: SolidJS migration, worker isolation, shared component library, event streaming

[windoliver]

Summary

Cross-project TUI architecture decisions that affect the Nexus TUI (@nexus-ai-fs/tui). Canonical issue with full rationale: windoliver/koi#1484. This issue tracks Nexus-specific implementation.

Execution Order

10 issues in 5 waves. Each wave's items can run in parallel within the wave, but waves are sequential — later waves depend on earlier ones.

Wave 0 — Prerequisites (fix what's broken)

Order	Issue	What	Why first
0a	#3623	Fix build-breaking issues — missing imports, broken panels, PanelId/nav mismatch	Nothing else can be validated if the TUI doesn't compile
0b	#3624	UX polish — TabBar click, dead code cleanup, duplicate terminal reset	Clean dead code before migrating it

Wave 0 unblocks everything. No point migrating to SolidJS or adding features on broken foundations.

Wave 1 — Foundation (theme + docs + guard)

Order	Issue	What	Depends on
1a	#3246	Migrate 88 hardcoded colors to semantic theme tokens	Wave 0 (clean codebase)
1b	#3501	TerminalGuard — 60×24 minimum size with responsive sidebar	Wave 0
1c	#3248	Per-screen wireframe documentation for all 10 panels	Wave 0 (panels must be reachable)

These are independent of each other — run all three in parallel. Theme tokens (1a) must land before the SolidJS migration so we migrate semantic tokens, not raw hex values. Wireframes (1c) document the current state before the architecture changes.

Wave 2 — Architecture migration

Order	Issue	What	Depends on
2a	#3632 §1	SolidJS migration (@opentui/react → @opentui/solid)	Wave 1a (theme tokens), Wave 0 (clean code)
2b	#3632 §5	Pin OpenTUI version (remove "latest")	Do during 2a — same PR

This is the biggest single change. Convert panel-by-panel:

1. Shared components first (theme.ts, side-nav.tsx, tab-bar.tsx, command-palette stub)
2. Simplest panel (e.g. Stack) as proof-of-concept
3. Remaining panels in complexity order
4. Remove React + @opentui/react when all panels converted

Wave 3 — Features enabled by new architecture

Order	Issue	What	Depends on
3a	#3626	OpenTUI native components — <code>, <diff>, <markdown>, plugin slots	Wave 2 (SolidJS, plugin slots only available in @opentui/solid)
3b	#3502	Command palette (:) for fuzzy navigation	Wave 2 (simpler with SolidJS signals)
3c	#3632 §3	SSE event streaming for live panel updates	Wave 2 (SolidJS signals make reactive updates trivial)
3d	#3632 §4	Shared component library from @koi/tui-base	Wave 2 + Wave 3b (command palette is a shared component)

These are mostly independent of each other — run in parallel.

Wave 4 — Resilience and advanced

Order	Issue	What	Depends on
4a	#3247	Partial/degraded state handling across panels	Wave 3c (needs SSE health events)
4b	#3632 §2	Worker thread isolation	Wave 3c (SSE is the transport between threads)
4c	#3516	--version flag	Anytime (no deps, low priority)

Worker thread isolation (4b) is last because it's the most invasive change and benefits from all prior work being stable.

Visual dependency graph

Wave 0:  #3623 ──┬── #3624
                 │
Wave 1:  #3246 ──┼── #3501 ── #3248
                 │
Wave 2:  #3632§1 (SolidJS) + pin version
                 │
         ┌───────┼───────┬──────────┐
Wave 3:  #3626   #3502   #3632§3    #3632§4
                          (SSE)     (shared)
                           │
Wave 4:  #3247 ────────── #3632§2 (worker)

Effort estimates

Wave	Issues	Estimated effort	Risk
0	#3623, #3624	1-2 days	Low — known fixes
1	#3246, #3501, #3248	3-4 days (parallel)	Low — mechanical
2	SolidJS migration	5-8 days	Medium — 10+ panels to convert
3	#3626, #3502, SSE, shared lib	4-6 days (parallel)	Medium — new features
4	#3247, worker thread	3-5 days	High — resilience + concurrency

Total: ~16-25 days of focused work.

What changes for Nexus TUI

1. Migrate from @opentui/react to @opentui/solid

Nexus TUI has 10+ panels (files, versions, agents, access, payments, search, events, workflows, connectors, stack, API console) built on React + @opentui/react. SolidJS fine-grained reactivity improves responsiveness — especially for the file explorer, event stream, and API console where data updates frequently.

Nexus-specific notes:

• Zustand stores used throughout — maps to SolidJS stores
• Panel system architecture stays the same (tab bar + side nav + content)
• testRender snapshot tests have identical API in both reconcilers

2. Worker thread isolation

Nexus TUI mixes rendering with API client calls, which can block on slow Nexus server responses. Target: rendering in main thread, API client + data fetching in worker.

Nexus-specific RPC:

• connect(baseUrl, apiKey) — establish Nexus connection
• subscribe(panels) → SSE stream of panel-relevant events
• rpc(method, params) — proxy JSON-RPC calls to Nexus
• search(query) — proxy search API

3. SSE event streaming

Nexus server already has event infrastructure (event streams with sequences, subscriptions, dead letters). Wire SSE from Nexus to TUI for:

• File system changes
• Agent lifecycle events
• Audit entries
• Workflow state transitions
• Lock/unlock events

TUI consumes via 16ms batched event handler.

4. Shared component library

Nexus TUI independently builds components that overlap with Koi and Grove:

• Command palette — planned (TUI: Command palette (:) for fuzzy navigation to 48+ destinations #3502), use shared implementation
• Theme — 88 hardcoded colors (TUI: Migrate 88 hardcoded colors to semantic theme tokens #3246), migrate to shared semantic tokens
• Tab bar / navigation — could share patterns
• Table — used across many panels

5. Pin OpenTUI version

Currently "latest" (unpinned). Pin to the same exact version as Koi and Grove. Unpinned "latest" risks breaking on any publish.

Acceptance criteria

• Wave 0: TUI: fix build-breaking issues — missing imports, broken panels, PanelId/nav mismatch #3623 and TUI: UX polish — TabBar click, dead code cleanup, duplicate terminal reset, minor bugs #3624 resolved — TUI compiles, dead code removed
• Wave 1: Theme tokens (TUI: Migrate 88 hardcoded colors to semantic theme tokens #3246), TerminalGuard (TUI: TerminalGuard — 60×24 minimum size with responsive sidebar #3501), wireframes (TUI: Per-screen wireframe documentation for all 10 panels #3248)
• Wave 2: @opentui/solid + solid-js added, React removed, all panels converted
• Wave 2: OpenTUI version pinned (not "latest")
• Wave 3: Native components (TUI: comprehensive OpenTUI adoption — plugin slots, streaming markdown, code highlighting, responsive layout #3626), command palette (TUI: Command palette (:) for fuzzy navigation to 48+ destinations #3502), SSE events, shared lib
• Wave 4: Partial/degraded state (TUI: Partial/degraded state handling across panels #3247), worker thread isolation