OpenQode/docs/tui-redesign-plan.md

TUI Professional Visual Redesign - Implementation Plan

Goal

Improve TUI text rendering to be professional-grade like Claude Code, fixing HTML entities, text wrapping, streaming jitter, and layout consistency. VISUAL ONLY - NO functionality changes.

---

User Review Required

Important

New Dependencies Required: This plan requires installing he (HTML entity decoder) and wrap-ansi (width-aware text wrapping). Both are lightweight, pure ESM-compatible, and widely used.

---

Root Cause Analysis

Issue	Source	Fix
' showing literally	marked outputs HTML entities, no decoder	Add he.decode() before rendering
Text bleeding into borders	No width calculation for wrapping	Use wrap-ansi with calculated width
Inconsistent spacing	No theme system, hardcoded values	Create centralized theme module
Streaming jitter	React re-renders on every token	Add batched streaming component
List indentation broken	Inline tokens not properly wrapped	Fix list rendering in markdown

---

Proposed Changes

Phase 1: Add Dependencies

npm install he wrap-ansi

---

Phase 2: Create Theme Module

[NEW] bin/tui-theme.mjs

Central theme configuration:

• Spacing scale: xs=0, sm=1, md=2, lg=3
• Semantic colors: fg, muted, info, warning, error, accent, border
• Border styles with fallback for non-unicode terminals
• Consistent component styling

---

Phase 3: Fix Markdown Renderer

[MODIFY] bin/ink-markdown-esm.mjs

Changes:

1. Import he for HTML entity decoding
2. Import wrap-ansi for width-aware wrapping
3. Apply he.decode() to all text content before rendering
4. Fix inline token rendering to decode entities
5. Improve list item wrapping and indentation
6. Add terminal width awareness for proper wrapping

---

Phase 4: Update Card Components

[MODIFY] bin/opencode-ink.mjs (lines 477-590)

Changes:

1. Import theme module
2. Update SystemCard, UserCard, AgentCard, ErrorCard to use theme
3. Add consistent padding/margin from theme
4. Add flex-based width constraints
5. Ensure proper overflow handling

---

Phase 5: Add Streaming Stability (Optional)

[MODIFY] bin/opencode-ink.mjs

Changes:

1. Add batched state update for streaming content
2. Implement 16ms throttle to reduce jitter
3. Use stable keys for message list

---

Verification Plan

Manual Testing (User)

Since there are no automated TUI tests in this project, verification is manual:

1. HTML Entity Test:

   • Launch TUI: node bin/opencode-ink.mjs
   • Send message containing apostrophes: "what's the best approach?"
   • ✅ Verify: apostrophes render as ' not '

2. Text Wrapping Test:

   • Resize terminal to 80 columns
   • Send long message
   • ✅ Verify: text wraps cleanly, doesn't touch borders

3. List Rendering Test:

   • Ask AI to list something: "list 5 programming languages"
   • ✅ Verify: bullet points render with proper indentation

4. Code Block Test:

   • Ask AI for code: "write a hello world in Python"
   • ✅ Verify: code block has border, syntax highlighting

5. Streaming Stability Test:

   • Send message requiring long response
   • ✅ Verify: output streams without major jitter

6. Functionality Preservation Test:

   • /help → Shows help card
   • /agents → Shows agent menu with scrolling
   • /context → Toggles context
   • /clear → Clears messages
   • ✅ All commands work exactly as before

Cross-Platform Testing

• Windows Terminal + PowerShell
• Windows CMD
• Linux bash (if available)