121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# 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)
|