@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-android-v6-compose-components/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: cometchat-android-v6-compose-components
+description: "CometChat Android UIKit v6 Jetpack Compose component catalog — all @Composable chat UI components, their parameters, styles, and usage"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, compose, components, conversations, messages, users, groups, calls"
+---
+
+> **Companion skills:** cometchat-android-v6-kotlin-components (Views equivalent), cometchat-android-v6-compose-theming, cometchat-android-v6-compose-customization, cometchat-android-v6-compose-placement
+
+## Purpose
+
+Complete catalog of all Jetpack Compose components in CometChat UIKit v6. Each component is a `@Composable` function in `com.cometchat.uikit.compose.presentation`.
+
+## Use this skill when
+
+- Adding a CometChat Compose component to a screen
+- Looking up component parameters and their types
+- Understanding which component to use for a specific chat feature
+- Finding the style class for a component
+
+## Do not use this skill when
+
+- Working with Kotlin Views components (use `cometchat-android-v6-kotlin-components`)
+- Customizing bubble rendering (use `cometchat-android-v6-compose-customization`)
+- Placing components in navigation (use `cometchat-android-v6-compose-placement`)
+
+## 1. Component Catalog
+
+
+### 1.1 List Components
+
+| Component | Package | Purpose |
+|---|---|---|
+| `CometChatConversations` | `presentation.conversations.ui` | Recent conversations list |
+| `CometChatUsers` | `presentation.users.ui` | User list |
+| `CometChatGroups` | `presentation.groups.ui` | Group list |
+| `CometChatGroupMembers` | `presentation.groupmembers.ui` | Members of a group |
+| `CometChatCallLogs` | `presentation.calllogs.ui` | Call history |
+
+### 1.2 Messaging Components
+
+| Component | Package | Purpose |
+|---|---|---|
+| `CometChatMessageList` | `presentation.messagelist.ui` | Message list with bubbles |
+| `CometChatMessageComposer` | `presentation.messagecomposer.ui` | Message input with attachments |
+| `CometChatMessageHeader` | `presentation.messageheader.ui` | Chat header (name, status, actions) |
+| `CometChatMessageInformation` | `presentation.messageinformation.ui` | Message delivery/read info |
+| `CometChatThreadHeader` | `presentation.threadheader.ui` | Thread parent message header |
+
+### 1.3 Call Components
+
+| Component | Package | Purpose |
+|---|---|---|
+| `CometChatCallButtons` | `presentation.callbuttons.ui` | Audio/video call buttons |
+| `CometChatIncomingCall` | `presentation.incomingcall.ui` | Incoming call screen |
+| `CometChatOutgoingCall` | `presentation.outgoingcall.ui` | Outgoing call screen |
+| `CometChatOngoingCall` | `presentation.ongoingcall.ui` | Active call screen |
+| `CometChatCallActivity` | `calls` | Activity wrapper for calls |
+
+### 1.4 Utility Components
+
+| Component | Package | Purpose |
+|---|---|---|
+| `CometChatSearch` | `presentation.search.ui` | Global search |
+| `CometChatReactionList` | `presentation.reactionlist.ui` | Reaction details |
+| `CometChatEmojiKeyboard` | `presentation.emojikeyboard.ui` | Emoji picker |
+| `CometChatStickerKeyboard` | `presentation.stickerkeyboard.ui` | Sticker picker |
+| `CometChatCreatePoll` | `presentation.createpoll.ui` | Poll creation |
+| `CometChatImageViewerScreen` | `presentation.imageviewer.ui` | Full-screen image viewer |
+| `CometChatFlagMessageDialog` | `presentation.report` | Report/flag message |
+| `CometChatAIAssistantChatHistory` | `presentation.aiassistantchathistory.ui` | AI chat history |
+
+### 1.5 Shared Elements
+
+Located in `presentation.shared/`:
+
+- AI features: `aiconversationstarter/`, `aiconversationsummary/`, `aismartreplies/`
+- Message bubble: `messagebubble/` (BubbleFactory, InternalContentRenderer, CometChatMessageBubble)
+- Mentions: `mentions/`
+- Formatters: `formatters/` (CometChatTextFormatter, CometChatMentionsFormatter)
+- Default states: `defaultstates/` (empty, error, loading state composables)
+- Dialog: `dialog/`
+- Popup menu: `popupmenu/`
+
+### 1.6 Preview Support
+
+The `preview/` package provides preview data, domain models, and presentation helpers for `@Preview` composables during development.
+
+## 2. Basic Usage Examples
+
+### 2.1 Conversations List
+
+```kotlin
+import com.cometchat.uikit.compose.presentation.conversations.ui.CometChatConversations
+import com.cometchat.uikit.compose.theme.CometChatTheme
+
+@Composable
+fun ConversationsScreen(onConversationClick: (Conversation) -> Unit) {
+    CometChatTheme {
+        CometChatConversations(
+            onItemClick = { conversation ->
+                onConversationClick(conversation)
+            }
+        )
+    }
+}
+```
+
+### 2.2 Message List
+
+```kotlin
+import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
+import com.cometchat.chat.models.User
+
+@Composable
+fun ChatScreen(user: User) {
+    CometChatTheme {
+        Column {
+            CometChatMessageHeader(user = user)
+            CometChatMessageList(
+                user = user,
+                modifier = Modifier.weight(1f)
+            )
+            CometChatMessageComposer(user = user)
+        }
+    }
+}
+```
+
+### 2.3 Users List
+
+```kotlin
+@Composable
+fun UsersScreen() {
+    CometChatTheme {
+        CometChatUsers(
+            onItemClick = { user ->
+                // Navigate to chat with user
+            }
+        )
+    }
+}
+```
+
+### 2.4 Groups List
+
+```kotlin
+@Composable
+fun GroupsScreen() {
+    CometChatTheme {
+        CometChatGroups(
+            onItemClick = { group ->
+                // Navigate to group chat
+            }
+        )
+    }
+}
+```
+
+## 3. Style Classes
+
+Every component has a corresponding `@Immutable data class` style in its `style/` subpackage:
+
+| Component | Style Class | Factory |
+|---|---|---|
+| `CometChatConversations` | `CometChatConversationsStyle` | `.default()` |
+| `CometChatUsers` | `CometChatUsersStyle` | `.default()` |
+| `CometChatGroups` | `CometChatGroupsStyle` | `.default()` |
+| `CometChatGroupMembers` | `CometChatGroupMembersStyle` | `.default()` |
+| `CometChatMessageList` | `CometChatMessageListStyle` | `.default()` |
+| `CometChatMessageComposer` | `CometChatMessageComposerStyle` | `.default()` |
+| `CometChatMessageHeader` | `CometChatMessageHeaderStyle` | `.default()` |
+| `CometChatCallLogs` | `CometChatCallLogsStyle` | `.default()` |
+| `CometChatThreadHeader` | `CometChatThreadHeaderStyle` | `.default()` |
+
+Usage:
+
+```kotlin
+CometChatConversations(
+    style = CometChatConversationsStyle.default(
+        backgroundColor = Color.White,
+        titleTextColor = Color.Black,
+        titleTextStyle = CometChatTheme.typography.heading1Bold
+    )
+)
+```
+
+## 4. ViewModel Integration
+
+Each component creates its own ViewModel internally via factories from `chatuikit-core`. The ViewModels expose `StateFlow` of sealed UI state classes. You typically don't need to interact with ViewModels directly — the components handle everything.
+
+## Hard rules
+
+- ALWAYS wrap CometChat Compose components in `CometChatTheme {}` — they depend on `CompositionLocal` theme values
+- Components create their own ViewModels internally — do NOT try to create or inject ViewModels manually
+- Style classes use `Companion.default()` factory functions — do NOT use the data class constructor directly (it requires all parameters)
+- All style defaults source from `CometChatTheme` tokens — override only what you need via named parameters

