@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,435 +1,90 @@
 ---
 name: cometchat-android-v6-compose-customization
-description: "CometChat Android UIKit v6 Compose customization — BubbleFactory interface, slot lambdas, @Immutable style classes, and per-slot overrides"
+description: "Make the CometChat Android v6 UI match your app in the Jetpack Compose cohort — theming with the CometChatTheme composable and lightColorScheme/darkColorScheme, per-component style data classes, @Composable view slots, state views, menu options, text formatters, custom message rendering with bubble factories, localization and sounds. Triggers: 'cometchat compose theme', 'brand colors jetpack compose cometchat', 'dark mode compose cometchat', 'custom row composable', 'custom message type 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, customization, bubble-factory, slots, style"
+  version: "1.0.0"
+  tags: "cometchat android customization theming v6 compose dark-mode colorscheme"
 ---
 
-> **Ground truth:** `com.cometchat:chatuikit-{compose,kotlin}-android:6.x` (+ `calls-sdk-android:5.x`) — resolved AAR (javap) + `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` + the Compose theme source. ⚠️ The theming API below was read from the INSTALLED 6.0.5 source and **differs from the docs** — see the callout. Fetch token names from `color-resources`; never invent one.
+>
+> ⚠️ **Jetpack Compose cohort** — theming is the `CometChatTheme` composable + colour-scheme factories; slots are `@Composable` lambdas. The Views cohort (XML theme attributes + ViewHolder listeners) is a separate skill.
 
-> **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.
+## Companion skills (read first)
+- `cometchat-android-v6-core` — install, credentials, init/login, the fetch map. Assumed here, never repeated.
+- `cometchat-android-v6-compose-components` — what exists and its param conventions.
 
 ## 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
