eigent/src/components/ChatBox/README.md

ChatBox component structure

This document describes the ChatBox layout, how the main pieces connect, and where to change behavior. Paths are relative to src/components/ChatBox/.

Overview

ChatBox is the main chat surface: it wires project + chat store data to message threads, task / workforce UI, and the BottomBox composer. It supports multi-turn flows, task planning, splitting, and execution with scroll and timeline affordances.

Architecture (folders)

ChatBox/
├── index.tsx                 # Main shell: layout, chat timeline, send/stop, BottomBox
├── ChatTimeline.tsx         # Per-project task/chat rail or popover (narrow layout)
├── ProjectChatContainer.tsx  # Scroll region + all chat stores for the active project
├── ProjectSection.tsx        # One chat store: query groups, FloatingAction
├── UserQueryGroup.tsx        # One user query → messages, task UI, agent results
│
├── TaskBox/                 # Plan / run task UI
│   ├── TaskCard.tsx         # Plan list, progress, filter, expand (workforce subtasks)
│   ├── TaskItem.tsx         # Editable line in the plan
│   ├── TaskType.tsx         # Task type indicator
│   ├── TypeCardSkeleton.tsx  # Loading skeleton while the plan is forming
│   └── StreamingTaskList.tsx
│
├── MessageItem/             # All message- and log-specific UI
│   ├── UserMessageCard.tsx
│   ├── UserMessageRichContent.tsx
│   ├── AgentMessageCard.tsx
│   ├── NoticeCard.tsx
│   ├── FeedbackCard.tsx
│   ├── TaskCompletionCard.tsx
│   ├── SplittingProgressRow.tsx   # “Splitting tasks” + token tick during decompose
│   ├── TaskWorkLogAccordion.tsx  # Work log: tool / agent lines (workforce)
│   ├── FloatingAction.tsx        # Pause / skip (used from ProjectSection)
│   ├── MarkDown.tsx
│   ├── SummaryMarkDown.tsx
│   └── TokenUtils.tsx            # Token animation + splitting elapsed formatting
│
└── BottomBox/                # Composer and chrome above input
    ├── index.tsx
    ├── InputBox.tsx
    ├── RichChatInput.tsx
    ├── ModelSelect.tsx
    ├── BoxHeader.tsx
    └── QueuedBox.tsx

Core responsibilities

index.tsx

• Composes ProjectChatContainer, BottomBox, and (when used) ChatTimeline.
• Connects to useChatStoreAdapter, projectStore, navigation, and session chrome (e.g. scroll padding, task time display, pause/resume).
• Owns high-level task operations (send, stop, share, history hooks) and passes props into children.

ProjectChatContainer.tsx

• Renders the stack of per–chat-id sections for the active project.
• Owns scroll behavior and “stick to bottom” / padding for the last message and BottomBox.

ProjectSection.tsx

• One vanilla chatStore instance: subscribes to it and maps messages into query groups (see UserQueryGroup).
• Hosts FloatingAction (pause, skip) for the active task.

UserQueryGroup.tsx

• A single user turn: user content, then downstream UI driven by AgentStep / ChatTaskStatus (e.g. splitting, task card, agent completion, notices).
• Imports from TaskBox/ and MessageItem/; this is the main place new message shapes are routed.

TaskBox (TaskBox/)

• TaskCard: Task type 1/2/3 flows—plan text, taskRunning rows, filter tabs, link to the chat that owns a subtask, expand/collapse with session-backed preference.
• TaskItem: Single plan line edit/delete.
• TypeCardSkeleton: Shown while the model is decomposing before to_sub_tasks is ready.
• StreamingTaskList: Renders running subtasks during streaming / updates.

MessageItem (MessageItem/)

• UserMessageCard / UserMessageRichContent: User bubble + rich blocks.
• AgentMessageCard: Assistant markdown, optional typewriter, attachments.
• SplittingProgressRow: Shown while the task is in the splitting phase; uses store taskTime / elapsed when present, with a per-session wall-clock fallback when not.
• TaskWorkLogAccordion: Collapsible work log for running/finished/paused task (tool activate/deactivate, agent lines); Framer height: auto for expand, stable segment keys from the merged log.
• TaskCompletionCard: Completion / summary style card when appropriate.
• NoticeCard: Chain-of-thought or notice-style content.
• FeedbackCard: Thumbs / feedback when enabled.
• FloatingAction: Compact floating controls (wired from ProjectSection).
• TokenUtils: Animated token number and formatSplittingElapsed helpers.

BottomBox (BottomBox/)

• index.tsx: Wires BoxHeader, InputBox / RichChatInput, QueuedBox to task state (pending, running, confirm, etc.).
• InputBox / RichChatInput / ModelSelect: Text input, model picker, rich input where applicable.
• BoxHeader: Task summary, timing, and header affordances.
• QueuedBox: Queued user messages when the task pipeline is busy.

Data flow (short)

1. User input → BottomBox → index.tsx / store → API or store updates.
2. SSE / store updates → ProjectChatContainer → ProjectSection → UserQueryGroup → MessageItem / TaskBox by step and status.
3. State → chatStore (per chat), projectStore (project + which chat is active), plus local component state (expand, scroll, active query).

Extending the UI

• New agent or system message type: branch in UserQueryGroup.tsx (and possibly ProjectSection if grouping changes).
• New task UI: add under TaskBox/ and mount from UserQueryGroup or TaskCard as needed.
• New bubble content: add a card under MessageItem/ and import it from UserQueryGroup (or the parent that owns that message list).

This layout keeps transport and layout (index, Project*) separate from message rendering (MessageItem/) and task planning/execution (TaskBox/), and composer behavior (BottomBox/).