package/skills/cometchat-android-v6-compose-customization/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: cometchat-android-v6-compose-customization
+description: "CometChat Android UIKit v6 Compose customization — BubbleFactory interface, slot lambdas, @Immutable style classes, and per-slot overrides"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, compose, customization, bubble-factory, slots, style"
+---
+
+> **Companion skills:** cometchat-android-v6-kotlin-customization (Views equivalent), cometchat-android-v6-compose-components, cometchat-android-v6-compose-theming, cometchat-android-v6-extensions (DataSource layer), cometchat-android-v6-events
+
+## Purpose
+
+Customize CometChat Compose components — override message bubble rendering with BubbleFactory, use slot lambda parameters for per-slot overrides, and apply @Immutable style classes. This is the v6 replacement for v5's DataSource/ChatConfigurator pattern.
+
+## Use this skill when
+
+- Creating custom message bubble rendering for specific message types
+- Overriding individual bubble slots (avatar, header, footer, content, etc.)
+- Applying custom styles to components
+- Replacing the entire bubble layout for a message type
+
+## Do not use this skill when
+
+- Working with Kotlin Views customization (use `cometchat-android-v6-kotlin-customization`)
+- Changing theme colors globally (use `cometchat-android-v6-compose-theming`)
+- Extending the data layer (use `cometchat-android-v6-extensions`)
+
+## 1. BubbleFactory (Message Bubble Customization)
+
+`BubbleFactory` is an interface in `com.cometchat.uikit.compose.presentation.shared.messagebubble`. Each implementation handles a specific message type.
+
+### 1.1 Creating a Custom BubbleFactory
+
+```kotlin
+import com.cometchat.uikit.compose.presentation.shared.messagebubble.BubbleFactory
+import com.cometchat.chat.constants.CometChatConstants
+import com.cometchat.chat.models.BaseMessage
+import com.cometchat.uikit.core.constants.UIKitConstants.MessageBubbleAlignment
+
+class LocationBubbleFactory : BubbleFactory {
+
+    override fun getCategory(): String = CometChatConstants.CATEGORY_CUSTOM
+    override fun getType(): String = "location"
+
+    override fun getContentView(
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment,
+        style: CometChatMessageBubbleStyle,
+        textFormatters: List<CometChatTextFormatter>
+    ): @Composable () -> Unit = {
+        // Your custom content composable
+        val metadata = message.metadata
+        val lat = metadata?.optDouble("latitude") ?: 0.0
+        val lng = metadata?.optDouble("longitude") ?: 0.0
+        LocationMapView(latitude = lat, longitude = lng)
+    }
+}
+```
+
+### 1.2 Registering BubbleFactories
+
+```kotlin
+CometChatMessageList(
+    user = user,
+    bubbleFactories = listOf(
+        LocationBubbleFactory(),
+        PaymentBubbleFactory()
+    )
+)
+```
+
+The list is converted to a map keyed by `"category_type"` internally via `toFactoryMap()`.
+
+### 1.3 Complete Bubble Replacement
+
+Override `getBubbleView()` to replace the ENTIRE bubble (all slots):
+
+```kotlin
+class CustomBubbleFactory : BubbleFactory {
+    override fun getCategory(): String = "custom"
+    override fun getType(): String = "payment"
+
+    override fun getBubbleView(
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment
+    ): (@Composable () -> Unit)? = {
+        // Complete custom bubble — no header, footer, avatar, etc.
+        PaymentCard(message = message, alignment = alignment)
+    }
+}
+```
+
+When `getBubbleView()` returns non-null, all other slot methods are ignored.
+
+### 1.4 Slot Methods
+
+All return `(@Composable () -> Unit)?` — return `null` to use defaults:
+
+| Method | Slot | Parameters |
+|---|---|---|
+| `getContentView()` | Main content | `message, alignment, style, textFormatters` |
+| `getLeadingView()` | Avatar | `message, alignment, style` |
+| `getHeaderView()` | Sender name | `message, alignment, style, showTime` |
+| `getReplyView()` | Reply preview | `message, alignment, style` |
+| `getBottomView()` | Moderation | `message, alignment, style, hideModerationView` |
+| `getStatusInfoView()` | Timestamp/receipts | `message, alignment, style, showTime` |
+| `getThreadView()` | Thread indicator | `message, alignment, style, onThreadRepliesClick` |
+| `getFooterView()` | Reactions | `message, alignment, style, onReactionClick, onReactionLongClick, onAddMoreReactionsClick` |
+
+### 1.5 Style Override
+
+```kotlin
+override fun getBubbleStyle(
+    message: BaseMessage,
+    alignment: MessageBubbleAlignment
+): CometChatMessageBubbleStyle? {
+    return CometChatMessageBubbleStyle(
+        backgroundColor = Color(0xFFE8F5E9),
+        cornerRadius = 16.dp
+    )
+}
+```
+
+Factory style is the highest priority in the 3-tier style chain.
+
+### 1.6 Lifecycle
+
+```kotlin
+override fun onDispose(message: BaseMessage) {
+    // Clean up resources when bubble leaves composition
+}
+```
+
+## 2. Slot Lambda Parameters (Per-Slot Overrides)
+
+Override individual slots across ALL message types directly on `CometChatMessageList`:
+
+```kotlin
+CometChatMessageList(
+    user = user,
+
+    // Custom avatar for all messages
+    leadingView = { message, alignment ->
+        if (alignment == MessageAlignment.LEFT) {
+            AsyncImage(
+                model = message.sender?.avatar,
+                contentDescription = null,
+                modifier = Modifier.size(32.dp).clip(CircleShape)
+            )
+        }
+    },
+
+    // Custom timestamp for all messages
+    statusInfoView = { message, alignment ->
+        Text(
+            text = formatTime(message.sentAt),
+            style = CometChatTheme.typography.caption1Regular,
+            color = CometChatTheme.colorScheme.textColorTertiary
+        )
+    },
+
+    // Custom footer for all messages
+    footerView = { message, alignment ->
+        // Custom reactions display
+        ReactionsRow(message = message)
+    }
+)
+```
+
+### 2.1 All Slot Parameters
+
+| Parameter | Type | Slot |
+|---|---|---|
+| `leadingView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Avatar |
+| `headerView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Sender name |
+| `replyView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Reply preview |
+| `contentView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Main content |
+| `bottomView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Moderation |
+| `statusInfoView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Timestamp/receipts |
+| `threadView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Thread indicator |
+| `footerView` | `@Composable (BaseMessage, MessageAlignment) -> Unit` | Reactions |
+
+### 2.2 Priority Order
+
+For each slot, the resolution order is:
+1. Explicit slot lambda parameter (highest priority)
+2. BubbleFactory slot method
+3. Internal default rendering
+
+## 3. Style Classes
+
+### 3.1 Using Style Classes
+
+```kotlin
+CometChatConversations(
+    style = CometChatConversationsStyle.default(
+        backgroundColor = Color(0xFFF5F5F5),
+        titleTextColor = Color.Black,
+        titleTextStyle = CometChatTheme.typography.heading1Bold,
+        separatorColor = Color.LightGray,
+        itemStyle = CometChatConversationListItemStyle.default(
+            titleTextColor = Color.DarkGray
+        )
+    )
+)
+```
+
+### 3.2 Style Class Pattern
+
+All style classes follow this pattern:
+
+```kotlin
+@Immutable
+data class CometChatConversationsStyle(
+    val backgroundColor: Color,
+    val titleTextColor: Color,
+    val titleTextStyle: TextStyle,
+    // ... many properties
+) {
+    companion object {
+        @Composable
+        fun default(
+            backgroundColor: Color = CometChatTheme.colorScheme.backgroundColor1,
+            titleTextColor: Color = CometChatTheme.colorScheme.textColorPrimary,
+            // ... defaults from CometChatTheme
+        ): CometChatConversationsStyle = CometChatConversationsStyle(/* ... */)
+    }
+}
+```
+
+Use `Companion.default()` with named parameter overrides — never call the data class constructor directly.
+
+### 3.3 Nested Styles
+
+Some styles contain nested style classes:
+
+```kotlin
+CometChatConversationsStyle.default(
+    itemStyle = CometChatConversationListItemStyle.default(/* ... */),
+    popupMenuStyle = CometChatPopupMenuStyle.default(/* ... */),
+    emptyStateStyle = CometChatEmptyStateStyle.default(/* ... */),
+    errorStateStyle = CometChatErrorStateStyle.default(/* ... */),
+    loadingStateStyle = CometChatLoadingStateStyle.default(/* ... */),
+    dialogStyle = CometChatDialogStyle.default(/* ... */)
+)
+```
+
+## 4. Custom State Views
+
+```kotlin
+CometChatMessageList(
+    user = user,
+    loadingView = { CircularProgressIndicator() },
+    emptyView = { Text("No messages yet") },
+    errorView = { Text("Something went wrong") }
+)
+```
+
+## 5. v5 → v6 Migration
+
+| v5 Pattern | v6 Pattern |
+|---|---|
+| `ChatConfigurator.enable(decorator)` | `CometChatMessageList(bubbleFactories = listOf(...))` |
+| DataSource template methods | BubbleFactory slot methods |
+| Global decorator chain | Per-component factory registration |
+| No bubble replacement | `getBubbleView()` for complete replacement |
+| Theme-level styling only | Per-factory `getBubbleStyle()` |
+
+## Hard rules
+
+- BubbleFactory is an `interface` — implement it, don't extend an abstract class
+- `getCategory()` and `getType()` are REQUIRED — they identify which message type the factory handles
+- When `getBubbleView()` returns non-null, ALL other slot methods are ignored for that message type
+- Slot lambda parameters on `CometChatMessageList` override BubbleFactory slot methods — use lambdas for cross-type overrides, factories for per-type overrides
+- Style classes must use `Companion.default()` factory — the data class constructor requires ALL parameters
+- Do NOT confuse BubbleFactory (UI rendering) with DataSource (data fetching) — they are separate layers

package/skills/cometchat-android-v6-compose-placement/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: cometchat-android-v6-compose-placement
+description: "CometChat Android UIKit v6 Compose placement — setContent, Compose Navigation, Dialog, BottomSheet, and Tab patterns"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, compose, navigation, placement, screens, tabs"
+---
+
+> **Companion skills:** cometchat-android-v6-kotlin-placement (Views equivalent), cometchat-android-v6-compose-components, cometchat-android-v6-compose-theming
+
+## Purpose
+
+Place CometChat Compose components into app screens using Compose Navigation, Dialogs, BottomSheets, and Tab layouts. Patterns derived from `master-app-jetpack`.
+
+## Use this skill when
+
+- Setting up Compose Navigation with CometChat screens
+- Placing CometChat components in a NavHost
+- Showing CometChat components in Dialogs or BottomSheets
+- Building a tabbed layout with Conversations, Users, Groups, Calls tabs
+
+## Do not use this skill when
+
+- Working with Kotlin Views placement (use `cometchat-android-v6-kotlin-placement`)
+- Looking up component APIs (use `cometchat-android-v6-compose-components`)
+
+## 1. Basic setContent Placement
+
+```kotlin
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            CometChatTheme {
+                CometChatConversations(
+                    onItemClick = { conversation -> /* navigate */ }
+                )
+            }
+        }
+    }
+}
+```
+
+## 2. Compose Navigation
+
+Pattern from `master-app-jetpack/navigation/NavGraph.kt`:
+
+```kotlin
+import androidx.navigation.compose.NavHost
+import androidx.navigation.compose.composable
+import androidx.navigation.compose.rememberNavController
+
+@Composable
+fun AppNavigation() {
+    val navController = rememberNavController()
+
+    CometChatTheme {
+        NavHost(navController = navController, startDestination = "conversations") {
+
+            composable("conversations") {
+                CometChatConversations(
+                    onItemClick = { conversation ->
+                        // Pass conversation ID or user/group via route
+                        navController.navigate("chat/${conversation.conversationId}")
+                    }
+                )
+            }
+
+            composable("chat/{conversationId}") { backStackEntry ->
+                val conversationId = backStackEntry.arguments?.getString("conversationId")
+                // Resolve user or group from conversationId, then:
+                Column {
+                    CometChatMessageHeader(user = resolvedUser)
+                    CometChatMessageList(
+                        user = resolvedUser,
+                        modifier = Modifier.weight(1f)
+                    )
+                    CometChatMessageComposer(user = resolvedUser)
+                }
+            }
+
+            composable("users") {
+                CometChatUsers(
+                    onItemClick = { user ->
+                        navController.navigate("chat/user_${user.uid}")
+                    }
+                )
+            }
+
+            composable("groups") {
+                CometChatGroups(
+                    onItemClick = { group ->
+                        navController.navigate("chat/group_${group.guid}")
+                    }
+                )
+            }
+        }
+    }
+}
+```
+
+## 3. Tabbed Layout
+
+```kotlin
+@Composable
+fun HomeScreen() {
+    var selectedTab by remember { mutableIntStateOf(0) }
+    val tabs = listOf("Chats", "Users", "Groups", "Calls")
+
+    CometChatTheme {
+        Column {
+            TabRow(selectedTabIndex = selectedTab) {
+                tabs.forEachIndexed { index, title ->
+                    Tab(
+                        selected = selectedTab == index,
+                        onClick = { selectedTab = index },
+                        text = { Text(title) }
+                    )
+                }
+            }
+
+            when (selectedTab) {
+                0 -> CometChatConversations(onItemClick = { /* navigate */ })
+                1 -> CometChatUsers(onItemClick = { /* navigate */ })
+                2 -> CometChatGroups(onItemClick = { /* navigate */ })
+                3 -> CometChatCallLogs(onItemClick = { /* navigate */ })
+            }
+        }
+    }
+}
+```
+
+## 4. Dialog Placement
+
+```kotlin
+@Composable
+fun ChatScreenWithInfo(message: BaseMessage) {
+    var showInfo by remember { mutableStateOf(false) }
+
+    if (showInfo) {
+        Dialog(onDismissRequest = { showInfo = false }) {
+            CometChatMessageInformation(message = message)
+        }
+    }
+}
+```
+
+## 5. BottomSheet Placement
+
+```kotlin
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun ChatScreenWithReactions(message: BaseMessage) {
+    var showReactions by remember { mutableStateOf(false) }
+    val sheetState = rememberModalBottomSheetState()
+
+    if (showReactions) {
+        ModalBottomSheet(
+            onDismissRequest = { showReactions = false },
+            sheetState = sheetState
+        ) {
+            CometChatReactionList(baseMessage = message)
+        }
+    }
+}
+```
+
+## 6. Call Activity Launch
+
+Ongoing calls use a dedicated Activity (not a composable screen):
+
+```kotlin
+import com.cometchat.uikit.compose.presentation.ongoingcall.ui.CometChatOngoingCallActivity
+import com.cometchat.uikit.core.constants.UIKitConstants.CallWorkFlow
+
+// Launch ongoing call
+CometChatOngoingCallActivity.launchOngoingCallActivity(
+    activity,           // Current Activity
+    call.sessionId,     // Call session ID
+    call.type,          // "audio" or "video"
+    CallWorkFlow.DEFAULT,
+    null,               // Custom CallSettingsBuilder (optional)
+    null                // CometChatOngoingCallStyle (optional)
+)
+```
+
+## 7. Incoming Call Overlay
+
+From `master-app-jetpack/Application.kt` — incoming calls are shown as an overlay using StateFlow:
+
+```kotlin
+// In Application class
+private val _incomingCall = MutableStateFlow<Call?>(null)
+val incomingCall: StateFlow<Call?> = _incomingCall.asStateFlow()
+
+// In your root composable
+val incomingCall by application.incomingCall.collectAsStateWithLifecycle()
+
+incomingCall?.let { call ->
+    CometChatIncomingCall(call = call)
+}
+```
+
+## Hard rules
+
+- ALWAYS wrap CometChat components in `CometChatTheme {}` at the top level — do not nest multiple `CometChatTheme` wrappers
+- Place `CometChatTheme {}` OUTSIDE the `NavHost` so all screens share the same theme
+- Ongoing calls MUST use `CometChatOngoingCallActivity` — they cannot be a composable screen (they need a separate Activity for PiP and lifecycle)
+- When passing User/Group objects between screens, use a cache or resolver pattern (like `master-app-jetpack/navigation/EntityCache.kt`) — do NOT serialize full objects in navigation routes