cometchat-ios-placement— agent skill

Companion skills (read first)

• cometchat-ios-core owns the default surface (list → pushed chat screen) and the five layout rules. This skill ADDS composition beyond that one screen. The five rules still apply to EVERY screen you add.

Use this skill when

"tab-based chat", "let people browse users and groups", "open group details", "add a thread screen", "make it work on iPad".

The shape of an iOS CometChat app

UITabBarController (yours) → per tab a UINavigationController (yours) → a kit list → push your own chat screen. The kit supplies screens; you own every container and every transition. There is no composite component and no built-in tab shell.

Recipes

The kit's lists draw their OWN navigation bar — the host's `navigationItem` is unused. Setting navigationItem.rightBarButtonItems (a "New Group" button is the first thing anyone adds) silently renders NOTHING: measured with the button installed and both bars inspected, the control never appears, and setting hideNavigationBar = true removes the visible bar, proving it is the kit's. Put custom controls in the kit's own affordances — CometChatMessageHeader.set(options:) for the header overflow menu, or assign the list components' menus property ([UIBarButtonItem]?) — there is no set(menus:) method; menus is a settable property, not a setter. Otherwise hide the kit bar and use your own — do not attach them to a navigationItem nobody draws.

Tabs. One UINavigationController per tab, each rooted at CometChatConversations / CometChatUsers / CometChatGroups / CometChatCallLogs. Every list's selection callback pushes your chat screen — wire all of them, or a tab dead-ends.

// Tab-based placement — wire each list's selection to the chat screen.
// set(onItemClick:) is TWO-arg on the lists: (item, indexPath). A one-arg `{ user in … }` does
// NOT compile ("expects 2 arguments, but 1 was used") — take the indexPath and ignore it.
let users = CometChatUsers()
users.set(onItemClick: { user, _ in openChat(user: user, group: nil) })

let groups = CometChatGroups()
groups.set(onItemClick: { group, _ in openChat(user: nil, group: group) })

// Global search — presented from the conversations list's onSearchClick property.
// CometChatSearch's result callbacks are assignable PROPERTIES, not setters — ASSIGN them
// (`search.onConversationClicked = …`). There is no setter form; wrapping either callback in a
// `set(...)` call does not compile (it resolves to a different overload). onConversationClicked
// is (Conversation, IndexPath); onMessageClicked is (BaseMessage).
let conversations = CometChatConversations()
conversations.onSearchClick = {
    let search = CometChatSearch()
    search.onConversationClicked = { conv, _ in
        self.dismiss(animated: false); openChatFromConversation(conv)
    }
    search.onMessageClicked = { msg in
        self.dismiss(animated: false); openChatFromMessage(msg)
    }
    self.present(search, animated: true)
}

Users or groups → chat. CometChatUsers.set(onItemClick:) gives a User; CometChatGroups.set(onItemClick:) gives a Group. Pass exactly one to your chat screen — the same single-target rule as core.

Group details / members. CometChatMessageHeader has no tap callback — no onItemClick. Its only interactive surface is set(options:) taking [CometChatPopupMenu.MenuItem], so a details/members screen is an overflow menu item you add, not a tap on the title. From that action, push CometChatGroupMembers — which has NO `init(group:)`; construct it `init()` then attach the group with the setter (let members = CometChatGroupMembers(); members.set(group: group) — guessing CometChatGroupMembers(group:) fails to compile, "argument passed to call that takes no arguments"). Two more things about it are not obvious:

• When PUSHED, hide the KIT's bar or the user is stranded. The kit draws a modal-style bar whose Cancel calls dismiss() — a no-op on a pushed controller — and set(onBack:) never fires from it (diagnosed on a tab-bar app; the same control works when the component is PRESENTED as a sheet). So: members.hideNavigationBar = true; members.title = "Members" and let the HOST navigation bar provide Back — measured working, edge-swipe included. This is the inverse of the chat screen's rule 5: a pushed kit LIST keeps the host bar.
• Kick, ban and scope-change are BUILT IN — do not hand-roll them. hideKickMemberOption / hideBanMemberOption / hideScopeChangeOption all default to false, and tapping a row already presents the kit's own CometChatScopeChange sheet. Wiring your own set(onItemClick:) on top produces a DOUBLE presentation (measured). Only add set(onItemClick:) if you first hide the built-in options.

Adding members has no component — build a picker from CometChatUsers in selection mode and call CometChat.addMembersToGroup(guid:groupMembers:bannedUIDs:onSuccess:onError:) (SDK fallback; docs-map.md).

Threads. CometChatMessageList.set(onThreadRepliesClick:) pushes a thread screen: CometChatThreadedMessageHeader + a thread list + composer. Thread scoping — the LIST takes its parent in the SAME call as its target. CometChatMessageList.set(user:parentMessage:withParent:) (or set(group:parentMessage:)). A separate set(user:) followed by set(parentMessageId:) does NOT scope the list: the first call already built a request for the whole conversation, so the thread screen renders the entire conversation with the parent in it. The COMPOSER is different — set(user:) then set(parentMessageId:). The header takes set(parentMessage:). Three components, three shapes — verified against the shipped 5.1.22 interface by compiling each.

Search. CometChatConversations.onSearchClick (a property) presents CometChatSearch. Anything you PRESENT owns its dismissal; anything you PUSH gets a back control free.

iPad. UISplitViewController with the list as primary and your chat screen as secondary. The kit components fill what you give them, so each column still needs the core layout rules applied independently.

Gotchas

• Selection multiplies the dead-end risk. Every list you add is another callback that must go somewhere.
• Hide the host nav bar only on screens that use the kit header, and restore it in viewWillDisappear — otherwise the rest of the app loses its bar.
• Modals need explicit dismissal. A presented screen with no way out is the iOS form of an unwired back button.

Verify it works

Every tab reaches a chat screen; every pushed screen returns; every presented screen dismisses; the composer clears the keyboard on all of them; rotation and iPhone SE → Pro Max keep the surface full-bleed.