-}
-```
-
-### 1.7 Custom attachment options (Scenario 3) — pass the `attachmentOptions` parameter
-
-A `BubbleFactory` only *renders* a custom type; to let users *create* one you usually add a composer attachment action. On Compose the canonical path is the **`attachmentOptions` parameter** on `CometChatMessageComposer` — a `List<CometChatMessageComposerAction>` whose contents are added **after** the built-in options.
-
-```kotlin
-CometChatMessageComposer(
-    user = user,
-    attachmentOptions = listOf(
-        CometChatMessageComposerAction(
-            id = "location",
-            title = "Send Location",
-            icon = R.drawable.ic_location,
-            onClick = OnClick { /* pick + send (see 1.8) */ }
-        )
-    )
-)
-```
-
-**Append is automatic — your list does NOT replace the defaults.** Internally the composable calls `composerViewModel.setAttachmentOptions(attachmentOptions)` (`CometChatMessageComposer.kt:431-432`), which sets only the *custom* options list (`_customAttachmentOptions`). The defaults (camera/image/video/audio/document/poll/collab-doc/collab-whiteboard) are rebuilt every time by `getDefaultAttachmentOptions(...)` and your custom options are concatenated at the end (`CometChatMessageComposerViewModel.kt:646-649`). There is no "wipe defaults" footgun here — `setAttachmentOptions` despite its name does NOT drop the built-ins.
-
-> Hide a built-in instead with the composer's `hide*Option` flags (e.g. `hidePollOption = true`), which flip the `_show*Option` visibility checked inside `getDefaultAttachmentOptions`.
-
-If you hold a `CometChatMessageComposerViewModel` directly (advanced), `addAttachmentOption(action)` appends one custom option and `setAttachmentOptions(list)` replaces the custom list — both verified at `CometChatMessageComposerViewModel.kt:657 / :666`. The built-in option IDs are constants on `CometChatMessageComposerAction` (`ID_CAMERA`, `ID_IMAGE`, `ID_VIDEO`, `ID_AUDIO`, `ID_DOCUMENT`, `ID_POLL`, `ID_COLLABORATIVE_DOCUMENT`, `ID_COLLABORATIVE_WHITEBOARD` — `CometChatMessageComposerAction.kt:42-49`).
-
-### 1.8 Sending a custom message — use the UIKit path, not the raw SDK
-
-```kotlin
-val message = CustomMessage(
-    receiverId,
-    CometChatConstants.RECEIVER_TYPE_USER,   // or RECEIVER_TYPE_GROUP
-    "location",                              // matches the BubbleFactory type
-    customData                               // org.json.JSONObject
-)
-// ✅ kit path — sets muid + sender, fires ccMessageSent → list APPENDS
-CometChatUIKit.sendCustomMessage(message, object : CometChat.CallbackListener<CustomMessage>() {
-    override fun onSuccess(p0: CustomMessage) {}
-    override fun onError(p0: CometChatException) {}
-})
-// ❌ CometChat.sendCustomMessage(...) — no muid/sender/event → recipient error + realtime replace
-```
-
-Verified (v6 core/compose): `CometChatMessageComposer(attachmentOptions = …)` param (`CometChatMessageComposer.kt:338`), `CometChatMessageComposerViewModel.addAttachmentOption / setAttachmentOptions / getDefaultAttachmentOptions` (`:657 / :666 / :547`), `CometChatUIKit.sendCustomMessage(CustomMessage, CallbackListener)` (`CometChatUIKit.kt:472`).
-
-### 1.9 Override an EXISTING type's bubble (Scenario 2)
-
-To replace the rendering of a built-in type (e.g. text or image), register a `BubbleFactory` whose `getCategory()`/`getType()` **match the built-in identifiers**. Built-in types are NOT pre-seeded as factory entries — the bubble falls back to `InternalContentRenderer` only when no factory matches a `"category_type"` key (`CometChatMessageBubble.kt:155` "Falls back to InternalContentRenderer if no factory is provided"). So a matching factory simply takes priority over the internal default.
-
-```kotlin
-import com.cometchat.chat.constants.CometChatConstants
-
-class MyTextBubbleFactory : BubbleFactory {
-    override fun getCategory(): String = CometChatConstants.CATEGORY_MESSAGE   // "message"
-    override fun getType(): String = CometChatConstants.MESSAGE_TYPE_TEXT      // "text"
-
-    override fun getContentView(
-        message: BaseMessage,
-        alignment: UIKitConstants.MessageBubbleAlignment,
-        style: CometChatMessageBubbleStyle,
-        textFormatters: List<CometChatTextFormatter>
-    ): @Composable () -> Unit = {
-        MyCustomTextContent(message as TextMessage)   // only the content area
-    }
-    // …or override getBubbleView() to replace the whole bubble (see 1.3)
-}
-
-CometChatMessageList(user = user, bubbleFactories = listOf(MyTextBubbleFactory()))
-```
-
-This is still additive at the list level: registering a `message_text` factory only overrides text bubbles; image/video/custom types keep their internal rendering. Use `getContentView()` for content-only override, `getBubbleView()` for full-bubble replacement.
-
-### 1.10 Add a long-press message option (Scenario 4 — Forward-style)
-
-`CometChatMessageList` exposes two lambda parameters for the long-press option sheet (`CometChatMessageList.kt:577-598`):
-
-| Param | Type | Semantics |
-|---|---|---|
-| `addOptions` | `((BaseMessage) -> List<CometChatMessageOption>)?` | **Append** after the defaults |
-| `options` | `((BaseMessage) -> List<CometChatMessageOption>?)?` | **Replace** all defaults (takes precedence over `addOptions`; return `null` to keep defaults) |
-| `onMessageOptionClick` | `((BaseMessage, optionId: String, optionName: String) -> Unit)?` | Click handler |
-
-Use `addOptions` for a Forward-style action so the built-in Reply/Copy/Edit/Delete survive:
-
-```kotlin
-import com.cometchat.uikit.core.domain.model.CometChatMessageOption
-
-CometChatMessageList(
-    user = user,
-    addOptions = { message ->            // ✅ appended to defaults
-        listOf(
-            CometChatMessageOption(
-                id = "forward",
-                title = "Forward",
-                icon = R.drawable.ic_forward,
-                onClick = { /* open forward picker for `message` */ }
-            )
-        )
-    }
-    // ❌ options = { listOf(forward) }   // would DROP reply/copy/edit/delete
-)
-```
-
-`CometChatMessageOption(id, title, titleColor, icon, iconTintColor, …, onClick)` is a data class at `CometChatMessageOption.kt:21`. Resolution order is verified in `CometChatMessageListViewModel.resolveMessageOptions` (`:817-827`): `setOptions` result wins if non-null, else `defaultOptions + addOptions`.
-
-### 1.11 MessageTemplate via the DataSource (docs-taught alternative to BubbleFactory)
-
-> ⚠️ **Verify before using — symbols not found in the GA v6 Compose source.** `CometChatUIKit.getDataSource()`, `getMessageTemplates()`, `CometChatMessageTemplate`, and a `templates` parameter on the Compose `CometChatMessageList` appear in the Android **docs** but are **absent from the verified `com.cometchat.uikit.compose` GA source** (they're the legacy `com.cometchat.chatuikit` v5-shaped API; the Compose list only exposes `bubbleFactories`). Treat this section as a docs reference that may not compile against your installed v6 kit — **prefer `BubbleFactory` (the confirmed v6-native path) for all new code.**
-
-The `BubbleFactory` / slot-lambda surface above is the primary v6 customization path. The Android docs also teach a **`MessageTemplate`** path through the data source ([message-template](https://www.cometchat.com/docs/ui-kit/android/v6/message-template)) — fetch the existing templates, mutate the one you want, then re-apply (append, never replace with a single-item list):
-
-```kotlin
-// 1. fetch existing templates from the data source
-val templates = CometChatUIKit.getDataSource()
-    .getMessageTemplates(additionParameter)   // pass the list's additionParameter
-    .toMutableList()
-
-// 2. mutate the template you want (or create a new one for a custom type)
-templates.find { it.type == UIKitConstants.MessageType.TEXT }
-    ?.setContentView { baseMessage, alignment ->
-        Text(text = (baseMessage as? TextMessage)?.text ?: "")
+"match the chat to our brand", "use our typography", "support dark mode", "restyle rows or bubbles", "replace the empty/loading/error view", "add a long-press option", "render a custom message type", "translate the UI".  **Theming lives HERE** — there is no separate theming skill.
+
+## Theming — the top mechanism (BAKED)
+Wrap the kit UI in the `CometChatTheme` composable and override the colour scheme:
+```kotlin
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.Color
+import com.cometchat.uikit.compose.theme.CometChatTheme
+import com.cometchat.uikit.compose.theme.darkColorScheme
+import com.cometchat.uikit.compose.theme.lightColorScheme
+
+@Composable
+fun AppChatTheme(content: @Composable () -> Unit) {
+    // Pass named params — CometChatColorScheme is NOT a data class, so there is no .copy().
+    // Setting `primary` DERIVES the whole extended ramp (extendedPrimaryColor50…900) for you.
+    val scheme = if (isSystemInDarkTheme()) {
+        darkColorScheme(primary = Color(0xFF8B7FFF))
+    } else {
+        lightColorScheme(primary = Color(0xFFF76808))
     }
-// new custom type:
-val contact = CometChatMessageTemplate().apply {
-    setType("contact"); setCategory(UIKitConstants.MessageCategory.CUSTOM)
-    setContentView { baseMessage, _ -> /* custom composable */ }
+    CometChatTheme(colorScheme = scheme) { content() }
 }
-templates.add(contact)
-
-// 3. re-apply — Compose passes the list to CometChatMessageList
-CometChatMessageList(user = user, templates = templates)
-```
-
-Compose templates expose lambda slot setters (`setContentView`, `setHeaderView`, `setFooterView`, `setBottomView`, `setStatusInfoView`, `setBubbleView`, `setOptions`) mirroring §2's slots. Prefer `BubbleFactory` for new code; use `getMessageTemplates(...)` when you want to start from the kit's defaults and tweak one type. (This overlaps the custom-message topic.)
-
-## 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)
-    }
-)
 ```
+`CometChatTheme(colorScheme, shapes, typography, content)` provides all three through composition locals; read them anywhere with `CometChatTheme.colorScheme` / `.typography` / `.shapes`. **Follow the system by default** on a fresh integration (`isSystemInDarkTheme()`), and override only the tokens you actually brand so future kit versions stay consistent.
 
-### 2.1 All Slot Parameters
+> ⚠️ **Docs drift — trust this file.** The docs Compose tab teaches `CometChatColorScheme.light()` / `.dark()`. Those factories **do not exist** in 6.0.5: the real ones are **top-level `lightColorScheme()` / `darkColorScheme()`** in `com.cometchat.uikit.compose.theme`, configured by **named params, not `.copy()`** (`CometChatColorScheme` is a plain class). Logged internally. The compile gate rejects both wrong forms.
 
-| Parameter | Type | Slot |
+## Customization mechanism map (pick the smallest one that does the job)
+| Intent | Mechanism | Docs page (fetch for exact names) |
 |---|---|---|
-| `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
-
+| brand colour, light/dark | `CometChatTheme(colorScheme = …)` + `lightColorScheme()`/`darkColorScheme()` | `theme-introduction` (Compose tab) |
+| exact token names | `CometChatColorScheme` fields | `color-resources` |
+| fonts / text styles | `CometChatTypography` (28 `TextStyle` named params: `titleBold`, `heading1Bold`, …), passed as `CometChatTheme(typography = …)` | **no shipped page documents Compose typography** — `theme-introduction` is colours-only and `component-styling` covers Views (`cometchatFontBold`). Use the signature here; do not fetch. |
+| restyle ONE component | `style = CometChat<X>Style.default().copy(...)` (style classes ARE data classes) | `component-styling` |
+| bubble look per type | bubble style data classes | `message-bubble-styling` |
+| replace a REGION of a row | `@Composable` slot params — `itemView`, `leadingView`, `subtitleView`, `trailingView` | `customization-view-slots` |
+| empty / error / loading | `hideEmptyState`/`hideErrorState`/`hideLoadingState` + your own composable | `customization-state-views` |
+| long-press / composer actions | `options` / `addOptions` params | `customization-menu-options` |
+| **custom message TYPE** | bubble factories (see below) | *not* the docs `message-template` page |
+| custom text patterns | `textFormatters` + `CometChatTextFormatter`/`CometChatMentionsFormatter` | `customization-text-formatters` |
+| what a list fetches | `conversationsRequestBuilder` (and the per-list equivalents) | `customization-viewmodel-data` |
+| translate the UI | `CometChatLocalize` | `localize` |
+| in-app sounds | `CometChatSoundManager` | `sound-manager` |
+
+## What's swappable — slots are `@Composable` lambdas
 ```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(/* ... */)
+    modifier = Modifier.fillMaxSize(),
+    trailingView = { conversation, typing -> MyUnreadPill(conversation) },   // (Conversation, TypingIndicator?)
+    options = { context, conversation -> myMenuItems(conversation) },
+    hideEmptyState = true,                                                   // then render your own
+    conversationsRequestBuilder = ConversationsRequest.ConversationsRequestBuilder()
+        .setConversationType("user"),                                        // scope in the REQUEST, not a client filter
+    onItemClick = { /* navigate */ },
 )
 ```
