@cometchat/skills 4.4.2 → 5.0.0

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

@@ -1,302 +1,219 @@
 ---
 name: cometchat-android-v6-compose-placement
-description: "CometChat Android UIKit v6 Compose placement — setContent, Compose Navigation, Dialog, BottomSheet, and Tab patterns"
+description: "Where the CometChat Android v6 chat UI goes in a Jetpack Compose app — the default conversations→message NavHost flow, growing to the tab-based app (chats/users/groups/calls + detail, thread and search routes + incoming calls), a single one-to-one screen, or chat embedded in an existing composable, with a correct back stack and IME handling. Triggers: 'cometchat compose navigation', 'chat screen navhost', 'tab based chat compose', 'embed cometchat in a composable', 'full chat app jetpack compose'."
 license: "MIT"
-compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-compose-android:6.x"
+compatibility: "Android minSdk >=28; compileSdk >=36; Kotlin >=2.1; AGP >=8.9.1; JVM target 11; com.cometchat:chatuikit-compose-android ^6 (Jetpack Compose cohort) — 6.0.x, verified 6.0.5; com.cometchat:chat-sdk-android ^5"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat, android, compose, navigation, placement, screens, tabs"
+  version: "1.0.0"
+  tags: "cometchat android placement layout v6 compose navhost scaffold"
 ---
 
-> **Ground truth:** `com.cometchat:chatuikit-compose-android:6.x` composables + `docs/ui-kit/android/v6`. **Official docs:** https://www.cometchat.com/docs/ui-kit/android/v6/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+> **Ground truth:** catalog `android-v6.json` + `contracts.android-v6.json` (`core-chat-surface`, `chat-experience`) + the docs recipes (`conversation-message-view`, `tab-based-chat`, `one-to-one-chat` — Compose tab). Param shapes verified against the INSTALLED 6.0.5 Compose source.
+>
+> ⚠️ **Jetpack Compose cohort.** Screens are composables on a `NavHost`. The Views cohort (Activities + XML) is a separate skill.
 
-> **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 `sample-app-compose`.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — install, credentials, `initFromSettings → login → render`, and **`references/layout.md`** (the ONE sizing standard). Sizing rules live THERE.
+- `cometchat-android-v6-compose-components` — the param conventions (`onX` / `hideX` / `@Composable` slots).
 
 ## Use this skill when
+"add a chat route to my NavHost", "build the full chat app in Compose", "open a chat screen for this user", "embed the conversation list in an existing composable", "the composer is under the keyboard".
 
-- 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
+## Prerequisites & install
 
-- Working with Kotlin Views placement (use `cometchat-android-v6-kotlin-placement`)
-- Looking up component APIs (use `cometchat-android-v6-compose-components`)
+> ⚠️ **Required on Compose too:** `configurations.all { exclude(group = "org.jetbrains", module = "annotations-java5") }` plus `android.useAndroidX=true` + `android.enableJetifier=true` in `gradle.properties`. The collision arrives via `chatuikit-core-android`, which BOTH cohorts pull, so a Compose-only app fails its FIRST build without them (~40 `Duplicate class` errors). Full block: `cometchat-android-v6-core` §Prerequisites & install.
+Same kit + `initFromSettings → login` gate as `core` — **no chat route is shown before login resolves**; gate the NavHost (or the start destination) on it. Compose cohort artifact only.
 
-## 1. Basic setContent Placement
+## The rule that governs every layout: one screen per route
+Compose composes by **navigation**, not side-by-side panes. List, message, thread and search are separate `NavHost` destinations with a real back stack. Never build a web-style two-pane split on a phone.
 
