Skip to content

docs: add TUI blueprint for next-generation terminal interface#277

Merged
avoidwork merged 20 commits into
mainfrom
docs/update-tui2-doc
Jun 16, 2026
Merged

docs: add TUI blueprint for next-generation terminal interface#277
avoidwork merged 20 commits into
mainfrom
docs/update-tui2-doc

Conversation

@avoidwork

@avoidwork avoidwork commented Jun 16, 2026

Copy link
Copy Markdown
Owner

Description

Adds a comprehensive design blueprint for a planned TUI rewrite. The document describes a clean-slate terminal interface grounded in the existing implementation patterns (Ink + ink-scroll-view + structured logger) and inspired by the best patterns of the bitchx IRC client.

This is a design spec — not a description of the current TUI. It defines the philosophy, architecture, scrolling model, message display, runtime configuration, command parser, streaming pipeline, session lifecycle, and proposed improvements for a future implementation.

Key sections:

  • Philosophy — input is primary, output is a log, silence is the default
  • Architecture — component hierarchy, dependencies (Ink, ink-scroll-view, pino)
  • Scrolling & Viewport — ink-scroll-view API, auto-scroll behavior, keyboard navigation
  • Message Display — role-based styling, memoization, markdown rendering, tool call display
  • Runtime Configuration — bitchx-inspired toggle commands (/toggle, /format, /level)
  • Command Parser — dispatch table, skill execution, registered commands
  • Streaming Architecture — full data flow from user input through dispatchProvider to UI updates
  • Session & Persistence — session lifecycle, context token calculation, GC integration
  • Onboarding & Banner — first-run experience
  • Architectural Debt — honest assessment of current code (useState vs useReducer, inline streaming, flat file structure)
  • Proposed Implementation — TUIState interface, action types, command registry schema, streaming callback transformation

Type of Change

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactor (no functional changes)
  • Performance improvement
  • CI / build / tooling

Testing

N/A — documentation-only change.

Coverage

  • 100% line coverage maintained
    N/A — no code changes.

Checklist

  • npm run lint passes
  • Tests pass with 100% line coverage
  • No forbidden patterns used
  • Conventional Commit style applied

@avoidwork avoidwork self-assigned this Jun 16, 2026
@avoidwork avoidwork changed the title docs: update TUI2.md to reflect current implementation docs: remove unused panel components from TUI2 blueprint Jun 16, 2026
@avoidwork avoidwork changed the title docs: remove unused panel components from TUI2 blueprint docs: rewrite TUI2.md to reflect actual TUI implementation Jun 16, 2026
@avoidwork avoidwork changed the title docs: rewrite TUI2.md to reflect actual TUI implementation docs: add TUI blueprint for next-generation terminal interface Jun 16, 2026
@avoidwork avoidwork merged commit 275c740 into main Jun 16, 2026
2 checks passed
@avoidwork avoidwork deleted the docs/update-tui2-doc branch June 16, 2026 02:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant