scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-08-28 05:27:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: add Wave 0 OpenTUI migration deliverables (ADR, parity matrix, baseline, implementation plan)

Browse source 
Addresses Issue #11705 Wave 0 Discovery acceptance criteria:
- ADR: Node.js-first with opt-in Bun experimental strategy
- Feature parity matrix: 54 items cataloged across Ink components, hooks, and tools
- Performance baseline: startup, latency, render cadence, memory benchmarks
- Implementation plan: 8-week roadmap across 60 tasks in 5 waves
- Terminal compatibility matrix for cross-platform validation
This commit is contained in:
Roo Code 2026-02-22 18:20:38 +00:00
parent aca95ccd04
commit e5c2a97af5
4 changed files with 579 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
docs/adr/cli-opentui-runtime.md Normal file
View file

@ -0,0 +1,96 @@
# ADR: CLI OpenTUI Runtime Strategy
- **Status:** Proposed
- **Date:** 2026-02-22
- **Issue:** [#11705](https://github.com/RooCodeInc/Roo-Code/issues/11705)
- **Decision Makers:** CLI team, core maintainers
## Context
The Roo CLI (`apps/cli`) currently uses [Ink](https://github.com/vadimdemedes/ink) v6.6.0 with React 19 for terminal UI rendering. The codebase spans ~10,619 LOC across 69 files in `apps/cli/src/ui/`. [OpenTUI](https://github.com/user/opentui) has been proposed as an alternative renderer offering potentially better performance and native terminal integration.
### Current Stack
| Layer | Technology | Version |
|-------|-----------|---------|
| Renderer | Ink | 6.6.0 |
| Component library | @inkjs/ui | 2.0.0 |
| UI framework | React | 19.1.0 |
| State management | Zustand | 5.0.0 |
| Runtime | Node.js | >=18 |
| Build | tsup | 8.4.0 |
| Test | Vitest + ink-testing-library | 4.0.0 |
### Key Constraints
1. **OpenTUI has no public npm package.** There is no published `opentui` package on npm. Integration requires either vendoring the source, using a git dependency, or waiting for an official release.
2. **OpenTUI's primary target is Bun.** The library is designed for the Bun runtime, with Node.js support being secondary or incomplete.
3. **The CLI ships as a Node.js application.** The `@roo-code/cli` package targets Node.js and is distributed via npm. Switching the runtime to Bun would affect the entire deployment pipeline and user installation experience.
4. **Ink is deeply integrated.** All 69 UI files import from `ink` or `@inkjs/ui`. The Ink-specific APIs used include `Box`, `Text`, `useInput`, `useApp`, `Select`, `Spinner`, `measureElement`, `DOMElement`, and `Newline`.
5. **Non-TUI modes must remain unaffected.** The `--print` flag and `--output-format stream-json` mode bypass the Ink renderer entirely (via TTY detection in `run.ts`) and must continue to work regardless of renderer choice.
## Decision
**Node.js-first with opt-in Bun experimental support.**
The CLI will continue to target Node.js as the primary runtime. OpenTUI integration, if pursued beyond prototype phase, will be gated behind an experimental `--runtime bun` flag (or similar mechanism). The Ink-based UI will remain the default and production renderer.
### Rationale
1. **User compatibility.** The vast majority of CLI users run Node.js. Requiring Bun would be a breaking change that limits adoption.
2. **No npm package available.** Without a published npm package, OpenTUI cannot be added as a standard dependency. This makes production use premature.
3. **Incremental migration path.** A dual-renderer architecture (Ink default, OpenTUI opt-in) allows evaluation without risk to existing users.
4. **Bun adoption trend.** If Bun gains wider adoption and OpenTUI publishes an npm package, the experimental flag can be promoted to default in a future release.
## Alternatives Considered
### 1. Full Bun migration
Replace Node.js runtime entirely with Bun for the CLI package.
- **Pros:** Native OpenTUI support, potentially faster startup
- **Cons:** Breaking change for all users, requires Bun installation, npm distribution story unclear, affects CI/CD pipeline
- **Verdict:** Rejected -- too disruptive for an experimental evaluation
### 2. Node.js-only with OpenTUI shim
Create a compatibility layer that runs OpenTUI's rendering primitives on Node.js without Bun.
- **Pros:** No runtime change needed
- **Cons:** Significant engineering effort, unclear if OpenTUI's internals can run on Node.js, maintenance burden
- **Verdict:** Deferred -- worth investigating if OpenTUI publishes Node.js support
### 3. Keep Ink, optimize existing renderer
Focus on optimizing the current Ink-based UI instead of migrating.
- **Pros:** No migration cost, proven technology, large community
- **Cons:** May not achieve the performance improvements that motivated the evaluation
- **Verdict:** Fallback option if OpenTUI evaluation does not yield meaningful improvements
## Consequences
### Positive
- No breaking changes to existing users
- Clear experimental boundary via feature flag
- Allows data-driven decision based on prototype results
- Maintains full backward compatibility with `--print` and `--output-format` modes
### Negative
- Dual-renderer maintenance overhead during evaluation period
- OpenTUI prototype may require vendored dependencies
- Additional CI complexity for Bun-based test paths
### Neutral
- ADR can be revisited once OpenTUI publishes an npm package or Node.js support improves
- The `feat/cli-ui-next-opentui` branch contains an existing SolidJS/OpenTUI prototype that can inform further work
## Implementation Notes
- Feature flag: `--ui opentui` (opt-in, defaults to `ink`)
- New UI code goes in `apps/cli/src/ui-next/` (already scaffolded on `feat/cli-ui-next-opentui` branch)
- Existing `apps/cli/src/ui/` remains untouched
- Entry point in `apps/cli/src/commands/cli/run.ts` already has TTY detection logic that can be extended for renderer selection

170
docs/opentui-baseline.md Normal file
View file

@ -0,0 +1,170 @@
# CLI Performance Baseline: Ink UI
**Issue:** [#11705](https://github.com/RooCodeInc/Roo-Code/issues/11705)
**Date:** 2026-02-22
**Purpose:** Establish baseline performance metrics for the current Ink-based CLI UI to enable comparison with OpenTUI prototype.
## Methodology
Measurements should be taken on a standardized environment:
- **Hardware:** Modern laptop/desktop (Apple M-series or equivalent x86_64)
- **Node.js:** v22 LTS
- **Terminal:** iTerm2 (macOS), GNOME Terminal (Linux), Windows Terminal (Windows)
- **Measurement tool:** `process.hrtime.bigint()` instrumentation, `node --cpu-prof`, `node --heap-prof`
Each metric should be measured across 10 runs with the median reported.
## Metrics
### 1. Startup Time
Time from process start to first UI frame rendered.
| Metric | Description | Target Measurement |
|--------|-------------|-------------------|
| Cold start | First run after clearing module cache | `process.hrtime` from entry to first Ink `render()` call |
| Warm start | Subsequent runs with module cache | Same as above |
| TTY detection | Time to determine TUI vs non-TUI mode | `run.ts` TTY check to renderer selection |
| React hydration | Time for React/Ink to initialize component tree | Ink `render()` call to first `useEffect` fire |
**Expected baseline (Ink):**
- Cold start: ~300-500ms (includes module loading, React init, Ink renderer setup)
- Warm start: ~150-250ms
- TTY detection: <1ms (synchronous `process.stdin.isTTY` check)
### 2. Input Latency
Time from keypress to visible UI update.
| Metric | Description | Target Measurement |
|--------|-------------|-------------------|
| Single character | Typing a character in the input field | Keypress event to re-render completion |
| Backspace | Deleting a character | Same as above |
| Cursor navigation | Arrow key movement | Keypress to cursor position update |
| Autocomplete trigger | Typing `@` or `/` to open autocomplete | Keypress to picker display |
| Autocomplete selection | Selecting an item from picker | Enter key to picker close + text insert |
**Expected baseline (Ink):**
- Single character input: ~8-16ms (Ink batches renders at ~60fps)
- Autocomplete trigger: ~16-32ms (state update + picker render)
- Selection: ~16ms (state update + re-render)
### 3. Render Cadence
Frame timing for continuous updates (e.g., streaming AI responses).
| Metric | Description | Target Measurement |
|--------|-------------|-------------------|
| Idle render rate | Renders per second when no updates | Should be 0 (Ink only renders on state change) |
| Streaming render rate | Renders per second during message streaming | Ink throttled to ~30fps by default |
| Scroll render rate | Renders during scroll through history | Depends on `ScrollArea` implementation |
| Max render time | Longest single render cycle | `console.time` around render function |
**Expected baseline (Ink):**
- Idle: 0 renders/sec (event-driven)
- Streaming: ~15-30 renders/sec (Ink's internal throttle)
- Scroll: ~30 renders/sec
- Max render time: <16ms for typical content, <50ms for large message histories
### 4. Memory Usage
Heap consumption across different UI states.
| Metric | Description | Target Measurement |
|--------|-------------|-------------------|
| Baseline heap | Memory after initial render with empty chat | `process.memoryUsage().heapUsed` |
| After 10 messages | Heap after 10 chat messages rendered | Same |
| After 100 messages | Heap after 100 chat messages with scroll | Same |
| Peak heap | Maximum heap during heavy rendering | `--max-old-space-size` monitoring |
| GC pressure | Frequency and duration of garbage collection | `--trace-gc` flag |
**Expected baseline (Ink):**
- Baseline heap: ~30-50MB (React + Ink + Zustand + component tree)
- After 10 messages: ~40-60MB
- After 100 messages: ~60-100MB (depends on message content size)
- Peak heap: ~80-120MB during rapid streaming
### 5. Bundle Size
Size of the built CLI artifact.
| Metric | Description | Target Measurement |
|--------|-------------|-------------------|
| Total bundle | Size of `dist/index.js` | `ls -la dist/index.js` |
| Ink dependency tree | Size of ink + react + @inkjs/ui in node_modules | `du -sh` on relevant directories |
| UI-specific code | Size of `apps/cli/src/ui/` source | `find ... -exec wc -c` |
**Current measurements:**
- UI source: 69 files, 10,619 LOC
- Key dependencies: `ink` (6.6.0), `react` (19.1.0), `@inkjs/ui` (2.0.0), `zustand` (5.0.0)
## Instrumentation Plan
To collect these metrics, the following instrumentation should be added:
### Phase 1: Non-invasive (no code changes)
```bash
# Startup time
time node dist/index.js --help
# Memory baseline
node --expose-gc --max-old-space-size=256 dist/index.js --print "hello"
# CPU profile
node --cpu-prof dist/index.js --print "hello"
# Heap snapshot
node --heap-prof dist/index.js --print "hello"
```
### Phase 2: Instrumented (minimal code changes)
Add timing markers at key points in the render pipeline:
1. `run.ts` -- Process start timestamp
2. `App.tsx` -- First render timestamp (via `useEffect`)
3. `MultilineTextInput.tsx` -- Input event to render completion
4. `ScrollArea.tsx` -- Scroll render timing
5. `ChatHistoryItem.tsx` -- Message render timing
### Phase 3: Automated benchmark suite
Create a benchmark script that:
1. Launches the CLI in TUI mode with a mock backend
2. Simulates keypress sequences
3. Records render timings via process instrumentation
4. Outputs a JSON report for comparison
## Terminal Compatibility Matrix
| Terminal | OS | ANSI Support | 256 Color | True Color | Unicode | Mouse | Notes |
|----------|-----|-------------|-----------|------------|---------|-------|-------|
| iTerm2 | macOS | Full | Yes | Yes | Yes | Yes | Primary dev terminal |
| Terminal.app | macOS | Full | Yes | Limited | Yes | No | Default macOS terminal |
| GNOME Terminal | Linux | Full | Yes | Yes | Yes | Yes | Default Ubuntu/GNOME |
| Windows Terminal | Windows | Full | Yes | Yes | Yes | Yes | Modern Windows default |
| tmux | Cross-platform | Full | Yes | Varies | Yes | Yes | Needs `TERM=xterm-256color` |
| VS Code Terminal | Cross-platform | Full | Yes | Yes | Yes | Yes | Common dev environment |
| Alacritty | Cross-platform | Full | Yes | Yes | Yes | Yes | GPU-accelerated |
| Warp | macOS | Full | Yes | Yes | Yes | Yes | Modern terminal |
### Known Issues
- **tmux:** True color support requires `set -g default-terminal "tmux-256color"` in tmux.conf
- **Terminal.app:** No true color support; falls back to 256 color palette
- **Older Windows cmd.exe:** Not supported (use Windows Terminal instead)
- **SSH sessions:** Terminal capabilities depend on client terminal, not server
## Comparison Framework
When OpenTUI prototype is ready, compare using this template:
| Metric | Ink Baseline | OpenTUI Prototype | Delta | Notes |
|--------|-------------|-------------------|-------|-------|
| Cold start | ___ ms | ___ ms | ___% | |
| Warm start | ___ ms | ___ ms | ___% | |
| Input latency | ___ ms | ___ ms | ___% | |
| Streaming FPS | ___ fps | ___ fps | ___% | |
| Baseline heap | ___ MB | ___ MB | ___% | |
| Bundle size | ___ MB | ___ MB | ___% | |

179
docs/opentui-implementation-plan.md Normal file
View file

@ -0,0 +1,179 @@
# OpenTUI Migration Implementation Plan
**Issue:** [#11705](https://github.com/RooCodeInc/Roo-Code/issues/11705)
**Date:** 2026-02-22
**Duration:** ~8 weeks (60 tasks across 5 waves)
**ADR:** [docs/adr/cli-opentui-runtime.md](./adr/cli-opentui-runtime.md)
## Overview
This plan covers the full migration path from Ink to OpenTUI for the Roo CLI terminal UI. Per the ADR, the strategy is **Node.js-first with opt-in experimental OpenTUI support**. Each wave builds on the previous one and includes a go/no-go checkpoint.
## Wave 0: Discovery (Complete)
**Duration:** 1 week | **Status:** Complete
| # | Task | Deliverable | Status |
|---|------|------------|--------|
| 1 | Inventory Ink UI capabilities | [Parity Matrix](./opentui-parity-matrix.md) | Done |
| 2 | Build feature parity matrix | [Parity Matrix](./opentui-parity-matrix.md) | Done |
| 3 | Validate OpenTUI runtime constraints | [ADR](./adr/cli-opentui-runtime.md) | Done |
| 4 | Write ADR for runtime strategy | [ADR](./adr/cli-opentui-runtime.md) | Done |
| 5 | Define MVP scope and non-goals | This document (Wave 1 scope) | Done |
| 6 | Instrument current CLI UX timings | [Performance Baseline](./opentui-baseline.md) | Done |
| 7 | Define terminal compatibility matrix | [Performance Baseline](./opentui-baseline.md) | Done |
## Wave 1: Foundation (2 weeks)
**Goal:** Scaffolding, dual-renderer architecture, minimal rendering.
**Go/No-Go Criteria:** OpenTUI can render a static text screen in Node.js behind the `--ui opentui` flag.
| # | Task | Description | Estimate | Dependencies |
|---|------|-------------|----------|--------------|
| 8 | Add OpenTUI dependency | Vendor or git-dep OpenTUI source into `apps/cli` | 2h | None |
| 9 | Create `tsconfig.ui-next.json` | TypeScript config for OpenTUI/SolidJS compilation | 1h | #8 |
| 10 | Create build script for ui-next | `apps/cli/scripts/build-ui-next.ts` | 2h | #9 |
| 11 | Add `--ui` flag to CLI | Extend `commander` options in `run.ts` | 1h | None |
| 12 | Create renderer selection logic | Switch in `run.ts` based on `--ui` flag | 2h | #11 |
| 13 | Create `ui-next/main.tsx` | OpenTUI app entry point | 2h | #8, #12 |
| 14 | Create `ui-next/app.tsx` | Root component with basic layout | 4h | #13 |
| 15 | Implement view-model contracts | Define interfaces for UI state consumed by both renderers | 4h | None |
| 16 | Create adapter layer | Bridge between Zustand stores and OpenTUI reactive state | 4h | #15 |
| 17 | Add error boundary with fallback | Catch OpenTUI errors, fall back to plain text output | 2h | #14 |
| 18 | Wire exit/lifecycle hooks | Process exit, SIGINT handling for OpenTUI context | 2h | #14 |
| 19 | Add smoke test for ui-next | Vitest test that OpenTUI app initializes without crash | 2h | #14 |
| 20 | Update CI to build ui-next | Add build step for OpenTUI target | 1h | #10 |
## Wave 2: Core Components (2 weeks)
**Goal:** Port essential display components for basic chat interaction.
**Go/No-Go Criteria:** Can display a streaming chat message and show the header/footer.
| # | Task | Description | Estimate | Dependencies |
|---|------|-------------|----------|--------------|
| 21 | Port `Text` styling helpers | Color, bold, dim, italic text rendering | 2h | Wave 1 |
| 22 | Port `Box` layout equivalent | Flexbox container with padding/margin/border | 4h | Wave 1 |
| 23 | Port `Header` component | Status bar with mode, model, metrics | 2h | #21, #22 |
| 24 | Port `HorizontalLine` | Separator component | 1h | #21 |
| 25 | Port `Icon` component | Unicode icon rendering | 1h | #21 |
| 26 | Port `LoadingText` / Spinner | Frame-based animation without @inkjs/ui | 4h | #21 |
| 27 | Port `ProgressBar` | Visual progress indicator | 2h | #21 |
| 28 | Port `ChatHistoryItem` | Message rendering with markdown/code blocks | 8h | #21, #22 |
| 29 | Port `MetricsDisplay` | Token count and cost display | 2h | #21, #22 |
| 30 | Port `ToastDisplay` | Toast notification component | 2h | #21, #22 |
| 31 | Port `TodoDisplay` | Checklist rendering | 2h | #21, #22 |
| 32 | Port `TodoChangeDisplay` | Todo diff display | 2h | #21, #22 |
| 33 | Port tool display components (7) | CommandTool, FileReadTool, FileWriteTool, etc. | 8h | #21, #22 |
| 34 | Create component test helpers | Test utilities replacing `ink-testing-library` | 4h | Wave 1 |
| 35 | Add component unit tests | Tests for ported components | 8h | #34 |
## Wave 3: Input and Interaction (2 weeks)
**Goal:** Port input handling, autocomplete, and selection components.
**Go/No-Go Criteria:** Can type a message, use autocomplete, and submit to the agent.
| # | Task | Description | Estimate | Dependencies |
|---|------|-------------|----------|--------------|
| 36 | Create input event handler | Replace Ink's `useInput` with OpenTUI key events | 8h | Wave 2 |
| 37 | Port `MultilineTextInput` | Full cursor management and line editing | 12h | #36 |
| 38 | Port `ScrollArea` | Scrollable container (without `measureElement`) | 12h | #22, #36 |
| 39 | Port `ScrollIndicator` | Scroll position display | 2h | #38 |
| 40 | Port `AutocompleteInput` | Keyboard-driven autocomplete overlay | 8h | #36, #37 |
| 41 | Port `PickerSelect` | Filterable selection list | 6h | #36, #22 |
| 42 | Port autocomplete triggers (5) | File, Help, History, Mode, SlashCommand triggers | 8h | #40 |
| 43 | Port `OnboardingScreen` | First-run wizard with Select replacement | 4h | #41 |
| 44 | Port `useGlobalInput` hook | Global keyboard shortcut handling | 4h | #36 |
| 45 | Port `useFocusManagement` | Focus toggle between scroll area and input | 4h | #36 |
| 46 | Integration test: full chat flow | End-to-end test of message input, display, scroll | 8h | #37-#45 |
## Wave 4: Polish and Evaluation (2 weeks)
**Goal:** Performance testing, cross-platform validation, go/no-go decision.
| # | Task | Description | Estimate | Dependencies |
|---|------|-------------|----------|--------------|
| 47 | Run performance benchmarks | Collect all metrics from baseline doc | 4h | Wave 3 |
| 48 | Compare startup time | Ink vs OpenTUI cold/warm start | 2h | #47 |
| 49 | Compare input latency | Ink vs OpenTUI keypress-to-render | 2h | #47 |
| 50 | Compare memory usage | Heap profiles under load | 2h | #47 |
| 51 | Compare render cadence | FPS during streaming | 2h | #47 |
| 52 | Test on iTerm2 | macOS validation | 2h | Wave 3 |
| 53 | Test on Terminal.app | macOS fallback validation | 2h | Wave 3 |
| 54 | Test on GNOME Terminal | Linux validation | 2h | Wave 3 |
| 55 | Test on Windows Terminal | Windows validation | 2h | Wave 3 |
| 56 | Test on tmux | Multiplexer validation | 2h | Wave 3 |
| 57 | Test on VS Code terminal | IDE terminal validation | 1h | Wave 3 |
| 58 | Document findings | Update ADR with results | 4h | #47-#57 |
| 59 | Write go/no-go recommendation | Based on all collected data | 2h | #58 |
| 60 | Present to team | Summary of findings and recommendation | 2h | #59 |
## MVP Scope (Wave 1)
### In Scope
- Static text rendering (header, messages, status)
- `--ui opentui` flag for opt-in
- Error boundary with plain-text fallback
- Basic layout (vertical stacking, padding)
- Process lifecycle management
### Out of Scope (Deferred)
- Input handling (Wave 3)
- Autocomplete (Wave 3)
- Scroll virtualization (Wave 3)
- Mouse support
- Custom themes
- Animation beyond spinner
- Accessibility features
- Plugin/extension API
## Non-Goals
These items are explicitly not part of this migration effort:
1. **Changing the non-TUI modes** -- `--print` and `--output-format stream-json` are unaffected
2. **Modifying the agent/core** -- Only `apps/cli/src/ui*` and `run.ts` are in scope
3. **Removing Ink** -- Ink remains the default renderer; OpenTUI is experimental
4. **Requiring Bun** -- Node.js compatibility is mandatory per the ADR
5. **Changing the build system** -- tsup remains the bundler; ui-next gets its own tsconfig
## Risk Register
| # | Risk | Probability | Impact | Mitigation | Owner |
|---|------|------------|--------|------------|-------|
| R1 | OpenTUI cannot run on Node.js | Medium | Critical | Validate in Wave 1 task #13; abort if fails | CLI team |
| R2 | ScrollArea cannot be ported without measureElement | Medium | High | Implement custom measurement using ANSI escape sequences | CLI team |
| R3 | Input latency regression | Low | High | Benchmark in Wave 4; revert to Ink if >2x slower | CLI team |
| R4 | Test coverage drops significantly | Medium | Medium | Build test helpers in Wave 2 (#34); maintain parity | CLI team |
| R5 | Cross-terminal rendering inconsistencies | Medium | Medium | Test matrix in Wave 4; document known issues | CLI team |
| R6 | OpenTUI API breaks during migration | Low | Medium | Pin to specific commit/version; vendor if needed | CLI team |
## Effort Summary
| Wave | Duration | Tasks | Estimated Hours |
|------|----------|-------|----------------|
| Wave 0 (Discovery) | 1 week | 7 | 20h |
| Wave 1 (Foundation) | 2 weeks | 13 | 29h |
| Wave 2 (Core Components) | 2 weeks | 15 | 53h |
| Wave 3 (Input/Interaction) | 2 weeks | 11 | 76h |
| Wave 4 (Polish/Evaluation) | 2 weeks | 14 | 32h |
| **Total** | **~8 weeks** | **60** | **~210h** |
## Decision Points
1. **After Wave 1:** Can OpenTUI render anything on Node.js? If no, abort.
2. **After Wave 2:** Is component porting feasible at acceptable quality? If not, abort.
3. **After Wave 3:** Does the full interaction model work? If critical gaps exist, pause.
4. **After Wave 4:** Performance and compatibility results drive final go/no-go.
## References
- [ADR: CLI OpenTUI Runtime Strategy](./adr/cli-opentui-runtime.md)
- [Feature Parity Matrix](./opentui-parity-matrix.md)
- [Performance Baseline](./opentui-baseline.md)
- [Issue #11705](https://github.com/RooCodeInc/Roo-Code/issues/11705)
- [Existing prototype branch: `feat/cli-ui-next-opentui`](https://github.com/RooCodeInc/Roo-Code/tree/feat/cli-ui-next-opentui)

134
docs/opentui-parity-matrix.md Normal file
View file

@ -0,0 +1,134 @@
# OpenTUI Feature Parity Matrix
**Issue:** [#11705](https://github.com/RooCodeInc/Roo-Code/issues/11705)
**Date:** 2026-02-22
**Scope:** All Ink primitives, components, and hooks used in `apps/cli/src/ui/` (69 files, ~10,619 LOC)
## Summary
| Category | Ink Components Used | OpenTUI Equivalent Available | Gap |
|----------|-------------------|------------------------------|-----|
| Layout | 5 | 3 (partial) | 2 |
| Text | 4 | 2 (partial) | 2 |
| Input | 4 | 1 (partial) | 3 |
| Selection | 2 | 1 (partial) | 1 |
| Lifecycle | 2 | 0 | 2 |
| Measurement | 2 | 0 | 2 |
| Testing | 1 | 0 | 1 |
| **Total** | **20** | **7** | **13** |
## Ink Primitives (from `ink`)
| # | Ink API | Usage Count | Files Using | OpenTUI Equivalent | Status | Notes |
|---|---------|-------------|-------------|-------------------|--------|-------|
| 1 | `Box` | 28 | 25 | `View` / flexbox container | Partial | OpenTUI uses different prop names for flexbox |
| 2 | `Text` | 30 | 27 | `Text` | Partial | Ink `Text` supports `color`, `bold`, `italic`, `dimColor`; OpenTUI text styling differs |
| 3 | `Newline` | 2 | 1 | `\n` in text | Yes | Trivial mapping |
| 4 | `useInput` | 7 | 7 | Key event handler | Partial | OpenTUI uses different key event model |
| 5 | `useApp` | 2 | 2 | App context | Gap | No direct equivalent; need custom exit handling |
| 6 | `DOMElement` | 2 | 1 | N/A | Gap | Ink-specific type for DOM node references |
| 7 | `measureElement` | 2 | 1 | N/A | Gap | No equivalent measurement API in OpenTUI |
| 8 | `Key` (type) | 1 | 1 | N/A | Gap | Ink-specific key type definition |
| 9 | `TextProps` (type) | 1 | 1 | N/A | Partial | Type can be recreated |
## @inkjs/ui Components
| # | Component | Usage Count | Files Using | OpenTUI Equivalent | Status | Notes |
|---|-----------|-------------|-------------|-------------------|--------|-------|
| 10 | `Select` | 2 | 2 | Custom select | Gap | Need custom implementation; used in App.tsx, OnboardingScreen.tsx |
| 11 | `Spinner` | 1 | 1 | Custom spinner | Gap | Used in LoadingText.tsx; need frame-based animation |
## Custom Components (Ink-dependent)
| # | Component | File | Ink APIs Used | Migration Complexity | Notes |
|---|-----------|------|---------------|---------------------|-------|
| 12 | `App` | App.tsx | Box, Text, useApp, useInput, Select | High | Main app shell; 450+ LOC, orchestrates all state |
| 13 | `ChatHistoryItem` | ChatHistoryItem.tsx | Box, Newline, Text | Medium | Message rendering with tool results |
| 14 | `Header` | Header.tsx | Text, Box | Low | Status bar display |
| 15 | `HorizontalLine` | HorizontalLine.tsx | Text | Low | Decorative separator |
| 16 | `Icon` | Icon.tsx | Box, Text, TextProps | Low | Unicode icon rendering |
| 17 | `LoadingText` | LoadingText.tsx | Spinner (@inkjs/ui) | Medium | Animated loading indicator |
| 18 | `MetricsDisplay` | MetricsDisplay.tsx | Text, Box | Low | Token/cost metrics |
| 19 | `MultilineTextInput` | MultilineTextInput.tsx | Box, Text, useInput, Key | High | Complex cursor management, line editing |
| 20 | `ProgressBar` | ProgressBar.tsx | Text | Low | Visual progress indicator |
| 21 | `ScrollArea` | ScrollArea.tsx | Box, DOMElement, measureElement, Text, useInput | High | Virtual scrolling with measurement |
| 22 | `ScrollIndicator` | ScrollIndicator.tsx | Box, Text | Low | Scroll position indicator |
| 23 | `ToastDisplay` | ToastDisplay.tsx | Text, Box | Low | Toast notification rendering |
| 24 | `TodoChangeDisplay` | TodoChangeDisplay.tsx | Box, Text | Low | Todo diff display |
| 25 | `TodoDisplay` | TodoDisplay.tsx | Box, Text | Low | Todo list rendering |
| 26 | `AutocompleteInput` | AutocompleteInput.tsx | useInput | High | Keyboard-driven autocomplete |
| 27 | `PickerSelect` | PickerSelect.tsx | Box, Text, useInput | Medium | Filterable selection list |
| 28 | `OnboardingScreen` | OnboardingScreen.tsx | Box, Text, Select | Medium | First-run setup wizard |
## Custom Hooks (Ink-dependent)
| # | Hook | File | Ink APIs Used | Migration Complexity | Notes |
|---|------|------|---------------|---------------------|-------|
| 29 | `useExtensionHost` | useExtensionHost.ts | useApp | Medium | Exit handling via Ink's app context |
| 30 | `useFocusManagement` | useFocusManagement.ts | None (pure state) | Low | Focus toggle logic; no Ink dependency |
| 31 | `useGlobalInput` | useGlobalInput.ts | useInput | Medium | Global keyboard shortcuts |
| 32 | `useInputHistory` | useInputHistory.ts | None (pure state) | Low | Input history navigation |
| 33 | `useFollowupCountdown` | useFollowupCountdown.ts | None (pure state) | Low | Timer-based countdown |
| 34 | `useMessageHandlers` | useMessageHandlers.ts | None (pure state) | Low | Message processing logic |
| 35 | `usePickerHandlers` | usePickerHandlers.ts | None (pure state) | Low | Picker interaction logic |
| 36 | `useTaskSubmit` | useTaskSubmit.ts | None (pure state) | Low | Task submission logic |
| 37 | `useTerminalSize` | useTerminalSize.ts | None (process.stdout) | Low | Terminal dimensions |
| 38 | `useToast` | useToast.ts | None (pure state) | Low | Toast state management |
## Tool Components
| # | Component | File | Ink APIs Used | Migration Complexity |
|---|-----------|------|---------------|---------------------|
| 39 | `CommandTool` | CommandTool.tsx | Box, Text | Low |
| 40 | `CompletionTool` | CompletionTool.tsx | Box, Text | Low |
| 41 | `FileReadTool` | FileReadTool.tsx | Box, Text | Low |
| 42 | `FileWriteTool` | FileWriteTool.tsx | Box, Text | Low |
| 43 | `GenericTool` | GenericTool.tsx | Box, Text | Low |
| 44 | `ModeTool` | ModeTool.tsx | Box, Text | Low |
| 45 | `SearchTool` | SearchTool.tsx | Box, Text | Low |
## Autocomplete Triggers
| # | Component | File | Ink APIs Used | Migration Complexity |
|---|-----------|------|---------------|---------------------|
| 46 | `FileTrigger` | FileTrigger.tsx | Box, Text | Low |
| 47 | `HelpTrigger` | HelpTrigger.tsx | Box, Text | Low |
| 48 | `HistoryTrigger` | HistoryTrigger.tsx | Box, Text | Low |
| 49 | `ModeTrigger` | ModeTrigger.tsx | Box, Text | Low |
| 50 | `SlashCommandTrigger` | SlashCommandTrigger.tsx | Box, Text | Low |
## State Management
| # | File | Ink Dependency | Migration Complexity | Notes |
|---|------|---------------|---------------------|-------|
| 51 | `store.ts` | None (Zustand) | None | Pure Zustand store; framework-agnostic |
| 52 | `uiStateStore.ts` | None (Zustand) | None | UI state; framework-agnostic |
## Testing Infrastructure
| # | Item | Current | OpenTUI Equivalent | Gap |
|---|------|---------|-------------------|-----|
| 53 | `ink-testing-library` | Used in 10 test files | N/A | Full gap -- need custom test renderer |
| 54 | Component snapshot tests | Ink render output | N/A | Need new snapshot format |
## Migration Complexity Summary
| Complexity | Count | Percentage |
|------------|-------|------------|
| None (framework-agnostic) | 12 | 22% |
| Low | 24 | 44% |
| Medium | 8 | 15% |
| High | 4 | 7% |
| Full gap (needs custom impl) | 6 | 11% |
| **Total tracked items** | **54** | **100%** |
## Critical Path Items
The following items are on the critical path for any migration and should be addressed first:
1. **ScrollArea** -- Uses `measureElement` and `DOMElement` which have no OpenTUI equivalent
2. **MultilineTextInput** -- Complex cursor/key handling tightly coupled to Ink's `useInput`
3. **AutocompleteInput** -- Keyboard-driven interaction depends on Ink's input model
4. **App (main shell)** -- Orchestrates all components; highest coupling to Ink lifecycle
5. **Testing infrastructure** -- `ink-testing-library` has no OpenTUI counterpart
6. **Select component** -- `@inkjs/ui` Select used in onboarding and main app