---
domain: widgets
last_rule_review_commit: 09080ca7f67c07b5b9227de78ca11c6d6018c13f
last_rule_updated_at: 2026-05-31
---

# widgets

## 목적 / 책임

AgentShell을 구성하는 embeddable Flutter UI primitives를 제공한다. 메시지 목록, composer, tool call card, approval prompt를 host 앱의 workbench layout 안에 자연스럽게 들어갈 수 있는 위젯으로 유지한다.

## 포함 경로

- `lib/src/widgets/` — agent shell의 Flutter widget 구현을 둔다.

## 제외 경로

- `lib/src/domain/` — UI와 무관한 계약과 상태 모델은 domain-model 도메인이다.
- application bootstrap — `runApp`, `MaterialApp`, Firebase/SystemChrome 초기화는 host 앱 책임이다.

## 주요 구성 요소

- `AgentShell` — message list와 composer를 조립하는 embeddable surface.
- `AgentComposer` — 사용자 입력과 submit callback을 제공한다.
- `AgentMessageList` — agent/user/tool 메시지를 표시한다.
- `ToolCallCard` — tool call 상태, arguments, result/error, approval prompt를 표시한다.
- `ApprovalPrompt` — approve/reject action을 host callback으로 전달한다.

## 유지할 패턴

- 위젯은 host theme를 사용하고 자체 app chrome을 만들지 않는다.
- rail, tab, center content, modal 같은 다양한 host container에 들어갈 수 있도록 크기와 padding을 보수적으로 둔다.
- action은 callback으로 host에 전달하고, backend/transport를 직접 호출하지 않는다.

## 다른 도메인과의 경계

- **domain-model**: widgets는 domain model을 표시하고 사용자 action을 callback으로 전달한다. 상태 계약 자체를 이 도메인에서 새로 정의하지 않는다.
- **host app**: host app은 navigation, persistence, runtime connection, auth, capability registry 조립을 소유한다.

## 금지 사항

- `MaterialApp`, `Navigator` root, global theme, platform bootstrap을 widgets 안에 만들지 않는다.
- IOP/NomadCode 전용 layout이나 WebView 조작 UI를 직접 넣지 않는다.
- tool approval을 위젯 내부에서 자동 승인하거나 실행하지 않는다.