simplex-chat/apps/multiplatform/spec/client/chat-view.md

Chat View Specification

Source: common/src/commonMain/kotlin/chat/simplex/common/views/chat/ChatView.kt

---

Table of Contents

1. Overview
2. ChatView Composable
3. Message List
4. ChatItemView
5. Message Types
6. Context Menu Actions
7. ChatInfoView
8. GroupChatInfoView
9. Source Files

---

Executive Summary

The Chat View is the primary message display and interaction surface in SimpleX Chat. It is built around the ChatView composable (line ~96 in ChatView.kt), which orchestrates a ChatLayout containing a reverse-scrolling LazyColumn of ChatItemView items and a ComposeView for message input. The view supports direct chats, group chats, local notes, and contact connections, with per-chat theming, search/filter, multi-select, and side-panel info modals. Message rendering is delegated to type-specific composables in the views/chat/item/ package.

---

1. Overview

ChatView
|-- ChatLayout
|   |-- ChatInfoToolbar            (top/bottom app bar with back, title, call, search, menu)
|   |-- SupportChatsCountToolbar   (reports/support banner, group only)
|   |-- ChatItemsList              (LazyColumnWithScrollBar, reverse layout)
|   |   |-- ChatViewListItem
|   |   |   |-- DateSeparator
|   |   |   |-- MemberNameAndRole  (group received messages)
|   |   |   |-- MemberImage        (group received messages)
|   |   |   +-- ChatItemView       (message type routing)
|   |   |-- ChatBannerView         (first item: chat profile banner)
|   |   +-- FloatingButtons        (scroll-to-bottom, unread counter)
|   |-- ComposeView               (message composition area)
|   |   |-- ContextItemView        (reply/edit/forward/report indicator)
|   |   |-- previewView            (link/media/voice/file preview)
|   |   +-- SendMsgView            (text input + send/voice/timed buttons)
|   |-- GroupMentions              (mention autocomplete popup)
|   |-- CommandsMenuView           (bot commands popup)
|   +-- ChooseAttachmentView       (bottom sheet for attachment type)
|-- ChatInfoView                   (contact info, end modal)
+-- GroupChatInfoView              (group management, end modal)

---

2. ChatView Composable

Location: ChatView.kt#L97

fun ChatView(
  chatsCtx: ChatModel.ChatsContext,
  staleChatId: State<String?>,
  scrollToItemId: MutableState<Long?>,
  onComposed: suspend (chatId: String) -> Unit
)

State Management

State Variable	Type	Purpose
showSearch	MutableState<Boolean>	Controls search bar visibility
searchText	MutableState<String>	Current search query text
composeState	MutableState<ComposeState>	Full compose area state (message, preview, context, mentions)
attachmentOption	MutableState<AttachmentOption?>	Selected attachment type from bottom sheet
selectedChatItems	MutableState<Set<Long>?>	Multi-select mode item IDs; null = selection off
showCommandsMenu	MutableState<Boolean>	Bot commands menu visibility
contentFilter	MutableState<ContentFilter?>	Active content type filter (images, videos, etc.)
availableContent	MutableState<List<ContentFilter>>	Content types available in this chat
activeChat	State<Chat?>	Derived from chatModel.chats matching staleChatId
unreadCount	State<Int>	Unread message count derived from chat stats

Chat Loading

On chat ID change (via snapshotFlow on chatModel.chatId.value, line ~162):

1. Marks unread chat as read (markUnreadChatAsRead)
2. Clears group members state
3. Resets search, content filter, and selection
4. Fetches available content types (updateAvailableContent)
5. For direct chats, loads contact info and connection stats
6. For groups with pending membership, opens member support chat

Chat Type Routing

The outer when (chatInfo) (line ~229) branches:

ChatInfo Type	Behavior
ChatInfo.Direct, ChatInfo.Group, ChatInfo.Local	Full ChatLayout with compose, search, reactions, per-chat theme
ChatInfo.ContactConnection	ModalView wrapping ContactConnectionInfoView
ChatInfo.InvalidJSON	ModalView with raw JSON display and share button

---

3. Message List

Location: ChatView.kt#L1592 (ChatItemsList composable)

The message list is a LazyColumnWithScrollBar with reverseLayout = true, meaning index 0 is the newest message at the bottom of the screen.

Key Behaviors