+**Add Navigation Compose — the kit does not pull it in.** Every placement below uses `NavHost` / `rememberNavController`; without the dependency the app fails with `Unresolved reference: rememberNavController`:
 ```kotlin
-class MainActivity : ComponentActivity() {
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        // Edge-to-edge enables drawing under the system bars; safeDrawingPadding
-        // below puts CometChat content back inside the safe area.
-        enableEdgeToEdge()
-        setContent {
-            CometChatTheme {
-                Box(Modifier.fillMaxSize().safeDrawingPadding()) {
-                    CometChatConversations(
-                        onItemClick = { conversation -> /* navigate */ }
-                    )
-                }
-            }
-        }
-    }
-}
+// app/build.gradle.kts — 2.8.0 matches the kit's compose-bom 2024.09.00 (what the pack's Compose harness builds with)
+implementation("androidx.navigation:navigation-compose:2.8.0")
 ```
 
-> ⚠️ **Always wrap CometChat composables in a `Modifier.safeDrawingPadding()` (or `systemBarsPadding()`) container when using edge-to-edge (ENG-35715).** Without it the kit's top app bar / composer is clipped under the status bar / navigation gesture area on modern Android (API 30+). The kit itself does NOT apply `WindowInsets` for you — that's the host's job. On XML host activities, the equivalent is `android:fitsSystemWindows="true"` on the root view (or per-fragment).
-
-## 2. Compose Navigation
-
-Pattern from `sample-app-compose/navigation/NavGraph.kt` + `messages/MessagesScreen.kt`.
-
-> **Carry `userId` / `groupId` on the route — NOT `conversation.conversationId`.** A `conversationId` is the conversation's own identifier, not a UID/GUID; the kit components need a `User` or `Group` object. The sample resolves the route's `userId`/`groupId` back into a `User`/`Group` on the chat screen via `CometChat.getUser(...)` / `CometChat.getGroup(...)` inside a `LaunchedEffect`. `CometChatTheme {}` is applied once at the app root (see §1), so it is NOT re-wrapped here.
+## Placement 1 — conversations → messages (the default)
+The `core-chat-surface` contract. `core` carries the full code; the structure:
 
 ```kotlin
-import androidx.navigation.NavType
-import androidx.navigation.compose.NavHost
-import androidx.navigation.compose.composable
-import androidx.navigation.compose.rememberNavController
-import androidx.navigation.navArgument
-
+// Two NavHost destinations, NOT an if/else swap — see the ⚠️ note below (the default surface
+// includes threads). The selection is hoisted above the NavHost; Placement 3 shows the
+// process-death-safe variant (route args + re-fetch by uid/guid).
 @Composable
-fun AppNavigation() {
+fun ChatApp() {
     val navController = rememberNavController()
+    var selectedUser by remember { mutableStateOf<User?>(null) }
+    var selectedGroup by remember { mutableStateOf<Group?>(null) }
 
-    NavHost(navController = navController, startDestination = "conversations") {
-
+    NavHost(navController, startDestination = "conversations") {
         composable("conversations") {
             CometChatConversations(
+                modifier = Modifier.fillMaxSize(),
+                title = "Chats",
                 onItemClick = { conversation ->
-                    // Resolve the participant and pass the UID/GUID on the route —
-                    // NOT conversation.conversationId.
                     when (val entity = conversation.conversationWith) {
-                        is User -> navController.navigate("chat?userId=${entity.uid}")
-                        is Group -> navController.navigate("chat?groupId=${entity.guid}")
+                        is User -> { selectedUser = entity; selectedGroup = null }
+                        is Group -> { selectedGroup = entity; selectedUser = null }
                     }
-                }
+                    navController.navigate("messages")
+                },
             )
         }
-
-        composable(
-            route = "chat?userId={userId}&groupId={groupId}",
-            arguments = listOf(
-                navArgument("userId") { type = NavType.StringType; nullable = true; defaultValue = null },
-                navArgument("groupId") { type = NavType.StringType; nullable = true; defaultValue = null }
-            )
-        ) { backStackEntry ->
-            val userId = backStackEntry.arguments?.getString("userId")
-            val groupId = backStackEntry.arguments?.getString("groupId")
-            ChatScreen(userId = userId, groupId = groupId, onBackPress = { navController.popBackStack() })
-        }
-
-        composable("users") {
-            CometChatUsers(
-                onItemClick = { user ->
-                    navController.navigate("chat?userId=${user.uid}")
-                }
-            )
-        }
-
-        composable("groups") {
-            CometChatGroups(
-                onItemClick = { group ->
-                    navController.navigate("chat?groupId=${group.guid}")
-                }
-            )
+        composable("messages") {
+            MessageScreen(selectedUser, selectedGroup) { navController.popBackStack() }
         }
+        // + composable("thread") { … } — its own destination (Thread route, Placement 3)
     }
 }
 ```
