From 3fe10c5d6d39dcb36f2745843361ad9f620d75de Mon Sep 17 00:00:00 2001 From: Ayan De Date: Fri, 8 May 2026 12:08:45 +0530 Subject: [PATCH 01/20] docs: add freecode TUI design spec React + xterm.js architecture with layered terminal/UI overlay, IPC bridge, message store, diff panel, and keybinding system. Logo-on-idle pattern with fade-out on interaction, textarea prompt that auto-resizes and scrolls beyond 5 rows. Co-Authored-By: Claude Opus 4.6 --- .../specs/2026-05-08-freecode-tui-design.md | 331 ++++++++++++++++++ 1 file changed, 331 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-08-freecode-tui-design.md diff --git a/docs/superpowers/specs/2026-05-08-freecode-tui-design.md b/docs/superpowers/specs/2026-05-08-freecode-tui-design.md new file mode 100644 index 00000000..590adb12 --- /dev/null +++ b/docs/superpowers/specs/2026-05-08-freecode-tui-design.md @@ -0,0 +1,331 @@ +# FreeCode TUI Design Specification + +## Context + +FreeCode is a CLI tool that uses the user's existing ChatGPT/Claude browser session (via Playwright/CDP automation) to help with coding tasks. It has no API costs — it drives the web UI programmatically. + +The original design spec describes a TypeScript REPL CLI that drives a browser controller. This spec adds a **React + xterm.js TUI layer** on top, providing a rich, scalable interface similar to opencode but without SST ecosystem coupling. + +**Why React + xterm.js:** +- Monorepo already has Next.js/web stack — patterns transfer directly +- xterm.js provides mature terminal rendering (colors, cursor, scrolling, keyboard handling) +- React gives full component model: composable, testable, extensible +- No SST/OpenTUI coupling — just React + xterm.js +- Future features (diff views, file trees, panels, plugins) slot naturally into React's component model + +--- + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────┐ +│ TUI App (React) │ +│ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ Terminal Layer (xterm.js) │ │ +│ │ - Renders terminal output (stdout/stderr) │ │ +│ │ - Keyboard input forwarding │ │ +│ │ - Cursor management │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ UI Overlay Layer (React DOM) │ │ +│ │ - Chat message list │ │ +│ │ - Prompt input │ │ +│ │ - Panels (diff view, file tree, settings) │ │ +│ │ - Dialogs, toasts, menus │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ Bridge Layer (IPC) │ │ +│ │ - JSON-RPC or event-based communication │ │ +│ │ - Connects TUI to CLI backend │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ CLI Backend (Node.js/TypeScript) │ +│ - Command parsing │ +│ - Browser controller (Playwright/CDP) │ +│ - Context engine │ +│ - Response parser │ +│ - File applicator │ +└─────────────────────────────────────────────────────────┘ +``` + +**Key principle:** The terminal layer and UI overlay layer are separate. The terminal renders raw output, the UI overlay renders interactive React components. They can coexist (terminal output above, UI panels overlaying). + +--- + +## Component Hierarchy + +### Core Components + +``` + +├── // xterm.js container +│ └── xterm.js instance // Renders stdout/stderr +├── // React DOM layer +│ ├── +│ │ ├── // Visible only when idle, fades on interaction +│ │ ├── +│ │ │ ├── +│ │ │ └── +│ │ │ ├── +│ │ │ ├── +│ │ │ └── +│ │ └── +│ ├── +│ │ ├── +│ │ ├── +│ │ └── +│ └── +│ ├── +│ ├── +│ └── +``` + +### Prompt Input Behavior (MVP) + +The prompt follows a two-state UX pattern: + +**Initial State (idle):** +- Logo displayed centered above the input area +- `` at the bottom, always visible +- Cursor blinks in the textarea, ready for input + +**Active State (user is typing):** +- Logo fades out and is removed from the DOM +- `` remains at the bottom — it's a `