# RAWP-CRS 1.0: Client Rendering Specification — Part 1 (§1–§3)

> **본 파일은 RAWP-CRS 1.0의 §1–§3을 포함합니다. §4–§7 및 부록은 Part 2를 참조하십시오.**

| 항목             | 값                 |
| ---------------- | ------------------ |
| 상태             | Stable             |
| 버전             | 1.0.2              |
| 상위 규격        | **RAWP 1.0.3**     |
| 데이터 평면 규격 | **RAWP-DPS 1.0.1** |

---

## 1. 개요 (Introduction)

RAWP-CRS 1.0은 RAWP 1.0 프로토콜 기반의 대화형 에이전트 인터페이스를 구현하는 클라이언트의 시각적 렌더링 및 UX 행동 규격이다. 본 규격은 RAWP 1.0의 제어 평면 이벤트와 RAWP-DPS 1.0의 데이터 평면 이벤트를 사용자에게 시각적으로 전달하는 방법을 정의하며, 대화 메시지의 레이아웃, 콘텐츠 렌더링, 상태 표시, 애니메이션 등 클라이언트 UI 구현에 필요한 모든 시각적 요구사항을 포괄한다.

본 규격은 프론트엔드 또는 시각적 피드백(웹 클라이언트, 데스크톱 앱, 터미널, 대시보드 등)을 구현하는 모든 시스템에 적용된다.

### 1.1. 요구사항 표기 규약 (Requirements Notation)

본 문서의 "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "OPTIONAL"은 RFC 2119를 따른다.

### 1.2. 용어 정의 (Terminology)

| 용어                   | 정의                                                                                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| User                   | 대화 인터페이스를 통해 에이전트와 상호작용하는 최종 사용자.                                                                                         |
| Agent                  | RAWP 세션 내에서 실행되는 작업 프로세스. 텍스트 응답, 도구 호출, 사고 과정 등 다양한 형식의 출력을 생성한다.                                        |
| System                 | 프로토콜 또는 클라이언트 자체가 생성하는 메타 정보 메시지. 세션 상태 안내, 에러 표시, 중지 알림 등을 포함한다.                                      |
| Turn                   | 사용자의 단일 프롬프트(`control.prompt.request`)에 대한 에이전트의 전체 응답 사이클. `session.turn.start`부터 `session.turn.end`까지의 논리적 단위. |
| 버블 (Bubble)          | 메시지를 감싸는 둥근 모서리의 배경색 컨테이너. 메신저 앱에서 발신/수신 메시지를 시각적으로 구분하는 관례적 UI 요소.                                 |
| 버블리스 (Bubble-less) | 버블 컨테이너 없이 콘텐츠 자체의 시각적 형태로 렌더링하는 방식.                                                                                     |
| Ephemeral              | 대화 이력에 영구적으로 기록되지 않는 일시적 UI 요소. 세션 재연결이나 이력 조회 시 표시되지 않는다.                                                  |

### 1.3. 적용 범위 (Scope)

본 규격은 다음을 정의한다:

- 대화 메시지의 행위자별(User, Agent, System) 시각적 정체성 및 레이아웃 규칙
- 마크다운 콘텐츠 렌더링 컴포넌트 명세
- 실시간 스트리밍 텍스트 렌더링 및 스크롤 제어
- 사고 과정(Thinking), 도구 호출 결과, Code Diff, 태스크 목록의 시각화 규칙
- 에이전트 상태 표시 및 전환 애니메이션
- 슬래시 명령어 자동 완성 UI 및 명령어 실행 버블 렌더링
- **파일 참조 입력(`@` 트리거 퍼지 검색) 및 인라인 토큰 렌더링** (§3.4)
- 시스템 메시지의 생략 금지 원칙 및 드롭다운 패턴
- 비스트리밍 환경(Discord, Slack 등) 적응 규칙
- **파일 브라우저 UI** — 세션 생성 전 작업 디렉토리 선택을 위한 트리 뷰 및 내비게이션 (§7)

본 규격은 다음을 정의하지 않는다:

- RAWP 제어 평면의 HTTP 엔드포인트 정의 (RAWP 1.0 참조)
- WSS 데이터 프레임의 Envelope 구조 및 이벤트 타입 (RAWP-DPS 1.0 참조)
- 클라이언트-서버 간 인증 및 토큰 교환 절차 (RAWP 1.0 §3 참조)

### 1.4. 호환성 및 파싱 규약 (Forward Compatibility)

- **알 수 없는 이벤트 무시**: 클라이언트의 렌더러는 본 규격에 정의되지 않은 `agent.*`, `tool.*`, `session.*` 이벤트 타입을 수신하더라도 UI를 중단하지 않고 조용히 무시해야 한다 (MUST).
- **알 수 없는 마크다운 구문 폴백**: 렌더러가 지원하지 않는 마크다운 확장 구문을 만나면 원문 텍스트를 그대로 표시해야 한다 (MUST). 렌더링 에러를 발생시키거나 해당 텍스트를 숨겨서는 안 된다.
- **알 수 없는 `output_type` 폴백**: `tool.invoke.result`의 `output_type`이 본 규격에 정의되지 않은 값인 경우, 모노스페이스 텍스트 블록으로 폴백 렌더링해야 한다 (MUST).

---

## 2. 메시지 아키텍처 및 레이아웃 원칙 (Message Architecture)

### 2.1. 메시지 행위자 정의 및 설계 목표

대화 인터페이스는 다음 세 가지 행위자의 메시지로 구성된다:

| 행위자     | 정의                                                                                                   | 설계 목표                                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User**   | 사용자가 입력한 자연어 텍스트 또는 슬래시 명령어                                                       | 사용자가 **1:1 채팅을 하고 있다는 자연스러운 대화 경험**을 제공한다. 메시지 형태는 친숙한 메신저 앱의 발신 메시지와 동일한 시각적 언어를 따른다.                |
| **Agent**  | 에이전트가 생성한 텍스트 응답, 사고 과정, 도구 호출 결과, 코드 diff, 태스크 목록 등 다양한 형식의 출력 | **다양한 형식의 콘텐츠를 복잡함 없이** 제시한다. 텍스트, 코드, diff, 파일 트리, 태스크 목록 등 이질적인 콘텐츠가 하나의 흐름에서 자연스럽게 읽히도록 한다.      |
| **System** | 프로토콜 또는 클라이언트가 생성한 상태 안내(중지 알림, 에러 표시, 세션 이벤트 등)                      | 대화의 맥락과 상태를 **빠짐없이, 직관적으로** 전달한다. 시스템 메시지는 보조 정보이므로 대화 흐름을 방해하지 않되, 모든 내용을 사용자에게 반드시 전달해야 한다. |

### 2.2. 레이아웃 정렬 규칙

각 행위자의 메시지는 수평 정렬(alignment)로 즉시 구분 가능해야 한다 (MUST):

| 행위자     | 정렬          | 버블                        | 근거                                                                                                                                                                                                                                                                                     |
| ---------- | ------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User**   | **우측 정렬** | 채팅 버블 사용 (MUST)       | 메신저 앱의 관례를 따라 발신 메시지로 인지되도록 한다. 배경색이 있는 둥근 모서리의 버블로 감싸 "내가 보낸 메시지"임을 즉각적으로 전달한다.                                                                                                                                               |
| **Agent**  | **좌측 정렬** | 채팅 버블 미사용 (MUST NOT) | 에이전트는 텍스트, 코드 블록, diff 뷰어, 태스크 목록, 파일 트리 등 다양한 형식의 콘텐츠를 출력한다. 이들을 채팅 버블로 감싸면 콘텐츠 유형별 시각적 구분이 무너지고 중첩된 컨테이너로 인해 가시성이 저하된다. 에이전트 출력은 버블 없이 대화 영역의 전체 가용 너비를 활용하여 렌더링한다. |
| **System** | **중앙 정렬** | 채팅 버블 미사용 (MUST NOT) | 시스템 메시지는 대화의 두 참여자(User, Agent) 사이의 메타 정보이므로, 좌우 어느 쪽에도 귀속되지 않는 중립적 위치에 배치한다. 배경색 없이 연한 색상의 텍스트로 표시하여 시각적 비중을 최소화한다.                                                                                         |

### 2.3. 상호작용 및 애니메이션 기본 원칙

**불필요한 애니메이션 제한**: 실제 클릭 등 인터랙션이 없는 정적 요소(단순 텍스트 스트림 출력부 등)에는 불필요하게 호버(Hover) 애니메이션을 적용하지 않아야 한다 (MUST NOT).

**방해 없는 애니메이션 효과**: 버튼(상호작용 요청의 옵션 등)과 같이 실제 인터랙션이 존재하는 곳은, 반드시 사용자의 작업 흐름이나 시선을 방해하지 않는 선에서 부드러운 애니메이션 효과를 제공해야 한다 (MUST).

### 2.4. 타임스탬프 표시 규칙 (Timestamp Display)

사용자는 대화 이력에서 각 메시지가 언제 발생했는지를 확인할 수 있어야 한다 (MUST). 그러나 모든 메시지 블록에 개별 타임스탬프를 표시하면 대화 흐름이 시각적으로 복잡해지고, 특히 에이전트의 다중 출력 블록(텍스트 → 도구 호출 → 텍스트 등)이 연속되는 구간에서 타임스탬프가 콘텐츠보다 많아지는 현상이 발생한다. 따라서 타임스탬프는 **Turn 경계 및 시스템 메시지 시점**에만 표시하여, 시간 정보의 유용성과 대화 인터페이스의 간결함을 동시에 확보한다.

**표시 시점 규칙**: 타임스탬프는 다음의 경우에만 대화 이력에 표시해야 한다 (MUST):

| 표시 시점                             | 위치                                 | 표시하는 시각                      | 근거                                                                                                             |
| ------------------------------------- | ------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **유저 메시지 발송 시** (Turn 시작)   | 유저 메시지 버블의 하단 또는 상단    | `control.prompt.request` 발송 시각 | 사용자가 언제 질문/명령을 보냈는지를 기록한다. 이것이 Turn의 시작점이다.                                         |
| **에이전트 Turn 완료 시** (Turn 종료) | 에이전트의 마지막 출력 블록 하단     | `session.turn.end` 수신 시각       | 에이전트가 언제 응답을 완료했는지를 기록한다. 유저 메시지 타임스탬프와 비교하면 응답 소요 시간을 파악할 수 있다. |
| **시스템 메시지 발생 시**             | 시스템 메시지 본문 내 또는 인접 위치 | 해당 이벤트 발생 시각              | 중지, 에러, 재연결 등 시스템 이벤트의 발생 시점을 기록한다.                                                      |

**에이전트 중간 블록에는 표시하지 않음**: 단일 Turn 내에서 에이전트가 생성하는 개별 출력 블록(텍스트 스트리밍, 사고 과정, 도구 호출, 도구 결과 등)에는 개별 타임스탬프를 표시하지 않는다 (MUST NOT). 에이전트의 Turn은 하나의 연속적인 응답 흐름이며, 중간 블록마다 시각을 표시하면 대화가 로그 뷰어처럼 보여 가독성이 저해된다. Turn 시작(유저 메시지)과 Turn 종료(에이전트 마지막 출력) 두 지점의 타임스탬프만으로 응답의 시간 맥락을 충분히 파악할 수 있다.

**기본 가시성**: 타임스탬프는 기본적으로 항상 표시(always visible)하는 것이 아니라, **사용자가 원할 때 확인할 수 있는 형태**로 제공할 것을 권장한다 (SHOULD). 구체적으로 다음 중 하나의 방식을 적용한다:

- **호버/탭 노출 (권장)**: 타임스탬프를 기본적으로 숨기고, 해당 메시지 영역에 마우스를 호버하거나 모바일에서 탭하면 타임스탬프가 나타나는 방식. 대화 흐름이 가장 깔끔하게 유지된다.
- **인라인 연한 표시**: Turn 경계 시점에 연한 색상(muted color)과 작은 폰트 크기로 타임스탬프를 상시 표시하는 방식. 시각적 비중을 최소화하되 스크롤만으로 시간을 확인할 수 있다.

**날짜 구분선 (Date Separator)**: 대화가 날짜를 넘겨서 이어지는 경우, 날짜가 변경되는 지점에 중앙 정렬 날짜 구분선(예: `── 2025년 3월 11일 ──`)을 삽입하여 시간 맥락의 단절을 명확히 해야 한다 (SHOULD). 이 구분선은 시스템 메시지와 동일한 중앙 정렬, 연한 색상 스타일을 따른다.

**시각 포맷**: 타임스탬프는 사용자의 로케일과 시간대에 맞춘 현지 시각으로 표시해야 한다 (MUST). 당일 메시지는 시:분(예: `14:32`), 이전 날짜의 메시지는 날짜+시:분(예: `3/10 14:32` 또는 로케일에 따른 포맷)으로 표시할 것을 권장한다 (SHOULD).

### 2.5. 키보드 인터랙션 (Keyboard Interaction)

대화 인터페이스에서 사용자가 키보드로 수행할 수 있는 공통 인터랙션을 정의한다. 팝업(슬래시 명령어 §3.2, 파일 참조 §3.4) 내부의 키보드 내비게이션은 각 섹션에서 별도 정의한다.

#### 2.5.1. 메시지 전송

| 키            | 동작        | 조건                                                   |
| ------------- | ----------- | ------------------------------------------------------ |
| `Enter`       | 메시지 전송 | 입력창에 텍스트가 존재하고, 팝업이 활성 상태가 아닐 때 |
| `Shift+Enter` | 줄바꿈 삽입 | 항상. 메시지를 전송하지 않는다.                        |

`Enter`로 전송 시 입력창의 내용이 비어 있으면(공백만 포함) 전송하지 않아야 한다 (MUST NOT).

#### 2.5.2. 에이전트 응답 취소 (`Escape`)

에이전트가 응답 중(Turn 진행 중)일 때 `Escape` 키를 누르면, 클라이언트는 `control.prompt.cancel`(RAWP-DPS 1.0.1 §6.1.2)을 발송하여 현재 Turn을 취소해야 한다 (MUST).

**취소 가능 상태**: 다음 에이전트 상태에서 `Escape`가 취소를 트리거해야 한다 (MUST):

| 에이전트 상태                                   | `Escape` 동작                            |
| ----------------------------------------------- | ---------------------------------------- |
| `thinking` (사고 중)                            | Turn 취소 (`control.prompt.cancel` 발송) |
| `tool_calling` (도구 실행 중)                   | Turn 취소                                |
| 텍스트 스트리밍 중 (`agent.text.delta` 수신 중) | Turn 취소                                |

**취소 불가 상태**: 다음 상태에서는 `Escape`가 취소를 트리거하지 않는다:

| 상태                             | `Escape` 동작                          |
| -------------------------------- | -------------------------------------- |
| `idle` (에이전트 유휴)           | 동작 없음                              |
| `awaiting_input` (상호작용 대기) | 상호작용 UI 닫기 (§2.5.3 참조)         |
| 팝업 활성 상태 (§3.2, §3.4)      | 팝업 닫기 (각 섹션의 키보드 규칙 적용) |

**취소 후 동작**: §5.2의 사용자 중지 피드백 규칙을 따른다.