-
-The chat screen re-fetches the `User`/`Group` from the route key, then composes the three pieces with `imePadding()` so the keyboard pushes the composer up (matches `MessagesScreen.kt`):
-
 ```kotlin
-import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.WindowInsets
-import androidx.compose.foundation.layout.consumeWindowInsets
-import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
-import androidx.compose.foundation.layout.imePadding
-import androidx.compose.foundation.layout.navigationBarsPadding
-import androidx.compose.foundation.layout.padding
-import androidx.compose.foundation.layout.statusBars
-import androidx.compose.material3.Scaffold
-import androidx.compose.runtime.*
-import androidx.compose.ui.Modifier
-import com.cometchat.chat.core.CometChat
-import com.cometchat.chat.exceptions.CometChatException
-import com.cometchat.chat.models.Group
-import com.cometchat.chat.models.User
-
 @Composable
-fun ChatScreen(userId: String?, groupId: String?, onBackPress: () -> Unit) {
-    var user by remember { mutableStateOf<User?>(null) }
-    var group by remember { mutableStateOf<Group?>(null) }
-
-    // Re-fetch the entity from the route key — routes carry IDs, not objects.
-    LaunchedEffect(userId, groupId) {
-        when {
-            userId != null -> CometChat.getUser(userId, object : CometChat.CallbackListener<User>() {
-                override fun onSuccess(fetched: User) { user = fetched; group = null }
-                override fun onError(e: CometChatException) {}
-            })
-            groupId != null -> CometChat.getGroup(groupId, object : CometChat.CallbackListener<Group>() {
-                override fun onSuccess(fetched: Group) { group = fetched; user = null }
-                override fun onError(e: CometChatException) {}
-            })
-        }
-    }
-
-    if (user != null || group != null) {
-        Scaffold(contentWindowInsets = WindowInsets.statusBars) { paddingValues ->
-            Column(
-                modifier = Modifier
-                    .fillMaxSize()
-                    .padding(paddingValues)
-                    .consumeWindowInsets(paddingValues)
-                    .navigationBarsPadding()
-                    .imePadding()
-            ) {
-                CometChatMessageHeader(
-                    modifier = Modifier.fillMaxWidth(),
-                    user = user,
-                    group = group,
-                    hideBackButton = false,
-                    onBackPress = onBackPress
-                )
-                CometChatMessageList(
-                    modifier = Modifier
-                        .fillMaxWidth()
-                        .weight(1f),
-                    user = user,
-                    group = group
-                )
-                CometChatMessageComposer(
-                    modifier = Modifier.fillMaxWidth(),
-                    user = user,
-                    group = group
-                )
-            }
+fun MessageScreen(user: User?, group: Group?, onBack: () -> Unit) {
+    Scaffold(contentWindowInsets = WindowInsets.statusBars) { padding ->
+        Column(
+            modifier = Modifier.fillMaxSize().padding(padding)
+                .consumeWindowInsets(padding).navigationBarsPadding().imePadding()
+        ) {
+            CometChatMessageHeader(
+                modifier = Modifier.fillMaxWidth(),
+                user = user, group = group,
+                hideBackButton = false, onBackPress = onBack,
+            )
+            CometChatMessageList(
+                modifier = Modifier.fillMaxWidth().weight(1f),   // weight(1f) = the list scrolls
+                user = user, group = group,
+            )
+            CometChatMessageComposer(modifier = Modifier.fillMaxWidth(), user = user, group = group)
         }
     }
 }
 ```
