tui-chat-design git:20261010.f3f9fa8A

Immutable. This exact content never changes and is served at /api/v1/blob/676b3fccabfd3d38.

---
name: tui-chat-design
description: "MASC TUI 채팅의 기본 대화 레이아웃, 상세 보기, 저널, 입력·진행 정보 배치 규칙. 채팅의 문구·폭·밀도·기호를 바꾸기 전에 읽는다."
---

# 대화를 먼저 읽는 채팅

정본은 `bin/masc_tui_message_layout.ml`, `bin/masc_tui_render_chat.ml`,
`bin/masc_tui_types.ml`이다. 코드와 다르면 이 문서도 함께 고친다.

## 기본 화면

- `Origin_bare`가 기본이다. 운영자 `›`, Keeper `●`, 외부 발신자 `◀`를 작은 여백에 둔다.
- 외부 발신자는 본문 위에 이름·출처를 남긴다. 운영자와 다른 발신자를 합치지 않는다.
- 본문 시작 열은 동일하다. 시계·넓은 역할 열·턴 레일·TOOLS 같은 종류 라벨은 기본으로 그리지 않는다.
- 도구 본문은 이미 호출 이름과 결과 기호를 갖는다. 별도 `■ TOOLS` 열을 반복하지 않는다.
- 읽기 폭은 최대 100 terminal cells다. 한국어·이모지·결합문자는 display width로 센다.
- 대화 사이의 한 줄 여백은 `Spacing`이다. 대화 맨 끝에는 여백을 세지 않으며, 큰 메시지를 잘라 보여줄 때는 첫 줄과 최신 본문을 보존한다.
- 사용자와 Keeper 본문은 원문이다. 요청 ID, TURN 번호, 처리 확인·시각 안내를 본문에 덧붙이지 않는다.
  시간은 여백·헤더에, 기술 식별자는 본문 뒤에 오는 명시적 진단에 둔다.
  그룹 키·인과 관계·검색과 스크롤의 원본 identity는 그대로 유지한다.
- 아직 처리되지 않은 입력은 `전송 대기`·`전송 중`·`처리 대기`·`전송 확인 중` 상태를 계속 표시한다. 접수를 턴 반영으로 바꾸어 말하지 않는다.
- 글꼴 크기·자간·행간은 터미널 에뮬레이터의 설정이다. 앱은 셀 배치와 여백을 제어한다.

## 보기 전환

| 키 | 순서 | 기본 |
|---|---|---|
| Ctrl-F | 대화 → inline metadata → origin heading → 대화 | `Origin_bare` |
| Ctrl-N | 숨김 → 요약 → 전체 → 숨김 | `Memory_hidden` |
| Ctrl-D | compact → results → full → compact | `Tools_compact` |
| Ctrl-R | folded → full → hidden → folded | `Reasoning_folded` |
| Ctrl-S | 턴 상세 접기/펼치기 | 기존 상태 유지 |

기본 설정을 알리는 `metadata:off`, `journal:off` 배지를 붙이지 않는다.
사용자가 연 상세 모드만 제목 옆에 표시한다. 모든 단축키는 도움말에서 찾는다.

## 상세 레이아웃

`Origin_inline`은 시계, 화자 열, 턴 레일을 표시한다. 같은 분의 시계와 같은 화자의 이름은 반복하지 않는다.
`Origin_row`는 화자와 시각을 별도 헤더에 표시한다. 소유 Keeper의 이름은 대화 제목과 중복하지 않는다.

상세 표식: 운영자 `▶`, 외부 발신자 `◀`, Keeper `●`, 상태 `○`, 로컬 명령 `›`,
저널 `◈`, 도구 `■`, 추론 `·`, 오류 `✗`. 스킬은 상태에 따라 `◇ ◆ △ ✗`를 쓴다.
색이 없어도 의미를 구별할 수 있어야 한다.

턴 레일은 `╭ │ ├ ╶ ╰`로 같은 턴의 인접 행을 연결한다. 외부 도착은 `───┤`,
저널은 `╌╌╌┤`로 구분한다. 원본 identity로 묶으며 표시 문자열로 그룹을 결정하지 않는다.

## 정보의 밝기

- 대화 본문은 전경색이다. 사용자가 보낸 글의 배경은 본문 영역 안에만 둔다.
- 도구·스킬·추론·저널은 dim이다. 강조나 링크가 닫힌 뒤에도 원래 밝기를 복원한다.
- 제목·시계·상태 크롬은 recede다. 진행줄 전체를 밝은 청록색과 대문자로 강조하지 않는다.
- 실패와 조치 요청은 보이게 남긴다. 내용을 보고 오류인지 추측하지 않고 타입을 사용한다.
- 실제 도구 결과는 Ctrl-D로 펼친다. 결과 수신 `↩`는 성공 판정이 아니다.

## 입력 주변

- 현재 대화의 진행 상태는 한 줄로 표시한다. 현재 호출·응답 상태만 남긴다.
  진행 타이머(요청·호출 경과 시간, 무응답 시간)와 누적 도구 목록·런타임 ID는 상세 레이아웃에 둔다.
- 모델 응답 종료 이벤트가 오면 응답 활동 표시를 끝낸다. Keeper 턴과 대기 중 도구는 계속 진행될 수 있다.
- 이어서 처리하기를 기다리는 요청은 진행줄을 그리지 않는다. 다음 실행이 시작되면 진행줄이 돌아온다.
- 같은 실행을 진행줄과 `기존 작업 처리 중`으로 중복 표시하지 않는다.
- 다른 Keeper의 실행과 `/interrupt <다른 이름>`은 입력 주변에 표시하지 않는다.
  Keepers 목록·Activity에서 관측하고 제어한다. 추적 중인 요청은 삭제하지 않는다.
- 전송 결과 미확인, 중단 실패, 관측 실패, 승인 질문은 기본 화면에서도 보인다.
  `Attention`은 기본 대화에서 상세를 접어도 남는다.
- 접힌 승인 기록이 있으면 진행줄의 `Ctrl-S:details`로 접근한다.
- 상태줄은 대화 대상의 health·mode·gate와 context를 표시한다. 상세 레이아웃에서는
  런타임·세부 사용량도 표시한다. roster 커서는 대화 대상을 바꾸지 않는다.
- 기본 footer는 전송·줄바꿈·중단/돌아가기·명령·도움말만 남긴다.
- 슬래시 메뉴와 녹음 안내는 관련 상태에서 footer를 대체한다.
- 메뉴가 실제로 표시될 때만 방향키·Tab·Enter·Esc를 가로챈다. 초안 보존과 전송 의미는 바꾸지 않는다.

## 검증

렌더러와 row budget은 같은 projection을 사용한다. 검색·스크롤·화면 너비·메모 캐시도
같은 origin mode와 실제 행을 사용해야 한다. 복사는 원본 응답에서 한다.

폭·기호·기본 모드를 바꾸면 기존 unit 기대값도 함께 갱신한다. 좁은 화면의 첫/마지막
본문, 외부 발신자 이름, 한글·이모지 줄바꿈, 전송 결과 미확인·중단 실패를 확인한다.

소스 projection 미리보기와 실제 TUI 실행 화면은 구분한다. 로컬 Dune 빌드와 CI 실행 시점은
constitution의 execution_protocol을 따른다.