#### 2.5.3. 상호작용 응답 키보드 조작

`agent.interaction.request`(RAWP-DPS 1.0.1 §4.3.1)에 의해 표시된 상호작용 UI에 대한 키보드 조작:

| `interaction_type` | 키보드 조작                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `YN`               | `Y` 또는 `Enter` → 승인, `N` 또는 `Escape` → 거부                    |
| `PERMISSION`       | `Enter` → 승인, `Escape` → 거부                                      |
| `SELECT`           | `↑`/`↓` → 항목 이동, `Enter` → 선택, `Escape` → 취소                 |
| `MULTI_SELECT`     | `↑`/`↓` → 항목 이동, `Space` → 토글, `Enter` → 확정, `Escape` → 취소 |
| `TEXT_INPUT`       | `Enter` → 제출, `Escape` → 취소                                      |

`Escape`로 상호작용을 취소하면 `default_value`가 정의된 경우 해당 값으로 자동 응답하고, 정의되지 않은 경우 타임아웃과 동일하게 처리해야 한다 (MUST).

#### 2.5.4. 대화 이력 내비게이션

| 키                      | 동작                                                                                                           |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `↑` / `↓`               | 입력창이 비어 있을 때 이전/다음 유저 메시지를 입력창에 불러오기 (MAY). 셸의 히스토리 내비게이션과 동일한 패턴. |
| `Page Up` / `Page Down` | 대화 이력 영역을 한 페이지씩 스크롤 (SHOULD)                                                                   |
| `Home`                  | 대화 이력의 최상단으로 스크롤 (MAY)                                                                            |
| `End`                   | 대화 이력의 최하단(최신 메시지)으로 스크롤 (MAY)                                                               |

#### 2.5.5. 입력창 포커스

대화 인터페이스가 활성 상태일 때, 팝업이나 상호작용 UI가 표시되지 않은 상태에서 사용자가 키보드 입력을 시작하면, 입력창에 자동으로 포커스가 이동해야 한다 (SHOULD). 이는 사용자가 별도의 클릭 없이 바로 타이핑을 시작할 수 있도록 하기 위함이다.

### 2.6. 대화 이력 점진적 로딩 (Conversation History Lazy Loading)

기존 대화를 다시 열 때, 전체 Turn을 한 번에 렌더링하면 Turn 수가 많은 대화에서 심각한 성능 저하가 발생한다. 이를 방지하기 위해 클라이언트는 **최신 N개 Turn만 초기 로딩**하고, 나머지는 사용자의 명시적 요청에 의해 추가 로딩하는 점진적 로딩(Lazy Loading) 방식을 적용해야 한다 (MUST).

#### 2.6.1. 초기 로딩 규칙

대화를 열 때 클라이언트는 가장 최근의 **N개 Turn**만 렌더링해야 한다 (MUST). 여기서 1 Turn은 사용자 메시지 1회와 그에 대한 에이전트의 전체 응답(텍스트, 도구 호출, 사고 과정 등)을 포함하는 논리적 단위이다.

**기본값**: N의 기본값은 **10**으로 한다 (SHOULD).

**설정 가능성**: N 값은 사용자가 클라이언트 설정에서 변경할 수 있어야 한다 (MUST). 최솟값은 1, 최댓값은 클라이언트 구현에 따르되 100 이하로 제한한다 (SHOULD).

#### 2.6.2. 이전 Turn 로딩 UI

초기 로딩 범위 밖의 이전 Turn이 존재하는 경우, 대화 이력의 최상단에 **이전 Turn 로딩 트리거**를 표시해야 한다 (MUST).

**트리거 형태**: 다음 중 하나의 방식을 사용한다:

- **명시적 버튼**: "이전 대화 불러오기" 또는 유사한 라벨의 버튼을 대화 이력 최상단에 배치한다. 클릭 시 이전 N개 Turn을 추가 로딩한다.
- **스크롤 기반 자동 로딩**: 사용자가 대화 이력을 최상단까지 스크롤하면 자동으로 이전 N개 Turn을 로딩한다. 로딩 중에는 스피너 또는 스켈레톤 UI를 표시해야 한다 (MUST).

두 방식을 함께 제공할 수 있다 (MAY).

#### 2.6.3. 로딩 동작 규칙

- **추가 로딩 단위**: 한 번의 로딩 요청에서 N개 Turn 단위로 추가 로딩한다 (SHOULD). 남은 Turn이 N개 미만이면 나머지를 모두 로딩한다.
- **스크롤 위치 유지**: 이전 Turn이 로딩되어 상단에 삽입될 때, 현재 사용자가 보고 있는 콘텐츠의 스크롤 위치가 변경되어서는 안 된다 (MUST). 새 콘텐츠는 현재 뷰포트 위쪽에 삽입되고, 스크롤 오프셋을 보정하여 사용자의 시각적 위치를 유지한다.
- **전체 로딩 완료 표시**: 모든 Turn이 로딩되면 로딩 트리거를 제거하거나 비활성화하여 더 이상 로딩할 내용이 없음을 표시해야 한다 (MUST).
- **로딩 실패**: 이전 Turn 로딩이 실패한 경우, 에러 메시지와 함께 재시도 옵션을 제공해야 한다 (MUST).

---

## 3. 유저 메시지 (User Message)

유저 메시지의 설계 목표는 **사용자가 1:1 채팅을 하고 있다는 자연스러운 경험**을 제공하는 것이다. 시각적 형태는 친숙한 메신저 앱의 발신 메시지 관례를 따른다.

### 3.1. 버블 스타일 및 레이아웃

**우측 정렬 채팅 버블**: 유저 메시지는 대화 영역의 우측에 배경색이 있는 둥근 모서리(border-radius) 버블로 렌더링해야 한다 (MUST). 버블의 최대 너비는 대화 영역 전체 폭의 70~80%로 제한하여 좌측에 여백을 확보하고, 에이전트 메시지와의 시각적 대칭을 유지한다 (SHOULD).

**텍스트 메시지**: `control.prompt.request`에서 `input_type: "text"`인 메시지는 입력된 텍스트를 버블 내에 마크다운 서식을 적용하여 표시한다.

**유저 메시지 서식 인식**: 유저 메시지 버블 내에서 다음의 텍스트 마크다운 서식을 인식하고 렌더링해야 한다 (MUST):

| 서식            | 구문                             | 렌더링                               |
| --------------- | -------------------------------- | ------------------------------------ |
| **볼드**        | `**text**` 또는 `__text__`       | `font-weight: bold` 적용             |
| **이텔릭**      | `*text*` 또는 `_text_`           | `font-style: italic` 적용            |
| **볼드+이텔릭** | `***text***`                     | 볼드와 이텔릭 동시 적용              |
| **취소선**      | `~~text~~`                       | `text-decoration: line-through` 적용 |
| **인라인 코드** | `` `code` ``                     | 모노스페이스 폰트, 배경색 구분       |
| **줄바꿈**      | Enter 키 (`\n`) 또는 Shift+Enter | `<br>` 줄바꿈 표시                   |
| **링크**        | `[text](url)`                    | 클릭 가능한 하이퍼링크               |
| **자동 링크**   | URL 패턴 자동 감지               | 클릭 가능한 링크로 변환              |
| **불릿 목록**   | `- item` 또는 `* item`           | `<ul><li>` 목록 렌더링               |
| **숫자 목록**   | `1. item`                        | `<ol><li>` 번호 목록 렌더링          |