+Slot params take `(@Composable (Conversation, TypingIndicator?) -> Unit)?` on the conversations list, with the analogous shape on users/groups/members. Style params take a data class: `style = CometChatConversationsStyle.default().copy(...)`.
 
-## 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()` |
-
-## Text formatters (inline mentions / URLs / custom tokens)
-
-Style/transform message text inline by passing `textFormatters` to the composer/list. The kit ships `CometChatMentionsFormatter` + `CometChatRichTextFormatter` (subclasses of the abstract `CometChatTextFormatter`) in `com.cometchat.uikit.compose.presentation.shared.formatters`. Default behavior (a mentions formatter) applies when you pass nothing — so to ADD a custom one, include the defaults too.
-
-```kotlin
-import com.cometchat.uikit.compose.presentation.shared.formatters.CometChatMentionsFormatter
-import com.cometchat.uikit.compose.presentation.shared.formatters.CometChatTextFormatter
-
-CometChatMessageComposer(
-    user = user,
-    textFormatters = listOf(CometChatMentionsFormatter(context) /* , YourFormatter(context) */),
-)
-// CometChatMessageList also takes textFormatters: List<CometChatTextFormatter>.
-```
-
-For a custom @/#/! token: subclass `CometChatTextFormatter(trackingCharacter)` and implement its `search()` + view hooks (see the kit's `formatters/` source + the per-platform docs).
-
-## Hard rules
+## Custom message types — bubble factories, not templates
+Register factories on the message list for custom categories/types; `createContentView` runs before the message is known, `bindContentView` receives it. ⚠️ **`CometChatMessageTemplate` and `setTemplates` are absent from the shipped 6.0.5 artifact** (logged internally). The docs `message-template` page was corrected upstream (verified 2026-09-09): it is now "Message Bubble Factory" and teaches the factory API — fetch its Compose tab for the current signatures.
 
