터미널 UI 만들기가 머리를 아프게 했다
Source: Dev.to
저는 대부분의 경력을 브라우저용 무언가를 만드는 데 보냈습니다.
무언가가 잘못 보이면 DevTools를 엽니다.
여백이 틀어지면 DOM을 검사합니다.
레이아웃이 엉망이면 CSS를 조정해서 더 이상 소리를 지르지 않게 합니다.
그래서 당연히 터미널 UI(TUI)를 만든다면… 비슷할 거라 생각했죠.
그렇지 않았습니다!
이 글은 TurboStream이라는 프로젝트를 진행하면서 공개적으로 기록하는 일환입니다 — 고속 WebSocket 스트림(블록체인, BGP, 금융 피드 등)을 토큰을 소모하거나 시스템을 다운시키지 않고 LLM에 연결해 주는 개발자 도구입니다.
예시:
WebSocket → Cache → Triggers → LLM → 짧은 인간이 읽을 수 있는 알림.백엔드는 비교적 쉬웠습니다.
터미널 UI가 저를 거의 죽음에 이르게 했습니다.
브라우저 세계에서 온 사람에게
웹 세계에서는
- Figma → HTML/CSS가 대부분 기계적인 작업
- 레이아웃은 시각적
- 디버깅은 인터랙티브
Bubble Tea 세계에서는
- 레이아웃은 수학
- 패딩은 분위기
- “왜 이 박스가 두 칸 더 넓어?”는 철학적인 질문
DOM 인스펙터가 없습니다.
“호버하면 경계 상자를 볼 수 있다”는 기능도 없습니다.
lipgloss.Style() 하나만 바꾸면 모든 것이 갑자기 움직입니다.
가장 어려운 화면: AI 분석
개념적으로는 간단합니다:
- LLM 컨텍스트 크기 표시
- 토큰 사용량 표시
- 생성 시간 표시
- 출력 텍스트 스트리밍
현실은:
- 내용 높이가 계속 변함
- 너비는 형제 패널과 정렬돼 있어야 함
- 스크롤 텍스트 + 테두리 + 패딩이 서로 충돌
결과적으로 다음과 같은 문제가 계속 발생했습니다:
- 텍스트가 잘려 보임
- 패널이 1 문자씩 넘쳐남
- 터미널 너비에 따라 테두리가 어긋남
한 크기에서는 괜찮아 보였지만, 크기를 바꾸면 완전히 깨졌습니다.
Bubble Tea를 사용해 본 사람이라면 이 느낌을 알 겁니다:
“이게 작동해야 하는데… 왜 안 될까?”
지금까지 배운 점
1. 픽셀 단위 사고를 멈춰라
터미널 레이아웃은 시각이 아니라 제약 조건에 관한 것입니다. 모든 것은 행 × 열입니다. 자유로운 공간은 없습니다.
2. 모든 것을 명시적으로 측정하라
너비/높이를 직접 계산하지 않으면 Bubble Tea가 기분 좋게 놀라게 할 것입니다.
3. 테두리는 거짓말한다
테두리와 패딩도 차지합니다. “한 칸 더”라는 현상은 언제나 당신의 실수입니다.
4. TUI 디버깅은 계측이 필요하다
다음과 같은 작업을 시작했습니다:
- 임시 배경 색상 추가
- 박스 안에 너비/높이 라벨 표시
- 레이아웃에 스트레스를 주는 가짜 내용 삽입
보기엔 못생겼지만 효과는 있었습니다.
앞으로 할 일
- 레이아웃 디버그 모드 만들기 – 컴포넌트 경계와 크기를 보여주는 토글 가능한 오버레이.
- 작은 레이아웃 테스트 하네스 작성 – 전체 앱 안에서 디버깅하지 말고 한 뷰씩 격리해서 테스트.
- 레이아웃 계약 표준화 – 각 패널이 “필요한 것”을 선언하게 하고, “스스로 알아내기”를 없앰.
- TUI UX ≠ Web UX임을 받아들이기 – 매체가 다르면 규칙도 다르다.