+> ⚠️ **Use a `NavHost`, not `if/else` — mandatory as soon as a THREAD is in play (the default
+> surface includes one), so Placement 1 already uses it. This is correctness, not polish.** `CometChatMessageList` resolves its `CometChatMessageListViewModel` from the enclosing
+> `ViewModelStoreOwner`. In one `if/else` composition scope both the main list and the thread list
+> share the Activity's store, so the thread REUSES the main chat's ViewModel, `parentMessageId` is
+> inert, and the thread screen silently renders the ENTIRE conversation — no error, no warning
+> (verified on device, 6.0.6). Each `NavHost` destination is its own `ViewModelStoreOwner`, which
+> is what makes the thread scope hold. A production app also gets a real back stack from it. Pass `User`/`Group` (both `Parcelable`) or re-fetch by uid/guid on the destination (Placement 5's `getUser`/`getGroup`) — safer across process death.
+
+**`weight(1f)` on the list is load-bearing**: without it the list is unbounded and the composer is pushed off-screen. `imePadding()` keeps the composer above the keyboard.
 
-## 3. Tabbed Layout
+## Placement 2 — a chat tab in an existing app
+Put `CometChatConversations` inside your existing `Scaffold` + `NavigationBar` tab. The tab shows the LIST; tapping a row navigates to the message route **above** the bottom bar (full-screen), so the composer isn't fighting the nav bar. Reuse the host's `NavHost` — additive, never rewrite the graph.
+
+## Placement 3 — grow to the full app (the tab-based recipe)
+The `chat-experience` contract: a `NavigationBar` over four destinations — **Chats** (`CometChatConversations`) · **Users** (`CometChatUsers`) · **Groups** (`CometChatGroups`) · **Calls** (`CometChatCallLogs`) — each item click routing into the same message screen. Then, as the plan names them:
 
 ```kotlin
+// Four-tab navigation — each tab hosts one list component; rows route into the message screen.
+// Every route you navigate to MUST be declared here: a bare "messages/{id}" with no matching
+// composable throws IllegalArgumentException on the first tap. Conversations/Users/Groups all
+// resolve to the same two message destinations, keyed user-vs-group.
 @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) }
-                    )
+fun AppNavigation(navController: NavHostController) {
+    NavHost(navController, startDestination = "chats") {
+        composable("chats") {
+            CometChatConversations(onItemClick = { conv ->
+                when (val e = conv.conversationWith) {   // a conversation is WITH a User or a Group
+                    is User  -> navController.navigate("messages/u/${e.uid}")
+                    is Group -> navController.navigate("messages/g/${e.guid}")
                 }
+            })
+        }
+        composable("users")  { CometChatUsers(onItemClick  = { user  -> navController.navigate("messages/u/${user.uid}") }) }
+        composable("groups") { CometChatGroups(onItemClick = { group -> navController.navigate("messages/g/${group.guid}") }) }
+        composable("calls")  { CometChatCallLogs() }
+
+        // The message destination — re-fetch the entity by id (safe across process death), then reuse
+        // MessageScreen from Placement 1. rememberUser/rememberGroup wrap the verified Placement-5 getters.
+        composable("messages/u/{uid}") { back ->
+            rememberUser(back.arguments?.getString("uid"))?.let { user ->
+                MessageScreen(user = user, group = null) { navController.popBackStack() }
             }
-
-            when (selectedTab) {
-                0 -> CometChatConversations(onItemClick = { /* navigate */ })
-                1 -> CometChatUsers(onItemClick = { /* navigate */ })
-                2 -> CometChatGroups(onItemClick = { /* navigate */ })
-                3 -> CometChatCallLogs(onItemClick = { /* navigate */ })
+        }
+        composable("messages/g/{guid}") { back ->
+            rememberGroup(back.arguments?.getString("guid"))?.let { group ->
+                MessageScreen(user = null, group = group) { navController.popBackStack() }
             }
         }
-    }
-}
-```
-
-## 4. Dialog Placement
-
-```kotlin
-@Composable
-fun ChatScreenWithInfo(message: BaseMessage) {
-    var showInfo by remember { mutableStateOf(false) }
-
-    if (showInfo) {
-        Dialog(onDismissRequest = { showInfo = false }) {
-            CometChatMessageInformation(message = message)
+        composable("members/{guid}") { back ->
+            // Group details: CometChatGroupMembers with built-in kick/ban/scope actions
+            rememberGroup(back.arguments?.getString("guid"))?.let { group ->
+                CometChatGroupMembers(group = group)
+            }
         }
     }
 }
-```
-
-## 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)
-        }
-    }
-}
+// Re-fetch by id with the Chat SDK (the Placement-5 getters), surfaced to Compose via produceState.
+@Composable fun rememberUser(uid: String?): User? = produceState<User?>(null, uid) {
+    val id = uid ?: return@produceState
+    CometChat.getUser(id, object : CometChat.CallbackListener<User>() {
+        override fun onSuccess(u: User) { value = u }
+        override fun onError(e: CometChatException) { /* SURFACE it — ERR_UID_NOT_FOUND must not dead-end */ }
+    })
+}.value
+@Composable fun rememberGroup(guid: String?): Group? = produceState<Group?>(null, guid) {
+    val id = guid ?: return@produceState
+    CometChat.getGroup(id, object : CometChat.CallbackListener<Group>() {
+        override fun onSuccess(g: Group) { value = g }
+        override fun onError(e: CometChatException) { /* SURFACE it */ }
+    })
+}.value
 ```
 
-## 6. Call Activity Launch
-
-Ongoing calls use a dedicated Activity (not a composable screen):
+> ⚠️ **A Groups tap is NOT a Conversations tap.** `CometChatGroups` lists groups the user may not
+> have joined; routing one straight to the message screen renders the kit's error state with a
+> live-but-dead composer (verified on device). Gate on membership (`group.isJoined` — the field
+> `hasJoined` is private; `isJoined()` is the accessor) and join first when false —
+> `CometChat.joinGroup(guid, groupType, password, CallbackListener<Group>)` — the listener is REQUIRED (4 params), prompting for the password when `groupType` is
+> `CometChatConstants.GROUP_TYPE_PASSWORD`. Only a Conversations row is guaranteed joined, because
+> a conversation exists only once you are in it.
 
+- **Detail routes** — user detail (block/unblock) and group detail via `CometChatGroupMembers` (kick/ban/scope, role-gated).
+- **Thread route** — note Compose takes the parent as **params**, not setters:
 ```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)