• Merged Items: Messages are grouped via MergedItems.create() (line ~1653), which collapses consecutive similar system events into expandable groups. Revealed state is tracked in revealedItems.
• Pagination: PreloadItems triggers loadMessages with ChatPagination.Before (older) or ChatPagination.Last (newer) when the user scrolls near list boundaries.
• Scroll To Item: scrollToItem lambda supports animated scrolling to a specific item ID, used by search result taps and quoted message navigation.
• Unread Marking: MarkItemsReadAfterDelay composable marks newly visible received items as read after a brief delay.
• Date Separators: DateSeparator composable renders between messages when the date changes (via ItemSeparation.date).
• Swipe to Reply: SwipeToDismiss modifier on each item (EndToStart direction, 30dp threshold) sets ComposeContextItem.QuotedItem.
• Selection Mode: When selectedChatItems is non-null, a checkbox overlay appears on each item; a full-width clickable overlay toggles selection.

Item Layout (ChatViewListItem)

• Group received messages with showAvatar = true: Column layout with MemberNameAndRole header, MemberImage (clickable to showMemberInfo), and message bubble.
• Group received without avatar: Indented to align with avatar-bearing messages.
• Sent messages (group or direct): Right-aligned with larger start padding.
• Direct messages: Symmetric padding (76dp opposite side).

---

4. ChatItemView

Location: item/ChatItemView.kt#L66

fun ChatItemView(
  chatsCtx, rhId, chat, cItem, composeState, imageProvider,
  useLinkPreviews, linkMode, revealed, highlighted, hoveredItemId,
  range, selectedChatItems, searchIsNotBlank, fillMaxWidth,
  selectChatItem, deleteMessage, deleteMessages, archiveReports,
  receiveFile, cancelFile, joinGroup, acceptCall, acceptFeature,
  openDirectChat, forwardItem, scrollToItem, scrollToItemId,
  scrollToQuotedItemFromItem, setReaction, showItemDetails,
  reveal, showMemberInfo, showChatInfo, developerTools, showViaProxy,
  showTimestamp, itemSeparation, ...
)

The composable routes based on cItem.content and cItem.meta.itemDeleted:

• Deleted items -> DeletedItemView or MarkedDeletedItemView
• Message content (SndMsgContent, RcvMsgContent) -> FramedItemView or specialized views depending on msgContent type
• Call items -> CICallItemView
• Integrity/decryption errors -> IntegrityErrorItemView, CIRcvDecryptionError
• Group invitations -> CIGroupInvitationView
• Events (group/direct/connection events) -> CIEventView
• Feature changes -> CIChatFeatureView, CIFeaturePreferenceView
• E2EE info -> CIEventView
• Chat banner -> handled at list level, not in ChatItemView
• Invalid JSON -> CIInvalidJSONView

Reactions

ChatItemReactions row renders below each message bubble, showing emoji reaction counts. Tapping own reactions removes them; tapping others' opens a member list dropdown.

Context Menu

Long-press or right-click opens a dropdown menu with context-sensitive actions (see section 6).

---

5. Message Types

CIContent Variant	MsgContent Type	View Composable	Source File
SndMsgContent / RcvMsgContent	MCText	FramedItemView -> TextItemView or EmojiItemView	TextItemView.kt, EmojiItemView.kt
SndMsgContent / RcvMsgContent	MCLink	FramedItemView (with link preview)	FramedItemView.kt
SndMsgContent / RcvMsgContent	MCImage	CIImageView (inside FramedItemView)	CIImageView.kt
SndMsgContent / RcvMsgContent	MCVideo	CIVideoView (inside FramedItemView)	CIVideoView.kt
SndMsgContent / RcvMsgContent	MCVoice	CIVoiceView	CIVoiceView.kt
SndMsgContent / RcvMsgContent	MCFile	CIFileView	CIFileView.kt
SndMsgContent / RcvMsgContent	MCReport	FramedItemView (with report styling)	FramedItemView.kt
SndCall / RcvCall	--	CICallItemView	CICallItemView.kt
RcvIntegrityError	--	IntegrityErrorItemView	IntegrityErrorItemView.kt
RcvDecryptionError	--	CIRcvDecryptionError	CIRcvDecryptionError.kt
RcvGroupInvitation / SndGroupInvitation	--	CIGroupInvitationView	CIGroupInvitationView.kt
RcvDirectEventContent	--	CIEventView	CIEventView.kt
RcvGroupEventContent / SndGroupEventContent	--	CIEventView	CIEventView.kt
RcvConnEventContent / SndConnEventContent	--	CIEventView	CIEventView.kt
RcvChatFeature / SndChatFeature	--	CIChatFeatureView	CIChatFeatureView.kt
RcvChatPreference / SndChatPreference	--	CIFeaturePreferenceView	CIFeaturePreferenceView.kt
RcvGroupFeature / SndGroupFeature	--	CIChatFeatureView	CIChatFeatureView.kt
SndModerated / RcvModerated / RcvBlocked	--	MarkedDeletedItemView	MarkedDeletedItemView.kt
SndDirectE2EEInfo / RcvDirectE2EEInfo	--	CIEventView	CIEventView.kt
SndGroupE2EEInfo / RcvGroupE2EEInfo	--	CIEventView	CIEventView.kt
RcvChatFeatureRejected / RcvGroupFeatureRejected	--	CIChatFeatureView	CIChatFeatureView.kt
ChatBanner	--	ChatBannerView (inline in ChatItemsList)	ChatView.kt
InvalidJSON	--	CIInvalidJSONView	CIInvalidJSONView.kt
CIMemberCreatedContact	--	CIMemberCreatedContactView	CIMemberCreatedContactView.kt