-- 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
+## The rule
+**Custom UI goes INSIDE the component** — a slot param, a style copy, a menu option, a formatter — never a composable stacked over a kit component with a `Box`, and never a forked component. If no slot exists, fetch the page's Compose tab before inventing UI; if there genuinely is no hook, say so rather than re-implementing the component.
 
-## Sound (in-app message + call sounds)
+## Common pitfalls
+`CometChatColorScheme.light()` from the docs (use `lightColorScheme()`) · calling `.copy()` on a colour scheme (not a data class — pass named params) · forgetting `CometChatTheme { }` around kit UI (falls back to defaults) · theming only light mode (no `isSystemInDarkTheme()` branch) · hardcoding colours per screen · `Box`-stacking custom UI instead of using a slot param · re-implementing a list to change one row · client-side filtering instead of a scoped request builder · emitting `CometChatMessageTemplate`.
 
-Sound is a customization sub-dimension. The UI Kit plays incoming/outgoing message + call sounds via `CometChatSoundManager` — mute it, swap custom audio, or play a specific sound. The full API + recipe lives in **`cometchat-android-v6-compose-theming`** (Sound section). Verify the access path against the installed kit before relying on it.
+## 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: the brand colour appears on kit surfaces; toggle system dark mode → the UI follows with readable contrast; a slot composable renders INSIDE its component; state views appear on empty/error/loading; a changed menu option shows on long-press.