다음 서식은 유저 메시지에서 렌더링하지 않는다 (MUST NOT): 헤더(`#`), 펜스 코드 블록(` ``` `), 테이블(`| |`), 이미지(`![]()`), 인용구(`>`), 수평선(`---`), 수식(`$`). 유저 메시지는 대화형 텍스트이므로 복잡한 블록 레벨 구조는 적용하지 않되, 목록은 대화에서 자주 사용되므로 예외적으로 허용한다.

**입력창에서의 서식 입력**: 입력창은 사용자가 마크다운 구문을 직접 타이핑하는 플레인 텍스트 모드를 기본으로 한다 (MUST). 서식이 적용된 리치 텍스트 미리보기는 입력 중에 표시하지 않는다 (MUST NOT). 마크다운 구문은 전송 후 대화 이력에 표시될 때 렌더링된다.

**파일 참조 토큰 렌더링**: 전송 완료된 메시지가 대화 이력에 표시될 때, `prompt_text` 내 파일 참조 토큰이 포함되어 있는 경우 §3.4.5의 토큰 시각 사양(배경색, 둥근 모서리, 아이콘)과 동일한 스타일로 인라인 렌더링해야 한다 (MUST). 대화 이력 내 토큰은 읽기 전용이며, 클릭 시 해당 파일의 경로를 클립보드에 복사하거나 파일 뷰어를 여는 동작을 지원할 수 있다 (MAY).

**토큰 검증 규칙**: 대화 이력에서 유저 메시지를 렌더링할 때, `prompt_text` 내 토큰 패턴이 `file_references`에 유효하게 매핑되는 경우에만 시각적 토큰으로 렌더링한다 (MUST). 매핑되지 않는 토큰 패턴은 RAWP-DPS §16.2.2에 따라 언이스케이프 후 리터럴 텍스트로 표시하여, 위조된 토큰이 시각적으로 정당한 파일 참조처럼 보이는 것을 방지한다 (MUST).

§3.3(슬래시 명령어 실행 버블)의 "중첩 컨테이너 금지" 원칙을 동일하게 따른다. 토큰의 배경색이 버블 배경색과 충분히 구분되어야 하며 (MUST), 버블 내에 별도의 컨테이너(카드, 박스 등)를 추가하지 않는다.

### 3.2. 슬래시 명령어 입력 (Slash Command Input)

사용자가 입력창에 `/` 문자를 타이핑하면, 클라이언트는 `agent.commands.publish`(RAWP-DPS §12.1.1)를 통해 수신한 명령어 목록을 기반으로 자동 완성 UI를 즉시 표시해야 한다 (MUST).

**트리거 조건**: 입력창에서 커서가 행 시작 위치이거나 공백 직후에 `/` 문자가 입력되면, 자동 완성 팝업을 활성화해야 한다 (MUST). 문장 중간의 슬래시(예: `https://...`, `path/to/file`)에서는 활성화해서는 안 된다 (MUST NOT).

**팝업 위치 및 반응 속도**: 자동 완성 팝업은 입력창 바로 위(또는 아래, 뷰포트 공간에 따라 동적 결정)에 오버레이로 표시해야 한다 (MUST). 기존 대화 이력이나 응답 영역을 가려서는 안 되며 (SHOULD NOT), 입력 커서와의 시각적 연결성을 유지해야 한다. `/` 입력 후 팝업 표시까지의 지연은 100ms를 초과해서는 안 된다 (SHOULD NOT). `agent.commands.publish`로 수신한 명령어 목록은 세션 시작 시 로컬에 캐싱하여 네트워크 지연 없이 즉시 표시할 수 있어야 한다 (MUST).

**목록 구성**: 각 명령어 항목은 다음 요소를 포함하여 표시해야 한다 (MUST):

- **명령어 이름**: `/{name}` 형식으로 좌측에 고정 표시. 모노스페이스 폰트 적용 (SHOULD).
- **설명(description)**: 명령어 이름 우측 또는 하단에 간략한 설명 텍스트를 표시.
- **카테고리 표지**: `category` 필드가 존재하면, 색상 뱃지 또는 아이콘으로 시각적 그룹핑을 제공할 수 있다 (MAY). 예: `session` 카테고리는 🔄, `display`는 👁, `config`는 ⚙ 등.

**항목 간 시각적 분리 (Item Separation)**: 명령어 목록의 각 항목은 인접 항목과 명확히 구분되어야 한다 (MUST). 다음 방법 중 하나 이상을 적용한다:

- **충분한 내부 패딩**: 각 항목에 상하 패딩(예: 8~12px)을 부여하여 텍스트가 경계에 밀착되지 않도록 한다 (MUST). 항목 간 여백 없이 패딩만으로 구분이 충분하면 구분선은 생략할 수 있다.
- **구분선 또는 배경 교차**: 항목 사이에 얇은 구분선(1px, 저대비 색상)을 삽입하거나, 짝수/홀수 항목에 미세하게 다른 배경색(zebra striping)을 적용할 수 있다 (MAY).
- **명령어명-설명 레이아웃**: 명령어 이름과 설명 텍스트는 시각적 위계가 명확해야 한다 (MUST). 명령어명은 볼드 또는 기본 텍스트 색상, 설명은 연한 색상(muted color)과 작은 폰트 크기로 차등을 둔다.

**실시간 필터링**: 사용자가 `/` 이후 추가 문자를 타이핑하면(예: `/com`), 입력된 접두사와 일치하는 명령어만 팝업에 필터링하여 표시해야 한다 (MUST). 필터링은 명령어 이름(`name`)에 대한 접두사 매칭을 기본으로 하되, 퍼지 매칭(fuzzy match)을 추가 지원할 수 있다 (MAY). 필터링 결과가 갱신될 때, 포커스는 목록의 첫 번째 항목으로 리셋되어야 한다 (SHOULD). 입력된 접두사에 매칭되는 명령어가 없으면, 팝업에 "일치하는 명령어가 없습니다" 등의 안내 메시지를 표시해야 한다 (SHOULD). 팝업을 즉시 닫아서는 안 된다 (MUST NOT) — 사용자가 타이핑을 수정할 기회를 보장해야 한다.

**정렬 순서**: 명령어 목록은 다음 우선순위로 정렬할 것을 권장한다 (SHOULD): 사용 빈도 높은 순 → `category`별 그룹핑 → 알파벳순.

**포커스 하이라이트 (Focus Highlight)**: 키보드 또는 마우스로 현재 선택 대상이 되는 항목은, 다른 항목과 즉각적으로 구별되는 하이라이트를 적용해야 한다 (MUST). 하이라이트는 해당 항목의 **전체 행 영역**(좌측 끝~우측 끝)에 배경색을 적용하는 방식이어야 하며, 텍스트 일부만 강조하거나 밑줄만 추가하는 방식은 불충분하다. 하이라이트 배경색은 비선택 항목의 배경과 충분한 명도 차이를 가져야 한다 (MUST). 동시에 두 개 이상의 항목이 하이라이트되어서는 안 된다 (MUST NOT). 키보드 포커스와 마우스 호버가 서로 다른 항목을 가리킬 경우, 마우스 호버가 우선한다 (SHOULD).

**키보드 내비게이션**: 팝업이 활성화된 상태에서 다음 키보드 조작을 지원해야 한다 (MUST):

| 키                 | 동작                                                          |
| ------------------ | ------------------------------------------------------------- |
| `↑` / `↓`          | 목록 항목 간 포커스 이동. 목록 끝에서 순환 (SHOULD).          |
| `Enter` 또는 `Tab` | 포커스된 항목 선택 및 입력창에 반영                           |
| `Esc`              | 팝업 닫기, 입력 텍스트는 유지                                 |
| 계속 타이핑        | 실시간 필터링 갱신. 포커스는 필터링된 목록의 첫 항목으로 리셋 |

팝업 내 목록이 스크롤 가능한 길이일 때, 키보드 포커스가 현재 보이는 영역 밖으로 이동하면 포커스된 항목이 뷰포트 내에 보이도록 팝업 내부를 자동 스크롤해야 한다 (MUST). 마우스 클릭 또는 터치 탭으로도 선택할 수 있어야 하며 (MUST), 마우스 호버 시 해당 항목에 포커스 하이라이트와 동일한 배경색을 즉시 적용해야 한다 (MUST).

**선택 후 동작**: 명령어가 선택되면, 입력창의 텍스트를 `/{선택된_name}` (후행 공백 포함)으로 교체하고 팝업을 닫아야 한다 (MUST). `parameters` 배열에 `required: true`인 항목이 있으면, 선택 후 입력창에 해당 파라미터의 힌트를 회색 플레이스홀더로 표시하여 사용자가 추가 입력이 필요함을 인지하도록 해야 한다 (SHOULD).

**명령어 목록 갱신**: `agent.commands.publish` 이벤트가 세션 중 재수신되면, 클라이언트는 로컬 캐시를 즉시 갱신해야 한다 (MUST). 팝업이 열려 있는 상태에서 갱신이 발생하면, 현재 필터 조건을 유지한 채 목록을 교체해야 한다 (SHOULD). 갱신 과정에서 사용자의 포커스 위치나 입력 상태가 초기화되어서는 안 된다 (MUST NOT).

### 3.3. 슬래시 명령어 실행 버블 렌더링 (Command Bubble)

사용자가 슬래시 명령어를 실행하면, 대화 이력에 표시되는 채팅 버블은 일반 텍스트 메시지와 명확히 구별되는 전용 렌더링을 적용해야 한다 (MUST).

**슬래시 접두사 제거**: 채팅 버블에 명령어를 표시할 때 선행 `/` 문자는 제거해야 한다 (MUST). 예: 사용자가 `/compact focus on auth module`을 입력했다면, 버블에는 `compact focus on auth module`로 표시한다.

**중첩 컨테이너 금지 (No Nested Containers)**: 명령어 버블은 **버블 자체가 뱃지(badge) 역할**을 겸해야 하며, 버블 내부에 별도의 뱃지, 칩(chip), 또는 박스 요소를 중첩해서는 안 된다 (MUST NOT).

**명령어명 강조**: 버블 내에서 명령어명(첫 번째 토큰)은 중첩 컨테이너 없이 **인라인 텍스트 스타일**로 구분해야 한다 (MUST). 명령어명은 **볼드(font-weight: bold)** 와 일반 텍스트 대비 약간 다른 색상을 적용하여 시각적으로 구분한다. 파라미터가 존재하면 일반 두께의 텍스트로 이어서 표시한다. 예: **compact** focus on auth module.

**버블 스타일 차별화**: 명령어 버블은 그 자체로 일반 메시지와 즉시 구분되어야 한다 (MUST). 다음 조합을 적용한다:

- **인라인 크기**: 내용 길이에 맞춰 최소 폭으로 렌더링 (SHOULD). 일반 메시지처럼 넓은 영역을 차지하지 않고, 컴팩트한 인라인 요소로 표시한다.
- **배경색 차별화**: 일반 메시지 버블과 명확히 다른 배경색을 적용한다.
- **모노스페이스 폰트**: 버블 전체에 모노스페이스 폰트를 적용 (SHOULD).
- **아이콘 접두**: 명령어명 좌측에 소형 아이콘(예: `⚡`, `▶`)을 표시할 수 있다 (MAY).

**실행 결과 연결**: 명령어 버블 직후에 에이전트의 응답이 이어지는 경우, 명령어 버블과 결과 영역 사이의 시각적 연결성을 표현하여 인과 관계를 명확히 해야 한다 (SHOULD).

**프로토콜 연계**: `control.prompt.request`에서 `input_type: "slash_command"`(RAWP-DPS §6.1.1)로 설정된 프레임은 본 섹션의 Command Bubble 스타일을 적용해야 한다 (MUST). `input_type: "text"` 또는 기타 값인 경우에는 §3.1의 일반 메시지 버블 스타일을 유지한다.

### 3.4. 파일 참조 입력 (File Reference Input)

사용자가 `@` 문자를 입력하여 로컬 파일을 인라인으로 참조하는 기능의 렌더링 및 UX 규격이다. 슬래시 명령어(§3.2)와 유사한 자동 완성 팝업 UI 패턴을 따르되, 파일 퍼지 검색의 특성에 맞게 확장한다.

#### 3.4.1. 트리거 조건

**활성화 조건**: 입력창에서 커서가 행 시작 위치이거나 공백 직후에 `@` 문자가 입력되면, 파일 검색 팝업을 활성화해야 한다 (MUST).

**비활성 조건**: 다음의 경우에는 팝업을 활성화해서는 안 된다 (MUST NOT):

- `@` 직전 문자가 영숫자(`a-z`, `A-Z`, `0-9`)이거나 `.`인 경우. 이는 이메일 주소 패턴(`user@domain`), URL 내 `@`, 또는 단어 중간의 `@`를 필터링한다.
- 슬래시 명령어 팝업(§3.2)이 이미 활성 상태인 경우. §3.4.7 참조.

#### 3.4.2. 팝업 UI 구성

**위치 및 반응 속도**: §3.2(슬래시 명령어)의 팝업 위치 규칙과 동일하게 입력창 바로 위에 오버레이로 표시한다 (MUST). 기존 대화 이력이나 응답 영역을 가려서는 안 되며 (SHOULD NOT), 입력 커서와의 시각적 연결성을 유지해야 한다. `@` 입력 후 팝업 표시까지의 지연은 100ms를 초과해서는 안 된다 (SHOULD NOT).

**초기 상태**: `@` 입력 직후(쿼리 문자열이 비어 있는 시점), 팝업은 다음 중 하나를 표시해야 한다 (MUST):

- 최근 수정된 파일 목록 (클라이언트가 DPS `control.file.search`의 빈 쿼리 응답으로 제공)
- "파일명을 입력하세요" 안내 메시지 + 로딩 인디케이터

**후보 항목 구성**: 각 파일 후보 항목은 다음 요소를 포함하여 표시해야 한다 (MUST):

- **파일 아이콘 (MAY)**: 확장자별 아이콘 또는 이모지를 좌측에 표시한다. 아이콘 매핑 예시:

  | 확장자 그룹                  | 아이콘/이모지 예시    |
  | ---------------------------- | --------------------- |
  | `.ts`, `.tsx`, `.js`, `.jsx` | 📜 또는 JS/TS 아이콘  |
  | `.py`                        | 🐍 또는 Python 아이콘 |
  | `.json`, `.yaml`, `.toml`    | ⚙ 또는 설정 아이콘    |
  | `.md`, `.txt`                | 📄                    |
  | `.css`, `.scss`              | 🎨                    |
  | 기타 / 알 수 없음            | 📁 (기본 파일 아이콘) |

  아이콘 매핑은 클라이언트 구현에 위임하며, 본 규격은 강제하지 않는다 (MAY). 단, 아이콘을 제공하는 경우 모든 후보에 일관되게 적용해야 한다 (MUST).

- **파일명**: 볼드 또는 기본 텍스트 색상으로 좌측에 표시. DPS `session.file.candidates`의 `match_ranges`가 제공된 경우, 매칭된 문자 범위를 강조 배경색 또는 볼드로 하이라이팅해야 한다 (MUST).
- **디렉토리 경로**: 파일명 우측 또는 하단에 연한 색상(muted color)으로 표시. 긴 경로는 선행 부분을 말줄임(`…/deep/path/to/`)으로 축약할 수 있다 (MAY).

**항목 간 시각적 분리**: §3.2의 항목 간 시각적 분리 규칙과 동일하게, 충분한 내부 패딩(8~12px)과 선택적 구분선을 적용한다 (MUST).

#### 3.4.3. 퍼지 검색 동작

**실시간 검색 요청**: 사용자가 `@` 이후 추가 문자를 타이핑하면, 클라이언트는 DPS `control.file.search` 이벤트 발송을 위해 입력을 마스터에 전달해야 한다 (MUST). 키스트로크마다 즉시 전송하지 않고, 150~300ms 디바운싱을 적용하여 네트워크 부하를 제어해야 한다 (SHOULD).

**로딩 상태**: 검색 요청 발송 후 `session.file.candidates` 수신 전까지, 팝업 하단에 로딩 인디케이터(스피너 또는 프로그레스 바)를 표시해야 한다 (MUST). 이전 결과가 존재하면 이전 결과를 유지한 채 로딩 인디케이터를 병행 표시하여, 화면이 빈 상태로 깜빡이는 것을 방지한다 (SHOULD).

**결과 순서 보장**: 클라이언트는 `session.file.candidates`의 `query_id`를 확인하여, 현재 활성 쿼리의 결과만 팝업에 반영해야 한다 (MUST). `query_id`가 현재 활성 쿼리와 불일치하는 응답(이전 쿼리의 지연 도착)은 무시한다 (MUST).

**빈 결과 처리**: 매칭 결과가 없으면 "일치하는 파일이 없습니다" 안내 메시지를 표시해야 한다 (SHOULD). 팝업을 즉시 닫아서는 안 된다 (MUST NOT) — 사용자가 타이핑을 수정할 기회를 보장해야 한다.

#### 3.4.4. 키보드 및 포인터 내비게이션

§3.2의 키보드 내비게이션 규칙을 동일하게 적용한다 (MUST):

| 키                 | 동작                                                      |
| ------------------ | --------------------------------------------------------- |
| `↑` / `↓`          | 목록 항목 간 포커스 이동. 목록 끝에서 순환 (SHOULD).      |
| `Enter` 또는 `Tab` | 포커스된 항목 선택 및 입력창에 반영                       |
| `Esc`              | 팝업 닫기, `@` 포함 입력 텍스트는 유지                    |
| 계속 타이핑        | 퍼지 검색 갱신. 포커스는 목록의 첫 항목으로 리셋 (SHOULD) |

포커스 하이라이트, 자동 스크롤, 마우스/터치 조작 규칙도 §3.2와 동일하다.

**추가 규칙**: `/`(슬래시) 키 입력은 디렉토리 구분자로서 검색 쿼리에 포함되어야 하며, 슬래시 명령어 팝업을 트리거해서는 안 된다 (MUST NOT). 즉, `@` 팝업이 활성 상태인 동안 `/` 입력은 파일 경로 검색의 일부로 처리한다.

#### 3.4.5. 선택 후 동작: 파일 참조 토큰 렌더링

사용자가 파일을 선택하면, 입력창에서 `@{타이핑한_텍스트}`를 **인라인 파일 참조 토큰**으로 교체해야 한다 (MUST). 이 토큰은 입력창 내에서 일반 텍스트와 시각적으로 명확히 구분되는 독립적 시각 요소로 렌더링한다.

**토큰 시각 사양:**

- **배경색**: 본문 입력 영역의 배경과 구분되는 연한 강조색(예: 연한 파란색 `#E3F2FD`, 또는 테마의 `primary` 색상의 10~15% 불투명도)을 적용한다 (MUST).
- **둥근 모서리**: `border-radius: 3~4px`를 적용하여 토큰의 경계를 시각적으로 명확히 한다 (MUST).
- **내부 패딩**: 좌우 4~6px, 상하 1~2px의 미세한 패딩을 부여한다 (SHOULD).
- **텍스트 내용**: 파일명만 표시하거나, 짧은 경우 상대 경로 전체를 표시한다. 경로가 긴 경우 `…/` 접두로 축약할 수 있다 (MAY).
- **파일 아이콘 (MAY)**: 토큰 좌측에 확장자별 소형 아이콘 또는 이모지를 표시한다. §3.4.2의 아이콘 매핑을 따른다. 아이콘은 텍스트와 동일한 줄높이 내에서 수직 중앙 정렬한다.
- **폰트**: 모노스페이스 폰트를 적용하여 파일 경로임을 시각적으로 암시한다 (SHOULD). 폰트 크기는 입력창의 본문 텍스트와 동일하게 유지한다.

**토큰 동작:**

- 토큰은 커서 이동 시 **원자 단위(atomic unit)** 로 취급한다 (MUST). 좌/우 화살표로 커서가 토큰에 도달하면 토큰 전체를 건너뛴다. 토큰 내부에 커서가 진입하지 않는다.
- 토큰을 포함한 텍스트의 복사/붙여넣기 시, 토큰은 `@파일명` 형태의 플레인 텍스트로 변환된다 (SHOULD).

**토큰 삭제 (Fluid Deletion):**

토큰 삭제는 커서 위치에 관계없이 물 흐르듯 자연스러운 시각적 연속성을 유지해야 한다 (MUST). 삭제 과정에서 대화 흐름이 끊기거나 레이아웃이 점프해서는 안 된다 (MUST NOT).

- **Backspace (토큰 직후에서)**: 첫 번째 `Backspace`로 토큰 전체를 선택(하이라이트) 상태로 전환한다 (MUST). 하이라이트된 토큰은 배경색 변경(예: 기존 연한 파란색 → 연한 빨간색 `#FFEBEE` 또는 테마의 `danger` 색상 10~15% 불투명도)으로 삭제 예정 상태임을 표시한다. 두 번째 `Backspace`로 토큰을 삭제한다.
- **Delete (토큰 직전에서)**: `Backspace`와 동일한 2단계 동작을 `Delete` 키에도 적용해야 한다 (MUST).
- **삭제 애니메이션**: 토큰이 삭제될 때 너비를 0으로 축소하는 트랜지션(100~150ms)을 적용하여 후속 텍스트가 부드럽게 당겨지도록 해야 한다 (MUST). 즉시 제거하여 텍스트가 갑자기 이동하는 것은 허용하지 않는다 (MUST NOT).
- **범위 선택 삭제**: 사용자가 마우스 드래그 또는 Shift+화살표로 토큰을 포함하는 텍스트 범위를 선택한 후 삭제하면, 선택 범위 내의 토큰은 2단계 확인 없이 즉시 삭제한다 (MUST). 이 경우에도 삭제 애니메이션은 적용한다 (SHOULD).
- **Undo 지원**: 토큰 삭제 후 `Ctrl+Z`(macOS: `Cmd+Z`)로 토큰을 복원할 수 있어야 한다 (MUST). 복원 시 토큰의 메타데이터(`ref_id`, 파일 경로 등)도 함께 복원된다.

**복수 참조**: 단일 메시지 내에 여러 개의 파일 참조 토큰이 존재할 수 있다 (MUST 지원). 각 토큰은 독립된 `ref_id`를 가지며, 동일 파일을 중복 참조하더라도 별개의 토큰으로 취급한다.

#### 3.4.6. 메시지 전송 시 변환 및 이스케이프

사용자가 메시지를 전송하면, 클라이언트는 입력창의 콘텐츠를 다음 두 영역으로 분리하여 처리해야 한다 (MUST):

- **토큰 영역**: UI 파일 선택을 통해 삽입된 인라인 토큰. DPS §16.2.1의 토큰 포맷(`<@file:ref_id|display_path>`)으로 변환한다. 이스케이프를 적용하지 않는다.
- **텍스트 영역**: 사용자가 키보드로 직접 입력한 모든 나머지 텍스트. DPS §16.2.2의 이스케이프 규칙을 적용하여 `\` → `\\`, `<@` → `\<@` 변환을 수행한다.

이 분리는 입력창의 내부 데이터 모델에서 토큰 노드와 텍스트 노드를 구분하여 관리함으로써 구현한다. 입력창이 단순 텍스트 필드(`<input>`, `<textarea>`)인 경우에도, 토큰 삽입 시점에 내부적으로 토큰 위치와 메타데이터를 별도 추적해야 한다 (MUST).

각 토큰에 대응하는 `file_references` 배열을 구성하여 DPS `control.prompt.request`의 `payload`에 포함한다 (MUST).

#### 3.4.7. 슬래시 명령어와의 상호 배타

`@` 팝업이 활성 상태인 동안 `/` 입력은 파일 경로의 일부로 처리하며, 슬래시 명령어 팝업을 트리거하지 않는다 (MUST). 역으로, `/` 팝업이 활성 상태인 동안 `@` 입력은 명령어 인자의 일부로 처리한다 (SHOULD). 동시에 두 팝업이 활성화되어서는 안 된다 (MUST NOT).

---

> **Part 1 끝. §4 에이전트 메시지, §5 시스템 메시지, §6 비스트리밍 환경 적응, §7 파일 브라우저 및 부록은 Part 2를 참조하십시오.**

# RAWP-CRS 1.0: Client Rendering Specification — Part 2 (§4–§7, 부록)

> **본 파일은 RAWP-CRS 1.0의 §4–§7 및 부록을 포함합니다. §1–§3(파일 참조 입력 §3.4 포함)은 Part 1을 참조하십시오.**

| 항목             | 값                 |
| ---------------- | ------------------ |
| 상태             | Stable             |
| 버전             | 1.0.2              |
| 상위 규격        | **RAWP 1.0.3**     |
| 데이터 평면 규격 | **RAWP-DPS 1.0.1** |

---

## 4. 에이전트 메시지 (Agent Message)

에이전트 메시지의 설계 목표는 **다양한 형식의 콘텐츠를 복잡함 없이 제시**하는 것이다. 에이전트는 텍스트, 마크다운, 사고 과정, 도구 호출 결과, 코드 diff, 태스크 목록 등 이질적인 형식의 출력을 생성하며, 이들이 하나의 대화 흐름에서 자연스럽게 읽히도록 해야 한다.

### 4.1. 레이아웃 원칙: 버블리스 디자인 (Bubble-less Design)

에이전트 메시지는 채팅 버블로 감싸지 않는다 (MUST NOT). 에이전트 출력에 채팅 버블을 적용하면 다음의 문제가 발생한다:

- 코드 블록, diff 뷰어, 태스크 목록 등이 버블 내부에 중첩되어 이중 컨테이너(container-in-container) 구조가 되며, 시각적 노이즈가 증가한다.
- 버블의 고정 패딩과 최대 너비 제한이 코드, 테이블, diff 등 가로 공간이 필요한 콘텐츠의 가독성을 저해한다.
- 다양한 콘텐츠 유형(텍스트, 코드, diff, 파일 트리 등)이 동일한 버블 외형으로 감싸져 유형별 시각적 구분이 무너진다.

에이전트 출력은 대화 영역의 좌측에 정렬하되, 버블 없이 콘텐츠 자체의 시각적 형태(텍스트 블록, 코드 블록, diff 뷰어, 카드 등)로 유형을 구분한다. 각 콘텐츠 블록 사이에는 충분한 수직 간격(예: 12~16px)을 확보하여 블록 간 경계를 명확히 한다 (SHOULD).

### 4.2. 마크다운 렌더링 (Markdown Rendering)

에이전트의 텍스트 응답은 마크다운 형식을 포함할 수 있으며, 클라이언트는 아래에 명시된 마크다운 컴포넌트를 렌더링할 수 있어야 한다. 각 컴포넌트는 지원 수준에 따라 **필수(MUST)**, **권장(SHOULD)**, **선택(MAY)** 으로 분류된다. 필수 컴포넌트를 렌더링하지 못하는 클라이언트는 본 프로토콜의 UI 적합성을 만족하지 못하는 것으로 간주한다.

**A. 인라인 텍스트 서식 (Inline Text Formatting)**

인라인 서식은 문장 내에서 특정 텍스트 범위에 스타일을 적용하는 요소다. 모든 인라인 서식은 상호 중첩(nesting)이 가능해야 한다 (MUST). 예: `***bold and italic***`, ``**bold with `code`**``.

| 컴포넌트                      | 마크다운 구문                   | 렌더링 명세                                                                                                                                                                    | 지원 수준 |
| ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| **볼드 (Bold)**               | `**text**` 또는 `__text__`      | `font-weight: bold` 적용. 본문 텍스트보다 시각적으로 두꺼워야 한다.                                                                                                            | MUST      |
| **이텔릭 (Italic)**           | `*text*` 또는 `_text_`          | `font-style: italic` 적용. 기울어진 글꼴로 렌더링한다.                                                                                                                         | MUST      |
| **볼드+이텔릭**               | `***text***`                    | 볼드와 이텔릭을 동시에 적용.                                                                                                                                                   | MUST      |
| **취소선 (Strikethrough)**    | `~~text~~`                      | `text-decoration: line-through` 적용. 텍스트 중앙을 가로지르는 선을 표시한다.                                                                                                  | MUST      |
| **인라인 코드 (Inline Code)** | `` `code` ``                    | 모노스페이스 폰트 적용. 본문 텍스트와 구분되는 배경색(예: 연한 회색)과 미세한 패딩을 부여하여 시각적으로 분리한다. 내부 텍스트는 마크다운 파싱 대상에서 제외(escape)해야 한다. | MUST      |
| **하이라이트 (Highlight)**    | `==text==`                      | `<mark>` 또는 동등한 형광펜 배경색을 적용하여 강조한다.                                                                                                                        | SHOULD    |
| **밑줄 (Underline)**          | `<u>text</u>` (HTML 태그)       | `text-decoration: underline` 적용. 링크와의 시각적 혼동을 방지하기 위해 밑줄 색상은 링크 색상과 구분되어야 한다 (SHOULD).                                                      | SHOULD    |
| **위첨자 (Superscript)**      | `^text^` 또는 `<sup>text</sup>` | 본문 기준선보다 위에, 작은 폰트 크기로 렌더링한다.                                                                                                                             | SHOULD    |
| **아래첨자 (Subscript)**      | `~text~` 또는 `<sub>text</sub>` | 본문 기준선보다 아래에, 작은 폰트 크기로 렌더링한다. 취소선(`~~`)과의 구문 충돌에 주의: 물결표 1개는 아래첨자, 2개는 취소선으로 파싱한다.                                      | SHOULD    |
| **키보드 키 (Keyboard)**      | `<kbd>Ctrl</kbd>`               | 키캡 스타일의 인라인 요소로 렌더링. 둥근 보더, 미세한 그림자, 모노스페이스 폰트를 적용하여 물리 키보드 키를 시각적으로 모방한다.                                               | MAY       |

**B. 블록 요소: 헤더 (Headings)**

| 컴포넌트     | 마크다운 구문        | 렌더링 명세                                                                                                                                                                       | 지원 수준 |
| ------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **헤더 1~6** | `# H1` ~ `###### H6` | 수준별 폰트 크기와 두께를 차등 적용하여 계층 구조를 시각적으로 표현한다. `H1`이 가장 크고, `H6`이 가장 작다. 모든 헤더는 본문 텍스트보다 크거나 같은 크기에 볼드를 적용해야 한다. | MUST      |

**헤더 크기 조정**: 에이전트 응답 내 헤더는 독립 문서가 아닌 대화 컨텍스트 안에서 표시되므로, 문서 수준의 과도하게 큰 `H1`은 대화 흐름을 시각적으로 단절시킨다. 클라이언트는 대화 인터페이스에 적합한 크기 범위로 헤더 스케일을 조정해야 한다 (SHOULD). 예: `H1`을 본문 대비 1.4~1.6배, `H2`를 1.2~1.4배 수준으로 제한하고, `H4`~`H6`은 본문과 동일 크기에 볼드 또는 색상 차등만으로 구분할 수 있다.

**헤더 간격**: 헤더 상단에는 본문 행간보다 넓은 여백(예: 1.5~2배)을 부여하여 섹션 경계를 명확히 해야 한다 (SHOULD). 헤더 하단 여백은 본문 행간과 동일하거나 약간 넓은 수준으로 유지하여 헤더와 후속 본문의 연결감을 보존한다.

**B. 블록 요소: 목록 (Lists)**

| 컴포넌트        | 마크다운 구문                | 렌더링 명세                                                                                                                                                          | 지원 수준 |
| --------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **비순서 목록** | `- item`, `* item`, `+ item` | 불릿 기호(●, ○, ■ 등)와 함께 들여쓰기를 적용하여 렌더링한다.                                                                                                         | MUST      |
| **순서 목록**   | `1. item`, `2. item`         | 숫자 번호와 함께 들여쓰기를 적용하여 렌더링한다. 번호는 마크다운 원문의 숫자가 아닌, 실제 순서를 기반으로 자동 생성해야 한다.                                        | MUST      |
| **중첩 목록**   | 들여쓰기(2~4칸)로 하위 항목  | 들여쓰기 수준에 따라 불릿 기호를 차등 적용(예: 1단계 ●, 2단계 ○, 3단계 ■)하고, 각 수준의 들여쓰기가 시각적으로 명확해야 한다. 비순서↔순서 혼합 중첩도 지원해야 한다. | MUST      |
| **체크리스트**  | `- [ ] todo`, `- [x] done`   | 미체크(☐)와 체크(☑) 상태를 시각적으로 구분하는 체크박스 아이콘을 표시한다. 체크박스는 읽기 전용으로, 사용자가 클릭하여 상태를 변경할 수 없다.                        | SHOULD    |

**B. 블록 요소: 코드 (Code Blocks)**

| 컴포넌트                | 마크다운 구문                | 렌더링 명세                                                                                                                                                                                                                   | 지원 수준 |
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **펜스 코드 블록**      | ` ```language ... ``` `      | 모노스페이스 폰트, 본문과 구분되는 배경색 컨테이너에 렌더링한다. 내용이 가로로 넘칠 경우 **가로 스크롤**을 지원해야 한다 (MUST).                                                                                              | MUST      |
| **구문 하이라이팅**     | ` ```python ` 등 언어 식별자 | 해당 언어의 키워드, 문자열, 주석, 숫자 등을 색상으로 구분하는 구문 하이라이팅을 적용한다. 최소한 주요 언어(Python, JavaScript/TypeScript, Java, C/C++, Go, Rust, HTML, CSS, SQL, Bash, JSON, YAML, Markdown)를 지원해야 한다. | SHOULD    |
| **코드 블록 메타 정보** | —                            | 코드 블록 상단에 언어명 레이블을 표시하고, 우측 상단에 **복사 버튼**을 제공한다. 아래 상세 규칙 참조.                                                                                                                         | MUST      |
| **라인 번호**           | —                            | 긴 코드 블록(예: 10줄 이상)에는 좌측에 라인 번호를 표시한다.                                                                                                                                                                  | MAY       |

**코드 블록 복사 버튼 상세 규칙:**

- **아이콘 전용**: 복사 버튼은 클립보드 아이콘만으로 구성하며, 텍스트 레이블("Copy" 등)을 포함하지 않는다 (MUST NOT). 이는 코드 블록의 시각적 간결함을 유지하기 위함이다.
- **위치**: 코드 블록 우측 상단에 배치한다 (MUST). 코드 블록에 마우스를 호버할 때만 표시하거나, 항상 표시하되 낮은 불투명도(예: 40~50%)로 처리하여 코드 가독성을 방해하지 않는다 (SHOULD).
- **복사 완료 피드백**: 버튼 클릭 시 사용자에게 복사가 완료되었음을 명확히 전달해야 한다 (MUST). 다음 시각적 피드백을 모두 적용한다:
  - **아이콘 전환**: 클립보드 아이콘 → 체크마크(✓) 아이콘으로 즉시 전환한다 (MUST). 1.5~2초 후 원래 아이콘으로 복귀한다.
  - **색상 변화**: 아이콘 색상을 기본 색상 → 녹색 계열(성공 색상)으로 전환한다 (MUST). 아이콘 복귀와 함께 원래 색상으로 돌아간다.
  - **탄성 애니메이션**: 아이콘 전환 시 스프링(spring) 또는 바운스 애니메이션을 적용하여 시각적 피드백을 강화한다 (SHOULD). 애니메이션 지속 시간은 100~250ms.
- **복사 실패 처리**: 클립보드 API가 실패한 경우(권한 거부 등), 아이콘을 경고 아이콘(⚠)으로 전환하고 빨간 계열 색상을 적용한다 (SHOULD).

**B. 블록 요소: 테이블 (Tables)**

| 컴포넌트   | 마크다운 구문      | 렌더링 명세                                | 지원 수준 |
| ---------- | ------------------ | ------------------------------------------ | --------- |
| **테이블** | `\| col \| col \|` | 행과 열이 구분된 테이블 형태로 렌더링한다. | MUST      |

**테이블 상세 명세**: 헤더 행 구분(MUST), 열 정렬(MUST), 행 구분(SHOULD), 셀 패딩(MUST), 오버플로우 시 가로 스크롤(MUST), 셀 내 마크다운(MUST).

**B. 블록 요소: 인용, 구분선, 이미지 (Quotes, Dividers, Images)**

| 컴포넌트        | 마크다운 구문         | 렌더링 명세                                                                                                             | 지원 수준 |
| --------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- |
| **인용구**      | `> text`              | 좌측에 수직 보더(3~4px, 강조 색상 또는 회색)를 배치하고, 본문 대비 들여쓰기를 적용한다. 다중 수준 인용 지원.            | MUST      |
| **수평선**      | `---`, `***`, `___`   | 전체 가용 너비에 걸친 시각적 구분선을 렌더링한다.                                                                       | MUST      |
| **이미지**      | `![alt](url)`         | 인라인 이미지로 렌더링. 최대 너비 제한(MUST), 원본 비율 유지(MUST), 로딩 중 placeholder(SHOULD), alt 텍스트 폴백(MUST). | MUST      |
| **이미지 캡션** | `![alt](url "title")` | `title` 속성이 제공된 경우, 이미지 하단에 캡션 텍스트로 표시한다.                                                       | MAY       |

**B. 블록 요소: 링크, 참조 (Links & References)**

| 컴포넌트        | 마크다운 구문                      | 렌더링 명세                                                                                                | 지원 수준 |
| --------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------- |
| **인라인 링크** | `[text](url)`                      | 클릭 가능한 하이퍼링크. 외부 링크는 새 탭/창에서 열어야 한다 (SHOULD).                                     | MUST      |
| **자동 링크**   | `<https://...>` 또는 URL 자동 감지 | URL 형태의 텍스트를 자동으로 클릭 가능한 링크로 변환한다.                                                  | SHOULD    |
| **참조 링크**   | `[text][id]` + `[id]: url`         | 참조 스타일 링크를 인라인 링크와 동일하게 렌더링한다.                                                      | SHOULD    |
| **각주**        | `[^1]` + `[^1]: text`              | 본문 내 각주 참조를 위첨자 번호로 표시하고, 클릭 시 대응하는 각주 내용으로 스크롤하거나 툴팁으로 표시한다. | MAY       |

**C. 수식 (Math / LaTeX)**

| 컴포넌트        | 마크다운 구문 | 렌더링 명세                                                        | 지원 수준 |
| --------------- | ------------- | ------------------------------------------------------------------ | --------- |
| **인라인 수식** | `$E = mc^2$`  | 본문 텍스트 흐름 내에서 수식을 렌더링한다. KaTeX, MathJax 등 사용. | SHOULD    |
| **블록 수식**   | `$$\n...\n$$` | 독립된 블록으로 중앙 정렬하여 수식을 렌더링한다.                   | SHOULD    |

**D. 다이어그램 (Diagrams)**

| 컴포넌트               | 마크다운 구문          | 렌더링 명세         | 지원 수준 |
| ---------------------- | ---------------------- | ------------------- | --------- |
| **Mermaid 다이어그램** | ` ```mermaid ... ``` ` | 아래 상세 규칙 참조 | SHOULD    |

**Mermaid 렌더링 상세 규칙:**

**뷰 모드**: Mermaid 코드 블록은 다음 세 가지 뷰 모드를 제공해야 한다 (MUST):

| 뷰 모드                    | 표시 내용                                                                 | 기본 상태 |
| -------------------------- | ------------------------------------------------------------------------- | --------- |
| **다이어그램 보기**        | 렌더링된 다이어그램만 표시                                                | 기본값    |
| **코드 + 다이어그램 보기** | 원본 Mermaid 코드와 렌더링된 다이어그램을 상하 또는 좌우 분할로 동시 표시 | —         |
| **코드 보기**              | 원본 Mermaid 코드를 구문 하이라이팅 적용된 코드 블록으로 표시             | —         |

뷰 모드 전환은 다이어그램 영역 상단의 탭 또는 토글 버튼으로 제공해야 한다 (MUST). 뷰 모드 전환 시 레이아웃 점프를 최소화해야 한다 (SHOULD).

**렌더링 에러 처리**: Mermaid 구문 에러로 렌더링이 실패한 경우:

- 다이어그램 영역에 에러 메시지를 표시해야 한다 (MUST). 에러 메시지는 Mermaid 파서가 반환한 에러 내용(라인 번호, 에러 유형 등)을 포함한다.
- 에러 상태에서는 자동으로 **코드 보기** 모드로 전환하고, 에러가 발생한 라인을 강조 표시해야 한다 (SHOULD).
- 에러 메시지는 §5.3의 `warning` 심각도 스타일(주황 계열)을 적용하여 다이어그램 영역 상단에 인라인으로 표시한다.

**다이어그램 색상 가이드**: 렌더링된 다이어그램은 대화 인터페이스의 테마와 조화되어야 한다 (MUST). 다음 색상 원칙을 따른다:

- **배경**: 투명 또는 대화 영역의 배경과 동일. 다이어그램 전용 배경색을 추가하지 않는다 (MUST NOT).
- **노드/요소**: 테마의 `primary` 색상 계열을 기반으로 한다. 라이트 테마에서는 연한 파란 계열(`#E3F2FD` ~ `#BBDEFB`), 다크 테마에서는 어두운 파란 계열(`#1A237E` ~ `#283593`)을 권장한다 (SHOULD).
- **텍스트**: 대화 영역의 본문 텍스트 색상(`--color-text-emphasis`)과 동일하게 적용하여 가독성을 확보한다 (MUST).
- **연결선/화살표**: 테마의 보조 텍스트 색상(`--color-text-secondary`)을 사용한다 (SHOULD).
- **강조 요소**: 상태 다이어그램의 활성 상태, 시퀀스 다이어그램의 현재 참여자 등 강조가 필요한 요소에는 테마의 `accent` 색상을 사용한다. 동시에 3가지 이상의 강조 색상을 사용하지 않는다 (SHOULD NOT).
- **색상 수 제한**: 단일 다이어그램에서 사용하는 고유 색상 수는 5개 이내로 제한하여 시각적 복잡도를 낮춘다 (SHOULD). 배경, 노드, 텍스트, 연결선, 강조의 5가지 역할에 각각 1색을 할당한다.

**다이어그램 크기 제어**:

- 다이어그램의 최대 너비는 대화 영역의 가용 너비를 초과하지 않는다 (MUST). 초과 시 다이어그램 내부를 가로 스크롤하거나 축소한다.
- 다이어그램의 최대 높이를 제한하여 대화 흐름이 과도하게 밀려나지 않도록 한다 (SHOULD). 높이 제한 초과 시 다이어그램 내부를 세로 스크롤한다.

**다이어그램 확장 보기 (Expanded View)**:

- 렌더링된 다이어그램 영역을 클릭하면 오버레이(모달) 형태의 **확장 보기**로 진입해야 한다 (MUST). 확장 보기는 뷰포트 기준 최대 크기로 다이어그램을 다시 렌더링하며, 배경에 딤(dim) 처리를 적용한다.
- 확장 보기 내에서 핀치 줌 및 드래그 패닝을 지원해야 한다 (SHOULD).
- 확장 보기에서도 뷰 모드 전환(다이어그램 보기 / 코드 + 다이어그램 보기 / 코드 보기)을 유지해야 한다 (MUST).
- 닫기: `ESC` 키, 배경 영역 클릭, 닫기 버튼 중 하나 이상을 제공해야 한다 (MUST).
- 다이어그램 영역에 확장 가능함을 암시하는 시각적 힌트(예: 우측 상단 확장 아이콘, 호버 시 커서 변경)를 제공해야 한다 (SHOULD).

**E. 기타 요소 (Miscellaneous)**

| 컴포넌트             | 마크다운 구문                                      | 렌더링 명세                                                                                                                                                                       | 지원 수준 |
| -------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **이모지**           | `:emoji_name:`                                     | GitHub 스타일 이모지 숏코드를 유니코드 이모지로 변환한다. 유니코드 이모지 직접 입력도 올바르게 렌더링해야 한다 (MUST).                                                            | SHOULD    |
| **줄바꿈**           | 행 끝 공백 2칸 또는 `<br>`                         | 명시적 줄바꿈을 적용한다.                                                                                                                                                         | MUST      |
| **이스케이프 문자**  | `\*`, `\#`, `\_` 등                                | 백슬래시로 이스케이프된 마크다운 특수 문자는 리터럴 문자 그대로 표시한다.                                                                                                         | MUST      |
| **HTML 인라인 태그** | `<br>`, `<u>`, `<sup>`, `<sub>`, `<mark>`, `<kbd>` | 안전한(safe) HTML 태그에 한해 인라인 렌더링을 허용한다. `<script>`, `<iframe>`, `<style>`, `<form>` 등 보안 위험이 있는 태그는 반드시 무시하거나 이스케이프 처리해야 한다 (MUST). | SHOULD    |

**스트리밍 중 미완성 마크다운 방어**: 렌더러는 스트리밍 중 마크다운 태그가 닫히지 않은 상태로 전달되더라도 UI가 깨지지 않도록 방어적으로 처리해야 한다 (MUST). 코드 블록은 열림 태그 수신 시 즉시 컨테이너를 생성하고 최소 높이를 할당한다 (SHOULD). 인라인 서식은 임시로 서식을 적용하되 닫는 마커 수신 시 확정한다. 테이블은 구분 행 수신 시점부터 렌더링을 시작한다 (SHOULD).

### 4.3. 점진적 텍스트 렌더링 (Progressive Text Rendering)

실시간 스트리밍 환경(WSS 지원 클라이언트)에서의 텍스트 렌더링 지침이다.

**버퍼 병합**: 클라이언트는 `content_index` 단위로 수신되는 텍스트 페이로드를 지연 없이 화면에 점진적으로 렌더링해야 한다 (MUST).

**오토 스크롤 제어**: 텍스트 생성 중에는 뷰포트 하단을 자동으로 추적하되, 사용자가 과거 이력을 보기 위해 스크롤을 위로 올린 상태(Scroll Up)에서는 읽기 방해를 막기 위해 오토 스크롤을 일시 중단해야 한다 (SHOULD).

**스크롤 안정성 (Scroll Stability)**: 클라이언트는 사용자가 현재 읽고 있는 텍스트가 시각적으로 흔들리지 않도록 스크롤 위치를 능동적으로 제어해야 한다 (MUST). 구체적으로 다음을 준수한다:

- **앵커 포인트 고정**: 오토 스크롤이 활성화된 상태에서는, 새로운 텍스트가 삽입될 때 현재 생성 중인 마지막 라인이 뷰포트 하단의 일정 영역(예: 하단 20~30% 지점)에 고정되도록 조정해야 한다 (MUST).
- **상방 삽입 보상 (Upward Insertion Compensation)**: 현재 읽고 있는 영역 **위쪽**에 콘텐츠가 삽입되거나 높이가 변하는 경우, 삽입된 높이만큼 `scrollTop`을 보상하여 현재 보고 있는 텍스트의 화면상 절대 위치가 변하지 않도록 해야 한다 (MUST).
- **부드러운 추종**: 오토 스크롤 시 `scrollTo`에 `behavior: 'instant'`를 사용하여 프레임 단위로 즉각 추종해야 한다 (SHOULD). `behavior: 'smooth'`는 빠른 텍스트 생성 속도에 뒤처져 누적 지연을 유발할 수 있으므로 스트리밍 중에는 사용하지 않아야 한다 (SHOULD NOT).
- **높이 변동 최소화**: 코드 블록, 테이블, 이미지 등 높이가 확정되지 않은 요소는 예상 높이를 미리 확보(placeholder/skeleton)하여 렌더링 완료 시 높이 변동폭을 최소화해야 한다 (SHOULD).

**텍스트 출현의 시각적 연속성 (Visual Continuity of Text Appearance)**: 점진적으로 생성되는 텍스트는 사용자에게 **매끄럽고 연속적인 흐름**으로 인지되어야 한다 (MUST). 구체적으로 다음을 준수한다:

- **마이크로 배칭 및 보간**: 클라이언트는 수신된 `agent.text.delta` 토큰을 짧은 시간 윈도우(예: 30~60ms) 내에 모아 한 번에 렌더링하거나, `requestAnimationFrame` 주기에 동기화하여 프레임당 일정량의 텍스트를 출력하는 방식을 적용해야 한다 (SHOULD). 단, 배칭으로 인한 체감 지연이 100ms를 초과해서는 안 된다 (MUST NOT).
- **출현 애니메이션**: 새로 삽입되는 텍스트에 미세한 페이드인 또는 수직 슬라이드인 효과를 적용할 수 있다 (MAY). 적용 시 애니메이션 지속 시간은 50~120ms 이내로 제한해야 한다 (MUST). 애니메이션은 **가장 최근에 추가된 텍스트 청크에만** 적용하며, 이미 표시된 텍스트가 반복적으로 애니메이션되어서는 안 된다 (MUST NOT).
- **하단 경계 효과 제한**: 생성 중인 텍스트의 하단 경계에 블러, 그라데이션 페이드 등의 시각 효과를 적용하는 경우, 효과 영역의 높이는 **텍스트 2줄 이내**(약 40~48px)로 제한한다 (MUST). 블러 강도는 **4px 이하**로 제한한다 (SHOULD). 맥동, 깜빡임, 색상 순환 등 동적 변화를 하단 경계 효과에 적용해서는 안 된다 (MUST NOT). 생성 완료(`agent.text.done`) 시 즉시 제거하거나 100ms 이내에 페이드아웃해야 한다 (MUST).
- **읽기 흐름 보호 원칙**: 점진적 렌더링의 모든 시각적 처리는 다음의 상위 원칙을 따라야 한다: **사용자가 이미 생성된 텍스트를 읽는 행위를 방해해서는 안 된다 (MUST NOT).**

### 4.4. 사고 과정 시각화 (Thinking Process)

**시각적 분리**: `agent.thinking.delta`의 내용은 일반 응답 텍스트와 명확히 구분되는 별도의 컨테이너(예: 인용구, 배경색이 다른 블록)에 렌더링해야 한다 (MUST).

**진행 상태 표현 (Thinking Indicator)**: 사고 과정이 진행 중일 때, 사용자에게 에이전트가 능동적으로 작업 중임을 시각적으로 전달해야 한다 (MUST). 그라데이션 애니메이션(SHOULD), 1.5~3초 사이의 느린 호흡 리듬(SHOULD), "Thinking…" 레이블(MUST)을 포함한다.

**실시간 텍스트 노출 정책**: 사고 스트림의 텍스트 본문을 사용자에게 실시간으로 노출할지 여부는 클라이언트 설정에 따른다. 요약 모드(기본값 권장)와 실시간 모드를 지원할 것을 권장한다 (SHOULD).

**상태 전이 및 제거**: `agent.thinking.done` 수신 시, 그라데이션 애니메이션을 즉시 중단하고 (MUST), 접힌 상태로 전환하여 "Thought for Ns" 요약 한 줄만 표시한다 (SHOULD). 활성 → 접힘 전환은 150~300ms 트랜지션으로 처리한다 (SHOULD). 후속 `agent.text.delta` 영역으로 시선을 유도한다 (SHOULD).

**마스킹 처리**: `redacted: true`인 경우 `[사고 내용 생략]` 등의 플레이스홀더로 마스킹하고 (MUST), 펼침 동작 자체를 비활성화한다 (MUST).

**다중 사고 블록**: 각 `content_index`별로 독립된 사고 컨테이너를 생성하되, 동시에 두 개 이상의 Thinking Indicator가 활성 상태로 표시되어서는 안 된다 (MUST NOT).

### 4.5. 도구 가용 상태 및 호출 결과 렌더링 (Tool Status & Result Rendering)

#### 4.5.1. 도구 가용 상태 표시 (Tool Availability Indicator)

`tool.catalog.publish`(RAWP-DPS 1.0.1 §5.4.1) 수신 시, 각 도구의 `status` 필드에 따라 가용 상태를 시각적으로 구분하여 표시해야 한다 (MUST). 도구 목록을 노출하는 모든 UI(도구 팔레트, 사이드바, 도구 호출 헤더 등)에 적용한다.

**상태별 시각 표현:**

| `status`      | 시각 표현                                       | 도구명 스타일                                  | 상호작용           |
| ------------- | ----------------------------------------------- | ---------------------------------------------- | ------------------ |
| `available`   | 없음 (기본 상태이므로 별도 표시 불필요)         | 기본 텍스트                                    | 정상 사용 가능     |
| `unavailable` | 도구명 좌측에 금지 아이콘(🚫) 또는 빨간 점 표시 | 흐린 텍스트(opacity 50%), 취소선 적용 (SHOULD) | 클릭/선택 비활성화 |
| `degraded`    | 도구명 좌측에 경고 아이콘(⚠) 또는 주황 점 표시  | 기본 텍스트 유지                               | 정상 사용 가능     |

**상태 사유 표시**: 도구의 `status_description` 필드(RAWP-DPS 1.0.1 §5.4.1)가 존재하면, 도구명 하단에 한 줄로 사유를 표시해야 한다 (MUST). `unavailable`이면 연한 빨간 텍스트, `degraded`이면 연한 주황 텍스트로 표시한다. `status_description`이 없으면 사유를 표시하지 않는다 (MUST NOT). 예: `Bash` 아래에 `실행 파일을 찾을 수 없음`.

**진단 메시지 연동**: `diagnostics` 배열에 해당 도구의 진단(`tool_name` 일치)이 포함된 경우, 도구 항목에 호버 또는 탭 시 진단 메시지를 툴팁으로 표시할 수 있다 (MAY).

**도구 카탈로그 갱신**: `tool.catalog.publish`가 세션 중 재수신되면, 도구 목록과 상태를 즉시 갱신해야 한다 (MUST). 이전에 `unavailable`이었던 도구가 `available`로 전이되면 금지 표시를 즉시 제거한다.

#### 4.5.2. 도구 호출 결과 렌더링 (Tool Result Rendering)

**진행 중 표시**: `tool.invoke.request` 수신 시, 도구명과 함께 스피너를 인라인으로 표시해야 한다 (MUST). `tool.invoke.stream` 수신 시에는 실시간 출력을 점진적으로 렌더링해야 한다 (SHOULD).

**병렬 도구 그룹화**: 동일한 `parallel_group_id`를 가진 복수의 `tool.invoke.request`는 하나의 그룹 컨테이너로 묶어 표시해야 한다 (SHOULD).

**완료 전환**: `tool.invoke.result` 수신 시, 스피너를 즉시 중단하고 `output_type`에 적합한 결과 뷰어로 전환해야 한다 (MUST). 뷰어 매핑:

| `output_type`  | 권장 뷰어                     | 비고                              |
| -------------- | ----------------------------- | --------------------------------- |
| `text`         | 모노스페이스 텍스트 블록      | Bash stdout 등                    |
| `diff`         | 구문 인지 Diff 뷰어           | §4.6 참조 (MUST)                  |
| `file_content` | 라인 번호 포함 코드 뷰어      | 구문 하이라이팅 적용 (SHOULD)     |
| `file_list`    | 파일 트리 또는 경로 목록      | 클릭 시 해당 파일 열기 지원 (MAY) |
| `web_content`  | 링크 포함 요약 카드           | 출처 URL 표시 (MUST)              |
| `structured`   | JSON 트리 뷰어 또는 전용 위젯 | TodoRead 등은 §4.8 참조           |
| `empty`        | 성공 체크마크 한 줄           | "✅ Write completed" 등           |
| `agent_result` | 서브에이전트 결과 접이식 블록 | 클릭 시 전체 결과 펼침 (SHOULD)   |

**파일 조작 결과 헤더**: `tool.invoke.result`에서 도구가 파일 조작 도구(`category: "filesystem"`, `tool_name` ∈ {Write, Edit, MultiEdit} 또는 동등 도구)인 경우, 결과 헤더에 파일 조작 유형을 명시적으로 표시해야 한다 (MUST):

| 조작 유형 | 헤더 표시 예시          | 시각적 힌트    |
| --------- | ----------------------- | -------------- |
| 파일 생성 | `Created: {file_path}`  | 녹색 계열 강조 |
| 파일 수정 | `Modified: {file_path}` | 기본 색상      |
| 파일 삭제 | `Deleted: {file_path}`  | 빨간 계열 강조 |

조작 유형의 판단은 도구의 `tool_name`과 `input` 필드에서 유추한다. 예: `tool_name: "Write"`이면 파일 생성 또는 덮어쓰기, `tool_name: "Edit"`이면 수정.

**에러 결과 표시**: `status`가 `error`, `timeout`, `cancelled`인 경우, 에러 상태를 시각적으로 구분하여 표시해야 한다 (MUST).

**접이식 기본 동작**: 도구 결과는 기본적으로 접힌 상태로 표시하되, 결과 요약 한 줄을 노출하고 클릭 시 전체 결과를 펼칠 수 있어야 한다 (SHOULD). 단, `output_type: diff`인 경우에는 기본 펼침 상태를 허용한다 (MAY).

### 4.6. Code Diff 렌더링 (Diff Viewer)

`output_type: diff` 또는 `output_type: text`이면서 내용이 Unified Diff 형식인 도구 결과는, **구문 인지 Diff 뷰어**로 렌더링해야 한다 (MUST).

**Diff 형식 자동 감지**: `output_type`이 `text`인 경우에도, 출력 내용의 첫 10라인 이내에 `--- a/`, `+++ b/`, `@@` 등 Unified Diff 시그니처가 감지되면 Diff 뷰어로 자동 전환해야 한다 (SHOULD).

**라인 수준 색상 구분**: 삭제=빨강 계열, 추가=녹색 계열의 대비가 즉각적으로 인지되어야 한다 (MUST).

| 접두 문자    | 의미           | 라이트 테마 배경 | 다크 테마 배경 |
| ------------ | -------------- | ---------------- | -------------- |
| `-`          | 삭제된 라인    | `#fdd`           | `#3d1114`      |
| `+`          | 추가된 라인    | `#dfd`           | `#1a361a`      |
| `@@`         | 청크 헤더      | `#def`           | `#1a2a3a`      |
| (공백)       | 컨텍스트 라인  | 투명             | 투명           |
| `diff --git` | 파일 경계 헤더 | 연한 회색        | 어두운 회색    |

**인라인 단어 수준 하이라이팅**: 동일 위치의 삭제/추가 라인 쌍에 대해, 라인 내 실제로 변경된 단어/문자 범위를 추가 강조할 것을 권장한다 (SHOULD).

**라인 번호 표시**: 원본(old)과 변경(new)의 라인 번호를 이중 컬럼으로 표시해야 한다 (SHOULD).

**파일 헤더 구분**: 여러 파일의 변경 사항이 포함된 경우, 각 파일 경계를 명확한 헤더로 구분해야 한다 (MUST). 파일 단위 접기/펼치기를 지원할 것을 권장한다 (SHOULD).

**뷰 모드 전환**: Unified View(기본값)와 Side-by-side View를 제공할 것을 권장한다 (SHOULD).

**접근성 고려**: 색상과 함께 접두 기호(`-`, `+`)를 항상 가시적으로 유지하고, 선택적으로 아이콘 또는 패턴을 병행 표시할 것을 권장한다 (SHOULD).

**변경 통계 요약 표시**: Diff 헤더 또는 푸터에 변경 통계를 한 줄로 요약 표시해야 한다 (MUST). 형식: `+{추가_라인_수} -{삭제_라인_수}`. 예: `+12 -3`.

**파일 생성/삭제 배지**:

- 모든 라인이 `+`(추가)인 Diff는 파일 전체가 신규 생성되었음을 의미한다. Diff 상단에 `New file` 배지를 표시해야 한다 (MUST).
- 모든 라인이 `-`(삭제)인 Diff는 파일 전체가 삭제되었음을 의미한다. Diff 상단에 `File deleted` 배지를 표시해야 한다 (MUST).
- 배지는 파일 헤더 영역 내에서 파일명과 함께 표시하며, 해당 색상(생성=녹색, 삭제=빨간) 계열의 배경을 적용한다 (SHOULD).

**라인 수준 추가/삭제 시각화**: `tool.invoke.result`의 `output`에 라인별 추가/삭제 정보가 포함된 경우(구조화 Diff 또는 Unified Diff), 개별 라인의 추가/삭제를 본 절의 라인 수준 색상 구분 규칙(삭제=빨강, 추가=녹색)에 따라 표시해야 한다 (MUST).

### 4.7. 에이전트 상태 표시 (Agent State Indicator)

`agent.state.changed` 이벤트는 에이전트의 내부 상태 전이를 실시간으로 통보한다. 각각 독립된 채팅 메시지로 렌더링해서는 안 된다 (MUST NOT).

**단일 인라인 상태 표시줄**: 클라이언트는 에이전트의 현재 상태를 대화 영역의 고정된 단일 위치에 표시하고, 수신 시마다 **제자리 갱신(in-place update)** 해야 한다 (MUST).

**상태별 렌더링**: `thinking` → `🧠 Thinking…` (그라데이션 펄스), `tool_calling` → `🔧 Running tool…` (스피너), `awaiting_input` → `⏸ Waiting for input` (정적), `error` → `⚠ Error occurred` (붉은 강조), `idle` → 표시줄 제거.

**전환 애니메이션**: 100~200ms 이내 크로스페이드 또는 슬라이드 (SHOULD). 전환 속도가 상태 변경 빈도보다 느리면 애니메이션을 생략하고 즉시 교체해야 한다 (MUST).

**유휴 상태 처리**: `idle` 전이 시 즉시 제거하거나 200~300ms 페이드아웃 (MUST). Turn 완료 후 대화 이력에 흔적이 남아서는 안 된다 (MUST NOT).

**대화 이력 비오염 원칙**: `agent.state.changed` 이벤트는 대화 이력에 영구적 항목으로 기록해서는 안 된다 (MUST NOT). 상태 표시는 순수하게 일시적(ephemeral)이다.

### 4.8. 태스크 목록 렌더링 (Task List Rendering)

`output_type: structured` 형태의 TodoRead/TodoWrite 결과(RAWP-DPS §8.2)를 수신하면, 클라이언트는 전용 태스크 관리 UI를 실시간으로 갱신해야 한다 (SHOULD).

**태스크 상태 시각화**:

| `status`      | 시각 표현                        | 비고                       |
| ------------- | -------------------------------- | -------------------------- |
| `pending`     | ○ 빈 원 또는 미체크 체크박스     | 회색 텍스트                |
| `in_progress` | ◐ 반원 또는 스피너 부착 체크박스 | 볼드 텍스트, 강조 배경     |
| `completed`   | ● 채워진 원 또는 체크된 체크박스 | 취소선 텍스트 (SHOULD)     |
| `cancelled`   | ✕ 취소 표시                      | 흐린 텍스트, 불투명도 감소 |

**계층 구조 지원**: `parent_id`가 존재하는 태스크는 부모 태스크 하위에 들여쓰기하여 트리 구조로 렌더링해야 한다 (SHOULD).

**전환 애니메이션**: 태스크 상태 변경 시 부드러운 전환 애니메이션을 적용해야 한다 (SHOULD). 다수의 태스크가 동시에 갱신되는 경우 개별 애니메이션을 생략하고 전체 목록을 일괄 교체할 수 있다 (MAY).

### 4.9. Turn 내 콘텐츠 순서 보장 (Content Ordering within Turn)

에이전트의 단일 Turn은 텍스트 블록, 사고 과정, 도구 호출이 교차(interleave)하여 발생할 수 있다. 이 교차 콘텐츠의 렌더링 순서 규칙을 정의한다.

**수신 순서 렌더링 원칙**: 모든 콘텐츠 블록은 수신 순서대로 대화 영역에 아래로 추가해야 한다 (MUST). 이미 렌더링된 요소의 순서를 재배치(reorder)해서는 안 된다 (MUST NOT).

**마지막 텍스트 블록 최하단 보장 (Last Text Anchoring)**: 에이전트가 Turn 내에서 마지막으로 생성하는 텍스트 블록(`agent.text.delta` → `agent.text.done`)은 해당 Turn의 시각적 렌더링에서 항상 최하단에 위치해야 한다 (MUST). 이는 수신 순서 렌더링 원칙에 의해 자연스럽게 보장된다 — 마지막 텍스트 블록은 마지막에 수신되므로 최하단에 추가된다.

**시퀀스 예시:**

| 수신 순서 | 이벤트                             | 렌더링 위치                   |
| --------- | ---------------------------------- | ----------------------------- |
| 1         | `agent.text.delta` (텍스트 A)      | 최상단                        |
| 2         | `tool.invoke.request` (도구 X)     | 텍스트 A 아래                 |
| 3         | `tool.invoke.result` (도구 X 결과) | 도구 X 요청 아래              |
| 4         | `agent.text.delta` (텍스트 B)      | 도구 X 결과 아래 **(최하단)** |

텍스트 B가 에이전트의 마지막 텍스트 블록이므로, Turn 완료 시 최하단에 위치한다. 이후 추가 도구 호출 없이 `session.turn.end`가 수신되면, 텍스트 B가 사용자에게 가장 마지막으로 보이는 콘텐츠가 된다.

**도구 호출로 Turn이 종료되는 경우**: 에이전트가 텍스트 출력 후 도구 호출을 수행하고 추가 텍스트 없이 Turn이 종료되면, 도구 결과가 최하단이 된다. 이는 허용되는 동작이다.

### 4.10. 서브에이전트 메시지 렌더링 (Subagent Message Rendering)

RAWP-DPS 1.0.1 §10의 서브에이전트 위임 규격에 따라, `metadata.subagent_context`가 포함된 메시지의 렌더링 규칙을 정의한다.

#### 4.10.1. 설계 원칙: 플랫 타임라인 (Flat Timeline)

서브에이전트 메시지는 메인 에이전트 메시지와 **동일한 플랫 타임라인**에 배치해야 한다 (MUST). 서브에이전트 메시지를 별도의 중첩 컨테이너(박스, 카드, 드롭다운 등)로 감싸서는 안 된다 (MUST NOT). 중첩 컨테이너는 depth가 증가할수록 가용 너비가 줄어들고, 중첩 박스 내부의 코드 블록·diff·테이블 등이 심각하게 훼손된다.

**서브에이전트 그룹핑**: 동일 서브에이전트 인스턴스(`parent_invocation_id` 기준)의 메시지는 하나의 연속 그룹으로 묶어서 표시해야 한다 (MUST). 여러 서브에이전트가 동시에 실행되어 메시지가 교차 수신되더라도, 클라이언트는 동일 인스턴스의 메시지를 모아서 그룹 단위로 렌더링한다. 이를 위해 수신 순서와 다르게 표시 순서를 재배치할 수 있다 (MAY).

서브에이전트 메시지와 메인 에이전트 메시지의 구분은 **좌측 보더(left border)** 와 **인라인 출처 라벨(origin label)** 로 표현한다.

#### 4.10.2. 좌측 보더 구분 (Left Border Indicator)

`subagent_context`가 포함된 메시지에는 좌측에 수직 보더를 표시하여 메인 에이전트 메시지와 시각적으로 구분해야 한다 (MUST).

**보더 규칙:**

- **색상**: 서로 다른 서브에이전트 인스턴스(`parent_invocation_id` 기준)에 각각 고유한 보더 색상을 할당해야 한다 (MUST). 동일 depth라도 서로 다른 서브에이전트는 서로 다른 색상을 사용한다. 예: depth 1의 첫 번째 서브에이전트 = 파란 계열, 두 번째 = 보라 계열, 세 번째 = 청록 계열. 색상 할당은 `parent_invocation_id` 등장 순서에 따라 순환 배정한다. 동일 `parent_invocation_id`의 모든 메시지는 동일한 색상을 사용해야 한다 (MUST).
- **너비**: 2~3px의 얇은 세로선. 대화 영역의 가용 너비를 줄이지 않는다.
- **위치**: 메시지 좌측 외곽에 배치. 들여쓰기(padding-left)를 추가하지 않는다 (MUST NOT). 보더는 장식적 요소이지 레이아웃을 변경하는 요소가 아니다.

**메인 에이전트 메시지**: `subagent_context`가 없는 메시지에는 좌측 보더를 표시하지 않는다 (MUST NOT).

#### 4.10.3. 출처 라벨 (Origin Label)

서브에이전트 메시지 그룹의 시작 지점에 인라인 출처 라벨을 한 줄로 표시해야 한다 (MUST). 그룹핑(§4.10.1)에 의해 동일 인스턴스의 메시지가 연속으로 배치되므로, 그룹의 첫 메시지에만 출처 라벨을 표시한다.

**라벨 형식:** `{agent_type}: {description}` 또는 `agent_type`만. `agent_type`이 없으면 `Subagent`. 예: `Explore: 코드 검색 위임`, `Plan`, `Subagent`.

**라벨 스타일:** 연한 텍스트(muted color), 본문보다 작은 폰트 크기. 좌측 보더와 동일한 색상을 텍스트에 적용해야 한다 (MUST). 라벨은 별도의 컨테이너나 배경색 없이 인라인 텍스트로 표시한다.

**종료 라벨:** `agent.subagent.ended` 수신 시, 서브에이전트 영역의 마지막에 종료 라벨을 한 줄로 표시해야 한다 (MUST). 형식: `{agent_type} 완료` 또는 `{agent_type} 실패` (`status`에 따라). `duration_ms`가 있으면 소요 시간을 함께 표시한다 (SHOULD). 예: `Explore 완료 (2.3s)`.

#### 4.10.4. 접기/펼치기

각 서브에이전트 그룹은 접기/펼치기가 가능해야 한다 (MUST).

**접힌 상태**: 출처 라벨(§4.10.3)과 종료 라벨(완료된 경우)만 표시하고, 그 사이의 모든 메시지(도구 호출, 텍스트, 사고 과정 등)를 숨긴다. 접힌 영역에 좌측 보더는 유지하여 서브에이전트 범위를 시각적으로 암시한다 (MUST).

**토글 위치**: 출처 라벨 또는 종료 라벨을 클릭하여 토글한다. 별도의 접기 버튼이나 드롭다운 화살표는 사용하지 않는다 (SHOULD NOT).

**기본 상태**: 진행 중인 서브에이전트는 펼침, 완료된 서브에이전트는 접힘을 기본으로 한다 (SHOULD).

#### 4.10.5. 서브에이전트 도구 호출 표시

- 서브에이전트 내의 도구 호출은 플랫 타임라인에서 좌측 보더가 표시된 채로 수신 순서에 따라 표시한다 (MUST). §4.5.2와 동일한 UI 컴포넌트를 사용한다.
- 서브에이전트 내의 모든 도구 호출 및 결과에 **소속 에이전트 라벨**을 표시해야 한다 (MUST). 라벨 색상은 해당 서브에이전트의 보더 색상과 동일하게 적용한다. 이를 통해 여러 서브에이전트의 도구 호출이 교차 수신될 때에도 각 호출의 소속을 즉시 식별할 수 있다.
- `subagent` 필드가 포함된 `tool.invoke.request`(서브에이전트를 호출하는 도구 자체)는 일반 도구 호출과 시각적으로 구분해야 한다 (MUST). 예: 도구명 옆에 `Subagent` 배지 또는 전용 아이콘.

#### 4.10.6. 동시 실행 그룹핑 (Concurrent Grouping)

여러 서브에이전트가 동시에 실행될 때의 렌더링 규칙을 정의한다.

**인스턴스 식별**: 클라이언트는 `parent_invocation_id`를 기준으로 각 서브에이전트 인스턴스를 식별하고, 동시에 활성 상태인 인스턴스 수만큼 고유한 보더 색상을 할당해야 한다 (MUST). 색상 팔레트가 소진되면 순환 재사용한다.

**그룹 단위 렌더링**: 여러 서브에이전트의 메시지가 교차 수신되더라도, 클라이언트는 동일 `parent_invocation_id`의 메시지를 하나의 연속 그룹으로 모아서 렌더링해야 한다 (MUST). 이를 위해 수신 순서와 다르게 표시 순서를 재배치할 수 있다 (MAY). 각 그룹은 출처 라벨(§4.10.3)로 시작하고, 완료된 경우 종료 라벨로 끝난다.

**그룹 배치 순서**: 서브에이전트 그룹의 배치 순서는 해당 인스턴스의 **첫 번째 메시지 수신 시각** 기준으로 정렬한다 (SHOULD). 먼저 시작된 서브에이전트의 그룹이 상단에 위치한다.

**그룹별 접기/펼치기**: 각 서브에이전트 그룹은 독립적으로 접기/펼치기가 가능해야 한다 (MUST). §4.10.4의 규칙을 따른다. 사용자는 관심 있는 서브에이전트만 펼쳐서 확인하고, 나머지는 접어 둘 수 있다.

#### 4.10.7. 서브에이전트 미지원 폴백

- `subagent_context`가 없거나 `null`인 메시지는 좌측 보더 없이 플랫하게 표시해야 한다 (MUST). 이것이 서브에이전트 미지원 에이전트의 기본 동작이다.
- `output_type: "agent_result"`인 `tool.invoke.result`는 `subagent_context` 없이도 서브에이전트 결과임을 암시한다. 이 경우 해당 tool request/result 쌍을 "서브에이전트 호출"로 표시할 수 있다 (MAY). 단, 내부 메시지의 좌측 보더 구분은 불가능하다.

---

## 5. 시스템 메시지 (System Message)

시스템 메시지의 설계 목표는 대화의 맥락과 상태를 **빠짐없이, 직관적으로** 전달하는 것이다. 시스템 메시지는 프로토콜 또는 클라이언트가 생성한 상태 안내로, 대화의 두 참여자(User, Agent) 사이의 메타 정보를 전달한다.

### 5.1. 레이아웃 원칙: 중앙 정렬, 생략 금지

**중앙 정렬**: 시스템 메시지는 대화 영역의 수평 중앙에 정렬해야 한다 (MUST).

**내용 생략 절대 금지 (No Ellipsis, No Truncation)**: 시스템 메시지의 텍스트는 어떠한 경우에도 말줄임표나 텍스트 잘림으로 생략되어서는 안 된다 (MUST NOT).

**짧고 직관적인 메시지**: 시스템 메시지의 본문은 최대한 짧고 직관적으로 작성해야 한다 (MUST). 예: `⏹ 응답이 중지되었습니다`, `⚠ 세션 연결이 끊어졌습니다`.

**긴 내용의 드롭다운 처리**: 시스템 메시지가 한 줄로 표현하기 어려운 상세 정보를 포함하는 경우 다음의 드롭다운 패턴을 적용해야 한다 (MUST):

- **요약 행**: 항상 노출되는 한 줄의 핵심 메시지. 예: `⚠ 도구 실행 실패 — 상세 보기 ▾`
- **상세 영역**: 요약 행 하단에 접힌 상태로 배치. 사용자가 클릭 시 펼쳐져 전체 내용을 표시한다. 펼침 상태에서도 모든 텍스트가 완전히 노출되어야 하며 (MUST), 내부 스크롤이나 추가 생략을 적용해서는 안 된다 (MUST NOT).
- **펼침/접힘 토글**: 요약 행 우측에 화살표(▾/▴)를 배치하여 상세 영역의 존재를 시각적으로 암시한다 (MUST).

**시각적 비중 최소화**: 시스템 메시지는 사용자 메시지나 에이전트 응답보다 시각적 비중이 낮아야 한다 (SHOULD). 작은 폰트 크기, 연한 텍스트 색상, 배경색 없음 등으로 존재감을 줄이되, 완전히 보이지 않을 정도로 숨겨서는 안 된다.

**반응형 너비 확보**: 시스템 메시지 컨테이너의 가용 너비는 대화 영역 전체 폭의 **60% 이상**을 확보해야 한다 (MUST). 최대 너비는 **90% 이내**로 제한해야 한다 (SHOULD). 뷰포트 너비가 480px 이하인 환경에서는 좌우 여백을 최소화(예: 좌우 각 8~12px)하여 텍스트 영역을 우선 확보해야 한다 (SHOULD). 드롭다운 상세 영역은 요약 행과 **동일한 컨테이너 너비**를 유지해야 한다 (MUST).

### 5.2. 사용자 중지 피드백 (Cancellation Feedback)

사용자가 중지 버튼을 눌러 진행 중인 Turn을 취소하면(`control.prompt.cancel` 발송), 클라이언트는 대화 이력에 시스템 메시지를 삽입하여 취소가 실행되었음을 명시적으로 기록해야 한다 (MUST). 이는 대화 이력에 영구적으로 남는 항목이다.

**렌더링 규격**: §5.1의 레이아웃 원칙에 따라 중앙 정렬, 연한 텍스트, 배경색 없음으로 표시한다. 간결한 메시지(예: `⏹ 응답이 중지되었습니다`)를 사용한다.

**삽입 위치 및 타이밍**: 에이전트의 마지막 출력 바로 아래에 삽입해야 한다 (MUST). `control.prompt.cancel` 발송 직후 즉시 표시하여 사용자에게 지체 없이 피드백해야 한다 (SHOULD).

**부분 응답 보존**: 중지 이전까지 수신된 `agent.text.delta` 텍스트는 삭제하지 않고 그대로 유지해야 한다 (MUST).

**에이전트 상태 정리와의 관계**: 시스템 메시지가 삽입되면, §4.7의 에이전트 상태 표시줄은 즉시 제거되어야 한다 (MUST).

### 5.3. 에러 및 경고 메시지

에이전트 에러(`agent.error`), 세션 에러(`session.error`), 연결 단절, 토큰 만료 등의 시스템 이벤트는 시스템 메시지로 표시한다.

**심각도별 시각 차등**:

| 심각도    | 시각 표현                                      | 예시                              |
| --------- | ---------------------------------------------- | --------------------------------- |
| `info`    | 기본 시스템 메시지 스타일 (연한 텍스트)        | `ℹ 세션이 재연결되었습니다`       |
| `warning` | 주황/노랑 계열 아이콘, 텍스트는 기본 색상 유지 | `⚠ 연결이 불안정합니다`           |
| `fatal`   | 빨강 계열 아이콘, 텍스트도 강조 색상 적용      | `❌ 세션이 비정상 종료되었습니다` |

**에러 상세 정보**: 에러 메시지에 기술적 상세가 포함되는 경우, §5.1의 드롭다운 패턴을 적용하여 요약 행 + 접이식 상세 영역으로 구성한다 (MUST).

### 5.4. 세션 이벤트 메시지 (Session Event Messages)

세션 수준의 상태 변경 이벤트(`session.renamed`, `session.deleted`)는 시스템 메시지로 대화 이력에 삽입하여 사용자에게 상태 변화를 명시적으로 전달해야 한다 (MUST). §5.1의 레이아웃 원칙(중앙 정렬, 생략 금지, 시각적 비중 최소화)을 따른다.

#### 5.4.1. 세션 이름 변경 (`session.renamed`)

RAWP-DPS 1.0.1 §7.6.1의 `session.renamed` 이벤트 수신 시, 대화 이력에 시스템 메시지를 삽입해야 한다 (MUST).

**렌더링 규격:**

- **메시지 형식**: `세션 이름이 "{previous_name}"에서 "{name}"으로 변경되었습니다` 형태로 표시한다. `previous_name`이 없으면 `세션 이름이 "{name}"(으)로 변경되었습니다`로 표시한다.
- **심각도**: `info` 수준. §5.3의 `info` 스타일(연한 텍스트)을 적용한다.
- **대화 이력 기록**: 영구적 항목으로 대화 이력에 기록한다. 세션 재연결 시에도 표시되어야 한다.
- **변경 주체 표시**: `renamed_by` 값에 따라 변경 주체를 괄호 안에 부기할 수 있다 (MAY). 예: `세션 이름이 "작업 A"(으)로 변경되었습니다 (원격)`.
- **UI 제목 반영**: 대화 창의 제목 표시줄 또는 세션 목록에 세션 이름이 표시되는 경우, 해당 영역도 즉시 갱신해야 한다 (MUST).

#### 5.4.2. 세션 종료 (`session.deleted`)

RAWP-DPS 1.0.1 §7.7.1의 `session.deleted` 이벤트 수신 시, 대화 이력에 시스템 메시지를 삽입하고 세션의 종료 상태를 시각적으로 확정해야 한다 (MUST).

**렌더링 규격:**

- **`reason`별 메시지:**

| `reason`         | 시스템 메시지 예시                       | 심각도    |
| ---------------- | ---------------------------------------- | --------- |
| `user_request`   | `세션이 종료되었습니다`                  | `info`    |
| `master_request` | `세션이 원격에서 종료되었습니다`         | `info`    |
| `timeout`        | `연결 시간 초과로 세션이 종료되었습니다` | `warning` |
| `error`          | `오류로 인해 세션이 종료되었습니다`      | `fatal`   |

- **심각도별 스타일**: §5.3의 심각도별 시각 차등 규칙을 적용한다.
- **입력 비활성화**: 세션 종료 메시지 표시 후, 입력창을 비활성화하거나 "세션이 종료되었습니다" 플레이스홀더를 표시하여 추가 입력이 불가능함을 명확히 해야 한다 (MUST).
- **에이전트 상태 정리**: §4.7의 에이전트 상태 표시줄이 활성 상태이면 즉시 제거해야 한다 (MUST).
- **진행 중 항목 시각 전환**: 세션 종료 시점에 진행 중이었던 도구 호출 스피너(§4.5.2)가 존재하면, 스피너를 중단하고 `cancelled` 상태로 전환하여 표시해야 한다 (MUST). 이는 RAWP-DPS 1.0.1 §7.5.3에서 발송되는 `tool.invoke.result` (status: `"cancelled"`) 수신과 연동된다.
- **대화 이력 기록**: 영구적 항목으로 대화 이력에 기록한다.

### 5.5. 연결 단절 및 복구 피드백 (Disconnect & Recovery Feedback)

WSS Connection이 비정상 종료되거나 재연결에 성공한 경우의 렌더링 규칙을 정의한다. RAWP-DPS 1.0.1 §7.8의 Finalization/Unfinalization 절차와 연동된다.

#### 5.5.1. 연결 단절 시 렌더링 (Finalization)

WSS 단절이 감지되면(RAWP-DPS 1.0.1 §7.8.2) 다음을 수행해야 한다 (MUST):

**시스템 메시지 삽입**: `⚠ 연결이 끊어졌습니다`를 §5.3의 `warning` 심각도 스타일로 대화 이력에 삽입한다. 영구적 항목으로 기록한다.

**스트리밍 텍스트 중단**: 활성 스트리밍 중이던 텍스트(`agent.text.delta`)는 수신된 지점까지 확정하고, 하단 경계 효과(§4.3)를 즉시 제거한다 (MUST). 텍스트 끝에 시각적 절단 표시(예: `…` 또는 흐린 경계선)를 추가하여 텍스트가 완전하지 않음을 나타낼 수 있다 (MAY).

**도구 호출 스피너 전환**: 진행 중이던 도구 호출 스피너를 즉시 중단하고, `cancelled` 상태 표시(§4.5.2의 에러 결과 표시)로 전환해야 한다 (MUST). 합성된 cancelled 결과(RAWP-DPS 1.0.1 §7.8.1의 `synthetic: true`)는 연한 회색 텍스트로 `연결 끊김으로 취소됨` 등의 메시지를 표시한다.

**사고 과정 중단**: 활성 Thinking Indicator(§4.4)를 즉시 중단하고 접힌 상태로 전환해야 한다 (MUST).

**에이전트 상태 표시줄 제거**: §4.7의 상태 표시줄을 즉시 제거하고 입력 가능 상태로 복원해야 한다 (MUST).

**상호작용 요청 폐기**: 활성 상태인 상호작용 UI(승인 버튼, 선택 팝업 등)를 즉시 닫고, 해당 영역에 `연결 끊김으로 취소됨`을 표시해야 한다 (MUST).

#### 5.5.2. 재연결 시 렌더링 (Unfinalization)

WSS 재연결이 성공하고 `session.history`(RAWP-DPS 1.0.1 §7.1.1)를 수신하면 다음을 수행해야 한다 (MUST):

**시스템 메시지 삽입**: `ℹ 연결이 복구되었습니다`를 §5.3의 `info` 심각도 스타일로 대화 이력에 삽입한다.

**합성 블록 제거**: Finalization에서 삽입한 합성 cancelled 결과(`synthetic: true`)를 제거하고, `session.history`의 실제 프레임으로 대체한다 (MUST).

**스트리밍 재개**: `session.history` 재생 후 에이전트가 응답을 계속 생성 중이면(새 `agent.text.delta` 수신), 스트리밍 렌더링을 정상 재개한다.

**복구 불가 시**: `session.history`의 `buffer_status.truncated`가 `true`이면, `⚠ 일부 메시지가 유실되었습니다`를 `warning` 심각도로 추가 표시해야 한다 (MUST). 합성 블록은 제거하지 않고 유지한다.

---

## 6. 비스트리밍/완성형 환경 적응 (Non-Streaming Environments)

WebSocket을 지원하지 않아 단일 메시지로만 응답을 렌더링해야 하는 서드파티 플랫폼 연동 게이트웨이(Discord, Slack, Webhook 등)에 대한 지침이다. §2~§5의 원칙은 이러한 환경에서도 최대한 준수하되, 플랫폼 제약에 따라 다음과 같이 적응한다.

### 6.1. 플랫폼 네이티브 상태 지시기 (Typing Indicator) 활용

슬랙(Slack), 디스코드(Discord) 등 대부분의 메신저 플랫폼은 자체적으로 '입력 중(Typing...)' 네이티브 UX 상태 지시기를 제공한다. 점진적 텍스트 렌더링이 불가능한 환경에서는 이러한 플랫폼 네이티브 기능을 최대한 활용하여 사용자에게 지연에 대한 시각적 피드백을 제공해야 한다 (MUST).

**이벤트-지시기 매핑**:

| 수신 이벤트                               | 지시기 동작                                 | 비고                                                                                       |
| ----------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `session.turn.start`                      | '입력 중' 활성화 시작                       | 주기적 갱신 개시                                                                           |
| `agent.thinking.delta`                    | '입력 중' 유지                              | 사고 중에도 활성 유지                                                                      |
| `tool.invoke.request`                     | '입력 중' 유지 또는 커스텀 상태 메시지 발송 | 플랫폼이 상태 메시지를 지원하면 "🔧 도구 실행 중…" 등의 임시 메시지를 발송할 수 있다 (MAY) |
| `agent.text.done` 또는 `session.turn.end` | '입력 중' 해제                              | 최종 메시지 발송과 동시에 해제                                                             |
| `agent.error` (severity: `fatal`)         | '입력 중' 즉시 해제                         | 에러 메시지로 대체                                                                         |

**주기적 갱신(Heartbeat)**: 대부분의 플랫폼은 '입력 중' 상태가 일정 시간(5~10초) 후 자동 만료된다. 게이트웨이는 Turn이 진행 중인 동안 플랫폼의 만료 주기보다 짧은 간격(예: 3~5초)으로 '입력 중' API를 반복 호출하여 상태를 유지해야 한다 (MUST).

**장시간 작업 대응**: 에이전트 응답이 30초 이상 지연될 경우, 중간 상태 메시지 발송 또는 리액션/이모지 업데이트(⏳ → ✅)로 진행 상황을 보강해야 한다 (SHOULD).

### 6.2. 버퍼링 및 일괄 발송 (Buffered Rendering)

게이트웨이는 `agent.text.delta`를 메모리에 버퍼링하고, 조립된 전체 텍스트를 단일 메시지로 플랫폼에 발송해야 한다 (MUST).

**플랫폼 제한 대응**: 대상 플랫폼의 단일 메시지 길이 제한(예: Discord 2,000자)을 초과할 경우, 코드 블록이나 문단이 중간에 훼손되지 않도록 논리적 단위로 분할(Chunking)하여 연속 발송해야 한다 (MUST).

### 6.3. 사고 과정 텍스트 우회 처리

비스트리밍 환경에서는 긴 사고 과정 텍스트가 화면을 과도하게 점유할 수 있으므로, 플랫폼에서 지원하는 스포일러 태그(예: `||내용||`)를 활용하여 기본적으로 가려진 상태로 전송하거나, 최종 응답과 별개의 스레드/메시지로 분리하여 발송해야 한다 (SHOULD).

---

## 7. 파일 브라우저 (File Browser)

세션 생성 전에 사용자가 노드와 에이전트를 선택한 후 작업 디렉토리(`workspace_path`)를 지정하기 위한 파일 브라우저 UI 규격이다. RAWP 1.0 §4.5(`POST /v1/fs/browse`) 및 §9.2.6(`POST /v1/edge/nodes/{node_id}/fs/browse`)의 응답 데이터를 시각적으로 렌더링한다.

### 7.1. 용도 및 진입점

파일 브라우저는 세션 생성 워크플로우에서 `workspace_path`를 선택하는 단계에 사용한다.

**진입점**: 노드 선택 → 에이전트 선택 완료 후, "작업 디렉토리 선택" 버튼 또는 자동 트리거로 모달 다이얼로그를 표시해야 한다 (MUST). 다이얼로그는 트리 뷰(§7.2), 경로 브레드크럼(§7.3), 수동 입력 필드(§7.6)를 포함한다.

**초기 로딩**: 다이얼로그가 열리면 `path` 생략 모드(루트 탐색)로 API를 호출하여 초기 트리를 구성해야 한다 (MUST).

### 7.2. 트리 뷰 컴포넌트

재귀적 트리 구조의 파일시스템 항목을 렌더링하는 핵심 컴포넌트다. `entries` 배열의 재귀 `children` 구조를 그대로 반영한다.

#### 7.2.1. 항목 렌더링

각 Entry 항목은 한 줄로 렌더링하며, 다음 요소를 좌측에서 우측 순서로 배치해야 한다 (MUST):

| 순서 | 요소              | 규칙                                                                                                                                            |
| ---- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | 들여쓰기          | 트리 깊이당 16~24px 패딩. 시각적 계층 구조를 명확히 전달한다 (MUST).                                                                            |
| 2    | 펼침/접기 chevron | 디렉토리(`directory`, `symlink_directory`)에만 표시. `▶`(접힌 상태) / `▼`(펼친 상태). 파일 항목에는 chevron 영역만큼 빈 공간을 유지한다 (MUST). |
| 3    | 아이콘            | §7.2.3의 아이콘 매핑에 따라 타입별 아이콘을 표시한다 (MUST).                                                                                    |
| 4    | 이름              | `entry.name`을 표시한다. `readable: false`인 항목은 연한 색상(muted color)으로 렌더링하고 잠금 아이콘(🔒)을 우측에 병기한다 (MUST).             |
| 5    | 부가 정보         | 파일 항목에 한해 `size`를 사람이 읽기 쉬운 단위(KB, MB 등)로 우측 정렬 표시한다 (SHOULD).                                                       |

**호버 및 선택 스타일**: 항목 호버 시 배경색 변경으로 포커스를 표시해야 한다 (MUST). 현재 선택된 디렉토리는 강조 배경색과 좌측 보더(2~3px, primary color)로 구분한다 (MUST).

#### 7.2.2. 디렉토리 펼침/접기

- chevron 클릭 또는 디렉토리 더블 클릭으로 펼침/접기를 토글한다 (MUST).
- 이미 `children`이 로딩된 디렉토리는 즉시 토글한다. `children`이 없고 깊이 경계에 해당하는 디렉토리는 API를 재호출하여 하위를 로딩한다 (Lazy Expansion).
- Lazy Expansion 중에는 해당 디렉토리의 chevron을 스피너로 교체하여 로딩 상태를 표시해야 한다 (MUST).
- 로딩 실패 시 chevron을 원래 상태로 복원하고 해당 항목 하위에 인라인 에러 메시지를 표시한다 (MUST).

#### 7.2.3. 아이콘 매핑

항목의 `type` 필드에 따라 아이콘을 매핑한다 (MUST):

| type                | 아이콘        | 비고                                    |
| ------------------- | ------------- | --------------------------------------- |
| `directory`         | 📁 폴더       | 펼친 상태 시 📂(열린 폴더)로 전환 (MAY) |
| `file`              | 📄 파일       | 확장자별 세분화는 구현에 위임 (MAY)     |
| `symlink_directory` | 📁↗ 폴더+링크 | 링크 표시를 겸한 폴더 아이콘            |
| `symlink_file`      | 📄↗ 파일+링크 | 링크 표시를 겸한 파일 아이콘            |

아이콘 세트는 구현체의 디자인 시스템에 위임하되, 타입 간 시각적 구분이 가능해야 한다 (MUST).

### 7.3. 경로 브레드크럼

트리 뷰 상단에 현재 탐색 경로를 브레드크럼 형태로 표시해야 한다 (MUST).

- 각 경로 세그먼트는 클릭 가능하며, 클릭 시 해당 레벨로 트리 뷰를 이동한다 (MUST).
- 경로 구분자는 `os_type`에 따라 결정한다: `unix` → `/`, `windows` → `\`.
- 루트 모드(`base_path`가 빈 문자열)에서는 OS 루트 아이콘(🖥 또는 컴퓨터 아이콘)을 최좌측에 표시한다 (SHOULD).
- Windows 환경에서 드라이브 문자(`C:\`, `D:\` 등)는 최상위 브레드크럼 세그먼트로 표시한다 (MUST).
- 경로가 길어 한 줄을 초과할 경우, 중간 세그먼트를 `…`으로 축약하되 첫 세그먼트와 마지막 2개 세그먼트는 항상 표시한다 (SHOULD).

### 7.4. 로딩 및 에러 상태

**초기 로딩**: 트리 뷰 영역 전체에 중앙 정렬 스피너를 표시해야 한다 (MUST). 로딩 중에도 수동 입력 필드(§7.6)는 사용 가능해야 한다 (SHOULD).

**Lazy Expansion 로딩**: §7.2.2에 따라 해당 디렉토리의 chevron을 스피너로 교체한다.

**에러 상태**:

| 상황                          | 렌더링                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| 노드 오프라인                 | 트리 뷰 전체를 에러 패널로 교체. "노드에 연결할 수 없습니다" 메시지와 재시도 버튼 표시 (MUST).          |
| 권한 없음 (`readable: false`) | 해당 항목에 잠금 아이콘(🔒)과 tooltip("접근 권한 없음")을 표시. 디렉토리인 경우 펼침을 비활성화 (MUST). |
| 심링크 순환                   | 해당 항목을 비활성(disabled) 상태로 렌더링하고 tooltip("순환 심링크")을 표시한다 (MUST).                |
| Truncation                    | 잘린 디렉토리 하위에 "외 N개 항목" 안내를 표시한다 (MUST). `total_children_count` 활용.                 |
| API 타임아웃/5xx              | 부분 결과가 있으면 표시하고 하단에 "일부 항목을 불러오지 못했습니다" 경고를 표시한다 (SHOULD).          |

### 7.5. 키보드 내비게이션

파일 브라우저는 WAI-ARIA Treeview 패턴을 준수해야 한다 (MUST):

| 키        | 동작                                                             |
| --------- | ---------------------------------------------------------------- |
| `↑` / `↓` | 트리 항목 간 포커스 이동                                         |
| `→`       | 포커스된 디렉토리 펼침. 이미 펼쳐져 있으면 첫 번째 자식으로 이동 |
| `←`       | 포커스된 디렉토리 접기. 이미 접혀 있으면 부모 디렉토리로 이동    |
| `Enter`   | 포커스된 디렉토리를 `workspace_path`로 선택                      |
| `Space`   | 포커스된 디렉토리 펼침/접기 토글                                 |
| `Home`    | 트리의 첫 번째 항목으로 이동                                     |
| `End`     | 트리의 마지막 가시 항목으로 이동                                 |
| `Esc`     | 파일 브라우저 다이얼로그 닫기                                    |

파일(`type: "file"`)은 포커스는 가능하나 `Enter`로 선택할 수 없다 (MUST). 디렉토리만 `workspace_path`로 선택 가능하다.

### 7.6. 작업 디렉토리 선택

**트리에서 선택**: 디렉토리를 클릭(싱글 클릭)하면 해당 항목을 선택 상태로 표시하고, "선택" 버튼 클릭 또는 `Enter` 키로 확정한다 (MUST). 확정 시 선택된 디렉토리의 `path`를 세션 생성 폼의 `workspace_path`에 반영하고 다이얼로그를 닫는다.

**수동 입력**: 트리 뷰 하단 또는 상단에 텍스트 입력 필드를 제공해야 한다 (MUST). 사용자가 절대 경로를 직접 입력하여 `workspace_path`를 지정할 수 있다.

- 입력 필드에 경로를 입력하면, 클라이언트는 해당 경로가 에이전트의 `allowed_directories` 범위 내인지 클라이언트 측에서 사전 검증해야 한다 (MUST).
- 범위 밖 경로 입력 시 인라인 경고("허용된 디렉토리 범위 밖입니다")를 표시하고 선택 버튼을 비활성화한다 (MUST).
- 유효한 경로 입력 시 트리 뷰를 해당 경로로 자동 이동하여 시각적 확인을 제공한다 (SHOULD).

### 7.7. 빈 상태 처리

에이전트의 `allowed_directories`가 빈 배열이거나 모든 경로에 접근 권한이 없는 경우, 트리 뷰 영역에 다음을 표시해야 한다 (MUST):

- "탐색 가능한 디렉토리가 없습니다" 안내 메시지
- 수동 입력 필드로의 안내 텍스트

`allowed_directories`가 미설정(제한 없음)인 경우에는 OS 루트부터 정상적으로 트리를 표시한다.

---

## 부록: 관련 규격 문서

| 문서                    | 설명                                                                        |
| ----------------------- | --------------------------------------------------------------------------- |
| **RAWP 1.0.3**          | 원격 에이전트 제어 프로토콜 (상위 규격). 본 문서의 상위 문서.               |
| **RAWP-DPS 1.0.1**      | 데이터 평면 스트리밍 규격. 본 문서가 참조하는 이벤트 타입 및 페이로드 정의. |
| **RAWP-DPS-0.1-Legacy** | 데이터 평면 스트리밍 규격 (단종 예고). 레거시 호환용.                       |