+CometChatThreadHeader(modifier = Modifier.fillMaxWidth(), parentMessage = parent)
+CometChatMessageList(
+    modifier = Modifier.fillMaxWidth().weight(1f),
+    user = user, group = group,          // the SAME target, or replies silently never send
+    parentMessageId = parent.id,
+)
+CometChatMessageComposer(
+    modifier = Modifier.fillMaxWidth(),
+    user = user, group = group, parentMessageId = parent.id,
 )
 ```
+- **Search route** — (import `com.cometchat.uikit.core.constants.SearchScope`) `CometChatSearch(searchScopes = listOf(SearchScope.CONVERSATIONS, SearchScope.MESSAGES), uid = …, guid = …, onConversationClick = …, onMessageClick = …, onBackPress = …)`. Omit `uid`/`guid` for global search; pass one to scope to the open chat.
+- **Incoming calls at app level** — `CometChatIncomingCall` driven by a global call listener, hoisted above the NavHost so a call surfaces from any tab (→ `cometchat-android-v6-calls`).
 
-## 7. Incoming Call Overlay
-
-> **Note on canonical references:** the **Compose** sample app (`sample-app-compose`) ships **without** calling enabled, so it has no incoming-call wiring to copy. The only canonical Android sample that wires incoming calls is the **Kotlin-Views** `sample-app-kotlin`, which adds `CometChatIncomingCall` to a programmatic `Snackbar` host after a `CometChat.addCallListener` fires (see `cometchat-android-v6-calls`). The Compose pattern below — register the call listener, push the `Call` into a `StateFlow`, render an overlay — is the idiomatic Compose adaptation of that same flow (you wire it yourself; it is not lifted verbatim from a sample file).
+Each tab keeps its own back stack (`navController` per tab, or `saveState`/`restoreState` on the bottom-nav items).
 
-Incoming calls are shown as an overlay using a StateFlow you expose from the `Application` (register a `CometChat.addCallListener` that pushes incoming `Call`s into it):
+## Placement 4 — embed in an existing composable
+Give the component a bounded box: `Modifier.weight(1f)` inside a `Column`, `Modifier.height(360.dp)`, or `fillMaxSize()` in its own pane. **Never place it in an unbounded parent** (a `Column` with `verticalScroll`, or no weight) — the kit fills what you give it, and unbounded means nothing. Never nest `CometChatMessageList` inside another scrollable.
 
+## Placement 5 — deep entry from an arbitrary screen (known UID/GUID)
+"Open a chat with THIS user" from one of your own screens (an order, an article, a ticket): gate on the same init/login, resolve the entity with the Chat SDK, then navigate to the SAME message destination from Placement 1 with it (docs: `core` → `references/docs-map.md` → `one-to-one-chat`):
 ```kotlin
