Initial Release: OpenQode Public Alpha v1.3

docs/tui-redesign-plan.md

@@ -0,0 +1,120 @@
+# 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
+
+```bash
+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)