Animated Images

SimpleAndAnimatedImageView is expect/actual. Android delegates to coil, which drives the animation itself. Desktop decodes frames with Skia's Codec in platform/AnimatedImage.desktop.kt, where rememberAnimatedImage(data, still, hidden) returns the frame to draw and falls back to the still image when the data is not an animation, exceeds the decode bounds, or fails before showing a frame. Decoding runs off the UI thread on two threads of the shared pool, and pauses while the window is minimized or hidden, while the image is behind the privacy blur, and while a full screen modal covers the chat. An animation whose frames cost too much to decode stops on the frame it reached rather than falling back to the still. The chat list preview (smallView) stays a still image. Only GIF reaches this path: desktop decodes stills with ImageIO, which has no WebP reader, so a received .webp renders only as the sender's preview and never opens full screen.

---

6. Context Menu Actions

Context menu actions are built dynamically in ChatItemView based on message type, direction, chat type, and feature flags.

Action	Condition	Effect
Reply	Message content (not event/deleted), not local notes	Sets ComposeContextItem.QuotedItem
Edit	Sent message, editable (meta.editable), text/link content	Sets ComposeContextItem.EditingItem
Delete for me	Any deletable item	apiDeleteChatItems with cidmInternal mode
Delete for everyone	Sent + within time window, or moderator privilege	apiDeleteChatItems with cidmBroadcast mode
Moderate	Group moderator + received message	apiDeleteMemberChatItems
Forward	Message content, not live message	Opens share sheet via SharedContent.Forward
Select	Any selectable item	Enters multi-select mode (selectedChatItems)
React	Message content, reactions enabled	Opens emoji picker; calls apiChatItemReaction
Report	Received group message, reports enabled	Sets ComposeContextItem.ReportedItem with reason
Info	Any message	Opens ChatItemInfoView in end modal
Copy	Text content present	Copies text to clipboard
Save	Image/video/file with completed download	Saves media to device
Open	File with completed download	Opens file with system handler
Reveal / Hide	Part of a merged group; expanded or collapsed	Toggles revealedItems state

---

7. ChatInfoView

Location: ChatInfoView.kt

Opened via the info callback when the user taps the toolbar title in a direct chat. Displayed in ModalManager.end.

Preloads apiContactInfo (connection stats, server profile) and apiGetContactCode (verification code) before showing the modal.

Key sections: contact profile, local alias, connection stats, shared media, disappearing messages preference, voice/call/file feature toggles, encryption verification, and contact deletion.

---

8. GroupChatInfoView

Location: group/GroupChatInfoView.kt

Opened via the info callback for group chats. Displayed in ModalManager.end.

Preloads group members (setGroupMembers) and group link (apiGetGroupLink).

Key sections: group profile, group link, member list with roles, group preferences (disappearing messages, direct messages, full deletion, voice, files, SimpleX links, history), member admission, welcome message, reports view, and group deletion/leave.

---

9. Source Files

views/chat/