-// In Application class
-private val _incomingCall = MutableStateFlow<Call?>(null)
-val incomingCall: StateFlow<Call?> = _incomingCall.asStateFlow()
+CometChat.getUser(uid, object : CometChat.CallbackListener<User>() {   // groups: CometChat.getGroup(guid, …)
+    override fun onSuccess(user: User) {
+        navController.navigate(messageRouteFor(user))   // or Placement 1: set selectedUser, then navigate("messages")
+    }
+    override fun onError(e: CometChatException) { /* SURFACE it (snackbar) — ERR_UID_NOT_FOUND must not dead-end */ }
+})
+```
+Verified in the installed SDK: `CometChat.getUser(@NonNull String, @NonNull CallbackListener<User>)` / `CometChat.getGroup(@NonNull String, @NonNull CallbackListener<Group>)`.
 
-// In your root composable
-val incomingCall by application.incomingCall.collectAsStateWithLifecycle()
+## Sizing and the keyboard
+Owned by `core/references/layout.md`; the Compose specifics: `Scaffold(contentWindowInsets = WindowInsets.statusBars)` + `.consumeWindowInsets(padding)` + `.navigationBarsPadding()` + **`.imePadding()`**, and `enableEdgeToEdge()` in the host Activity. Missing `imePadding()` is the #1 Compose complaint (composer under the keyboard).
 
-incomingCall?.let { call ->
-    CometChatIncomingCall(call = call)
-}
-```
+## Navigation & back-stack discipline
+Every route pops correctly: `onBackPress` → `navController.popBackStack()`; thread/search/detail → back returns to the message route; predictive-back safe. Never re-`init`/`login` per screen — that happened once at startup.
 
-## Hard rules
+## Common pitfalls
+Showing a chat route before login resolves · a swallowed `getUser`/`getGroup` `onError` (Placement 5) · missing `weight(1f)` (composer pushed off-screen) · missing `imePadding()` · unbounded parent (renders nothing) · nesting the message list in a scrollable · thread route missing the `user`/`group` target · using `setParentMessageId(...)` (that's the Views cohort — Compose takes `parentMessageId =`) · rebuilding the host's nav graph instead of adding routes.
 
-- 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 navigating to a chat, carry `userId`/`groupId` on the route and re-fetch the `User`/`Group` with `CometChat.getUser`/`CometChat.getGroup` on the chat screen (see §2) — do NOT serialize full objects, and do NOT pass `conversation.conversationId` (it is not a UID/GUID)
+## Verify it works
+Compile: `./gradlew :app:assembleDebug   # in YOUR app (native-fence.mjs is a pack-repo gate, not installed by the CLI)`. On device: list → tap → message screen for the right entity; system back returns; composer stays visible with the keyboard open; nothing under the system bars; thread and search open AND return; on the grown app each tab renders and an incoming call surfaces from any tab.