File	Description
ChatView.kt	Main chat view, ChatLayout, ChatItemsList, ChatInfoToolbar
ChatInfoView.kt	Contact info modal
ChatItemInfoView.kt	Individual message delivery/read info
ChatItemsLoader.kt	Pagination and message loading logic
ChatItemsMerger.kt	MergedItems grouping of consecutive events
CommandsMenuView.kt	Bot /command menu popup
ComposeContextContactRequestActionsView.kt	Contact request action buttons in compose area
ComposeContextGroupDirectInvitationActionsView.kt	Group direct invitation compose actions
ComposeContextPendingMemberActionsView.kt	Pending member compose actions
ComposeContextProfilePickerView.kt	Profile picker in compose context
ComposeFileView.kt	File attachment preview in compose
ComposeImageView.kt	Image/video attachment preview in compose
ComposeView.kt	Main compose area (ComposeState, send logic)
ComposeVoiceView.kt	Voice recording preview in compose
ContactPreferences.kt	Per-contact feature preferences
ContextItemView.kt	Reply/edit/forward context indicator
ScanCodeView.kt	QR code scanner
SelectableChatItemToolbars.kt	Multi-select toolbar (delete, forward, moderate)
SendMsgView.kt	Text input field, send button, voice record button
VerifyCodeView.kt	Contact/member encryption verification

views/chat/item/

File	Description
ChatItemView.kt	Message type routing, context menu, reactions
CIBrokenComposableView.kt	Fallback for rendering errors
CICallItemView.kt	Call event display (incoming/outgoing/missed)
CIChatFeatureView.kt	Chat feature change event
CIEventView.kt	Generic event display (group/direct/connection)
CIFeaturePreferenceView.kt	Feature preference change event
CIFileView.kt	File message (download/upload progress)
CIGroupInvitationView.kt	Group invitation card
CIImageView.kt	Image message (thumbnail + fullscreen)
CIInvalidJSONView.kt	Invalid JSON fallback display
CIMemberCreatedContactView.kt	Member-created contact event
CIMetaView.kt	Message metadata (time, status indicators)
CIRcvDecryptionError.kt	Decryption error display
CIVideoView.kt	Video message (thumbnail + player)
CIVoiceView.kt	Voice message (waveform + player)
DeletedItemView.kt	Deleted message placeholder
EmojiItemView.kt	Large emoji-only message
FramedItemView.kt	Message bubble frame (quoted item, text, media)
ImageFullScreenView.kt	Fullscreen image gallery
IntegrityErrorItemView.kt	Message integrity error
MarkedDeletedItemView.kt	Marked-as-deleted / moderated message
TextItemView.kt	Plain text message with markdown

views/chat/group/

File	Description
AddGroupMembersView.kt	Add members to group
GroupChatInfoView.kt	Group info and management
GroupLinkView.kt	Group link display and management
GroupMemberInfoView.kt	Individual member info
GroupMembersToolbar.kt	Members toolbar in group info
GroupMentions.kt	@mention autocomplete
GroupPreferences.kt	Group feature preferences
GroupProfileView.kt	Group profile editor
GroupReportsView.kt	Group reports list view
MemberAdmission.kt	Member admission settings
MemberSupportChatView.kt	Member support chat (scoped context)
MemberSupportView.kt	Support chat list for moderators
WelcomeMessageView.kt	Group welcome message editor
ChannelRelaysView.kt	Channel relay list. Owner-only Add relay entry opens AddGroupRelayView with existingRelayIds = groupRelays.mapNotNull { it.userChatRelay.chatRelayId }.toSet() — every relay currently in groupRelays is excluded regardless of relayStatus, mirroring the backend APIAddGroupRelays gate. Long-press menu offers Remove relay for relays that can be removed.
AddGroupRelayView.kt	Sheet to pick relays to add to a channel

Relay Rejection Surface

When a relay operator runs /leave #channel, the relay sends x.grp.relay.reject over the owner-relay direct contact channel. Owner-side handling: the corresponding GroupRelay.relayStatus transitions RSInvited → RSRejected; the relay's GroupMember.memberStatus is set to MemLeft so the owner UI renders the rejected relay identically to one that explicitly ran /leave (MemRejected is reserved for the knocking-admission flow). In GroupMemberInfoView, an additional "Status: rejected by relay operator" InfoRow appears when groupRelay?.relayStatus == RelayStatus.RsRejected. The status is final on the owner side — clearable only by the relay operator running /group allow #<channel>, which has no owner-facing event.

The RelayStatusIndicator composable in AddChannelView.kt renders RsRejected with a red dot and "rejected" text, matching the connFailed/removed rendering.