@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-core/references/anti-patterns.md

@@ -0,0 +1,113 @@
+# Anti-patterns — what does NOT exist, and what compiles but is wrong
+
+> Catalog-verified against the shipped 5.1.22 `.swiftinterface`. If a symbol is not in
+> `catalogs/ios-v5.json`, it does not exist in the installed kit — no matter where you saw it.
+
+## 1. v4 composite components — they do not exist in v5
+
+The single most damaging carry-over. These are **v4** names and are NOT in the v5 public API:
+
+- `CometChatConversationsWithMessages`
+- `CometChatUsersWithMessages`
+- `CometChatGroupsWithMessages`
+- `CometChatMessages`
+
+They appeared on v5 documentation pages (tracked as **IOS-DOCS-001**), which is exactly why the
+rule is "verify against the catalog", not "trust a code sample". v5 has **no composite** — the
+host composes header + list + composer itself and owns the navigation. See `layout.md`.
+
+If you find yourself reaching for a one-liner chat screen: there isn't one. That is the design.
+
+## 2. Styles are PROPERTIES, not setters
+
+The kit's API is setter-based and returns `Self`, so `set(...)` is the reflex — but styling is
+not applied that way:
+
+```swift
+// wrong — no such setter
+list.set(style: myStyle)
+
+// right — assign the style property
+list.style = myStyle
+```
+
+Guessing the call form is the most common compile failure. Fetch the component's `.md` twin via
+`docs-map.md` and match the shape exactly.
+
+## 3. `CometChatCallLogs` hands back `Any`
+
+Unlike every other list component, five of its setters pass untyped values. Using them directly
+does not compile — cast first:
+
+```swift
+callLogs.set(onItemClick: { callLog, _ in
+    guard let log = callLog as? CallLog else { return }
+    // …
+})
+```
+
+This is a property of the shipped binary, not a docs error. Treat every `CometChatCallLogs`
+callback parameter as `Any` until proven otherwise.
+
+## 4. The thread trap — two parent APIs
+
+A threaded reply view needs its parent message, and there is more than one way to hand it over.
+Mixing them (setting a parent message id on one component and a parent message object on
+another) yields a view that renders but never sends. Set the parent ONE way, on the component
+the docs prescribe for that surface, and verify by actually sending a reply.
+
+## 5. Assuming the SDK ships with the kit's dependencies resolved
+
+The kit is a prebuilt binary xcframework compiled against ONE `CometChatSDK` version, and SPM
+does **not** resolve that transitively. Pin the exact version. On 5.1.19 the shipped
+`.swiftinterface` also hard-imports `CometChatCallsSDK`, so the Calls SDK must resolve for ANY
+integration to compile — even a chat-only one that never places a call. 5.1.18 built without it,
+so treat this as a packaging regression to state plainly, not as a design requirement to teach.
+
+## 6. Answering API from memory
+
+The kit's surface is largely un-prefixed (`User`, `Group`, `ConversationRequest`), so a
+plausible-looking name is often a real type from a DIFFERENT module — which is why guessing here
+fails silently rather than loudly. Always fetch the `.md` twin via `docs-map.md`. Never read the
+`.swiftinterface` as a substitute for the docs; it is the catalog's source, not user-facing API
+guidance.
+
+## 7. Three things that are NOT like the web UI Kit
+
+Read these before writing any Swift, or you will carry React habits across and they will compile but not work.
+1. **The API is SETTER-based, not prop-based.** `view.set(user: user)`, `view.set(controller: self)` — chained, returning `Self`. There are no props.
+2. **There is NO composite/all-in-one component.** `CometChatMessages`, `CometChatConversationsWithMessages` and friends are **v4** and do not exist in v5 — never emit them, in any file. You compose the chat screen from three components. (Some v5 doc pages still showed them; that is tracked as IOS-DOCS-001 and corrected upstream.)
+3. **The default UX is a NAVIGATION STACK**, not side-by-side panes. The list pushes the chat screen. There is nothing to "collapse on mobile" — iOS is one-pane by construction.
+
+## 8. Kit components are VIEW CONTROLLERS, not views
+
+`CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`,
+`CometChatCompactMessageComposer`, `CometChatGroups`, `CometChatUsers`, `CometChatCallLogs` — every
+one is a `UIViewController`. The names read like views, and `addSubview` + Auto Layout is the
+reflex, but it does not compile:
+
+```
+error: value of type 'CometChatConversations' has no member 'translatesAutoresizingMaskIntoConstraints'
+error: cannot convert value of type 'CometChatConversations' to expected argument type 'UIView'
+error: value of type 'CometChatConversations' has no member 'topAnchor'
+```
+
+**Push or present it** (see the core skill's navigation stack), or, to place it inside a screen you
+own, **embed it as a child view controller** — never `addSubview(component)`:
+
+```swift
+let conversations = CometChatConversations()
+addChild(conversations)
+conversations.view.translatesAutoresizingMaskIntoConstraints = false
+container.addSubview(conversations.view)          // the .view, not the component
+NSLayoutConstraint.activate([
+    conversations.view.topAnchor.constraint(equalTo: container.topAnchor),
+    conversations.view.leadingAnchor.constraint(equalTo: container.leadingAnchor),
+    conversations.view.trailingAnchor.constraint(equalTo: container.trailingAnchor),
+    conversations.view.bottomAnchor.constraint(equalTo: container.bottomAnchor),
+])
+conversations.didMove(toParent: self)             // omitting this breaks appearance callbacks
+```
+
+Constrain `component.view`; `addChild` before adding the view and `didMove(toParent:)` after, or
+the child never receives `viewWillAppear`/`viewDidAppear` and its data never loads.

package/skills/cometchat-ios-core/references/docs-map.md

@@ -0,0 +1,124 @@
+# docs-map — CometChat iOS v5: intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query, version?)` — replaces browsing the scoped `llms-*` index.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list
+  (the conversations page path for your platform); the MCP resolves the `.md` twin and returns raw Markdown.
+  A full `https://…/docs/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated STATIC recipes that can lag the live docs (verified stale vs v7: e.g. `CometChatConversationsWithMessages`, `css-variables.css`). Treat any bundle as a hint only: RECONCILE it against the `fetch_cometchat_doc_page` result + the pack's hardening; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE`/`SDK_DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE     = https://www.cometchat.com/docs
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+```
+> **Fetch rule:** always build a URL as `DOCS_BASE` + the path shown, then append `.md`.
+> Never hardcode a host anywhere else; **never** read the kit's `.swiftinterface`, and never
+> answer API from memory.
+>
+> **Docs note (`DOCS-BACKLOG.md`):** the v4 composite components (`*WithMessages`) do not exist in
+> 5.1.22. The live pages now say so (`conversations.md` states there is no composite; `*WithMessages`
+> survives only on `upgrading-from-v4`, correctly as the v4 "before" side). Still: verify every symbol
+> against `catalogs/ios-v5.json` before emitting — the catalog is the ground truth, not the docs.
+
+## The convention
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim Swift + an "AI Integration Quick Reference"
+block: component, package, props, callbacks).
+```
+Fetch:  {DOCS_BASE}/ui-kit/ios/conversations.md
+```
+Fallback order: `.md` twin → if it 404s, the same URL **without** `.md` (HTML) → **never** the
+`.swiftinterface`, never memory.
+
+## Scoped iOS v5 index
+```
+{DOCS_BASE}/ui-kit/ios/llms-ios-v5.md
+```
+> Covers all 51 iOS UI Kit v5 pages, and its **"Task guides (recipes)"** section is the source for
+> the guide list below. Prefer this index over the site-wide `{DOCS_BASE}/llms.txt` (large; last
+> resort). The twin of React's `llms-react-v7.md` and Angular's `llms-angular-v5.md`.
+> If this path 404s, fall back to the trigger table below.
+
+## SDK docs — the FALLBACK reference (a feature the UI Kit has NO component for)
+The rule of the pack: **for every feature, first check whether the UI Kit has a component for it**
+(the table below + `catalogs/ios-v5.json`). **If it does — USE it. If it does NOT** (AI agents,
+campaigns, moderation, add-members, transient messages, low-level presence, webhooks) **— drop to the
+Chat SDK and call its method directly.** The SDK is already linked under the kit. Look the method up —
+never guess:
+- **SDK index:** prefer the scoped `{SDK_DOCS_BASE}/sdk/ios/llms-ios-v4.md` — it routes every iOS
+  Chat SDK v4 page by intent. If it 404s, fall back to `{SDK_DOCS_BASE}/sdk/ios/overview.md` and
+  the page for the area.
+- **Convention:** `{SDK_DOCS_BASE}/sdk/ios/<page>` + `.md`. Each page opens with an **"AI Integration
+  Quick Reference"** accordion (package · import · key methods) — read that FIRST.
+- **Worked example (the kit ships no component):** adding group members →
+  `{SDK_DOCS_BASE}/sdk/ios/group-add-members.md` →
+  `CometChat.addMembersToGroup(guid:groupMembers:bannedUIDs:onSuccess:onError:)`, driven from a
+  `CometChatUsers` picker in `selectionMode`.
+
+## Don't fetch the hot path — it's baked
+Install, the exact version trio, `init → login → render`, the golden-path composition and its five
+layout rules are BAKED in `cometchat-ios-core`. Fetch ONLY for exhaustive API, long-tail components,
+theming tokens, or feature enablement.
+
+## The 80% trigger table  (URL = `{DOCS_BASE}` + path, then append `.md`)
+| Intent | Path (append `.md`) |
+|---|---|
+| install / init / login / permissions | `/ui-kit/ios/getting-started` |
+| conversation list → chat screen (THE core recipe) | `/ui-kit/ios/ios-conversation` |
+| 1:1 or group chat from a user/group list | `/ui-kit/ios/ios-one-to-one-chat` |
+| tab-based app | `/ui-kit/ios/ios-tab-based-chat` |
+| conversation list (full API) | `/ui-kit/ios/conversations` |
+| message list · composer · header | `/ui-kit/ios/message-list` · `message-composer` · `message-header` |
+| users · groups · group members | `/ui-kit/ios/users` · `groups` · `group-members` |
+| threads | `/ui-kit/ios/threaded-messages-header` |
+| search | `/ui-kit/ios/search` |
+| call buttons · incoming · outgoing · ongoing · logs | `/ui-kit/ios/call-buttons` · `incoming-call` · `outgoing-call` · `ongoing-call` · `call-logs` |
+| calling setup | `/ui-kit/ios/calling-integration` |
+| AI features / assistant history | `/ui-kit/ios/ai-features` · `/ui-kit/ios/ai-assistant-chat-history` |
+| theming: tokens · colors · per-component · bubbles | `/ui-kit/ios/theme-introduction` · `color-resources` · `component-styling` · `message-bubble-styling` |
+| localization · sounds | `/ui-kit/ios/localize` · `/ui-kit/ios/sound-manager` |
+| formatters (mentions · shortcuts) | `/ui-kit/ios/mentions-formatter-guide` · `shortcut-formatter-guide` |
+| message templates | `/ui-kit/ios/message-template` |
+| events | `/ui-kit/ios/events` |
+| extensions (dashboard-gated) | `/ui-kit/ios/extensions` |
+| full component list | `/ui-kit/ios/components-overview` |
+| v4 → v5 upgrade | `/ui-kit/ios/upgrading-from-v4` |
+| push notifications | `/notifications/push-overview` |
+
+## Task guides (recipes) — for a whole FEATURE, BUILD FROM the guide + COMPARE against it
+For a TASK ask (a whole capability, not one component's API), the docs ship **end-to-end guides**. iOS
+has **nine** — more than React:
+`guide-overview` · `guide-new-chat` · `guide-group-chat` · `guide-group-ownership` ·
+`guide-threaded-messages` · `guide-message-privately` · `guide-block-unblock-user` ·
+`guide-call-log-details` · `guide-ai-agent`
+(at `{DOCS_BASE}/ui-kit/ios/<guide>.md`). Use the matching guide **two ways**:
+1. **As the implementation SOURCE** — build the feature from the official recipe, adapted
+   **ADDITIVELY** into the user's app (reuse their navigation, auth and layout; never drop in the
+   guide's standalone shell).
+2. **As a COMPLETENESS check** — after you emit, DIFF your implementation against the guide: every
+   component, call and affordance it shows. Fill any gap.
+
+> **Then apply the baked HARDENING DELTAS — the guide is the BASELINE, not the whole truth.**
+> The guides do not carry the runtime lessons: `set(controller:)` on every component or its
+> affordances are inert; the composer pinned to the **safe-area bottom** (NOT `keyboardLayoutGuide` — the kit composer already handles the keyboard, and double-pinning collapses the list)
+> the recipe shows; explicit vertical division or the list collapses; the host nav bar hidden or you
+> get two headers; and the thread trap — `CometChatThreadedMessageHeader` takes
+> `set(parentMessage:)`; the LIST takes `set(user:parentMessage:withParent:)` (parent in the same
+> call as the target); the composer takes `set(user:)` + `set(parentMessageId:)`.
+
+**No matching guide? → build from this skill's baked golden path** and fetch each component's `.md`
+twin for exact API. The guide is an enhancement when present, never a hard dependency.
+
+## Not in the table?
+Fetch the page from the trigger table nearest your intent, or the site-wide `{DOCS_BASE}/llms.txt`.
+Never guess a path; never read the `.swiftinterface`; never answer API from memory. If a symbol is not
+in `catalogs/ios-v5.json`, it does not exist in v5 — do not emit it, whatever a page says.

package/skills/cometchat-ios-core/references/install.md

@@ -0,0 +1,23 @@
+# Install — Swift Package Manager
+
+The full install detail. The entry keeps only the three pinned versions and the SPM-only rule.
+
+**Use SPM. Do not use CocoaPods and do not offer it as an option**, even if the user's project already has a `Podfile`: CocoaPods distribution is being wound down and its spec repo is going read-only, so a Podfile-based integration cannot receive future releases. A project already on CocoaPods should be moved to SPM as part of adding CometChat.
+
+Add these three packages. The kit is a **prebuilt binary compiled against ONE Chat SDK version** and SPM does not resolve that transitively, so the versions are **exact, not floors** — overriding either side is unsupported and either fails to build or crashes at runtime.
+
+| Package | Repository | Version |
+|---|---|---|
+| `CometChatUIKitSwift` | `https://github.com/cometchat/cometchat-uikit-ios` | **exactly 5.1.22** |
+| `CometChatSDK` | `https://github.com/cometchat/chat-sdk-ios` | **exactly 4.1.7** |
+| `CometChatCallsSDK` | `https://github.com/cometchat/calls-sdk-ios` | **exactly 5.0.3** |
+
+> **All three must be added BY HAND — including the Calls SDK, and including for a chat-only app.**
+> This is a **packaging regression in 5.1.19**, not a design requirement, so treat it as a workaround with a shelf life rather than a permanent rule:
+> - 5.1.19's compiled `.swiftinterface` carries `import CometChatCallsSDK`, and Swift requires every import in an interface to be resolvable — so the module must be present to compile **any** integration, even one with no calling.
+> - Nothing in the kit's **public API actually uses a CallsSDK type** (0 references), and **5.1.16 and 5.1.18 have no such import at all**. It appears in 5.1.19 only. That makes it an internal import leaking into the public interface, not an intentional dependency.
+> - The kit's own `Package.swift` declares **neither** `CometChatSDK` nor `CometChatCallsSDK`, so SPM cannot supply them. Omit the Calls SDK and the build fails with `unable to resolve module dependency: 'CometChatCallsSDK'`.
+>
+> If a future release drops that import, the Calls SDK goes back to being calls-only and belongs to `cometchat-ios-calls`. Re-check the interface before assuming this still applies.
+
+Deployment target **iOS 15.1+**. Add the usage descriptions the kit's media features need to `Info.plist` (camera, microphone, photo library) — see `references/setup-credentials.md`.

package/skills/cometchat-ios-core/references/layout.md

@@ -0,0 +1,219 @@
+# The iOS sizing standard — why each rule exists
+
+> Every rule below was measured on a simulator by the native review harness (iPhone 16 / iOS
+> 18.2, kit 5.1.22), not reasoned across from the web UI Kit. Where a claim is unverified, it
+> says so.
+
+v5 ships **no composite chat component**. The host composes `CometChatMessageHeader` +
+`CometChatMessageList` + `CometChatCompactMessageComposer` and owns the layout. That means the sizing
+below is YOUR responsibility — the kit will not correct it, and every failure here is a RUNTIME
+failure that compiles perfectly.
+
+## Rule 0 — a component is a `UIViewController`, so constrain `component.view`
+
+Every kit component (`CometChatConversations`, `CometChatMessageList`, `CometChatGroups`, …)
+subclasses `UIViewController`, **not** `UIView`. Treating one as a view does not compile:
+
+```
+error: value of type 'CometChatConversations' has no member 'translatesAutoresizingMaskIntoConstraints'
+error: cannot convert value of type 'CometChatConversations' to expected argument type 'UIView'
+error: value of type 'CometChatConversations' has no member 'topAnchor'
+```
+
+Push or present it, or — to place it inside a screen you own — embed it as a child view
+controller and constrain its `.view`:
+
+```swift
+let conversations = CometChatConversations()
+addChild(conversations)                                  // BEFORE adding the view
+conversations.view.translatesAutoresizingMaskIntoConstraints = false
+container.addSubview(conversations.view)                 // the .view, not the component
+NSLayoutConstraint.activate([
+    conversations.view.topAnchor.constraint(equalTo: container.topAnchor),
+    conversations.view.leadingAnchor.constraint(equalTo: container.leadingAnchor),
+    conversations.view.trailingAnchor.constraint(equalTo: container.trailingAnchor),
+    conversations.view.bottomAnchor.constraint(equalTo: container.bottomAnchor),
+])
+conversations.didMove(toParent: self)                    // AFTER; omitting it breaks
+                                                         // viewWillAppear/viewDidAppear,
+                                                         // so the child never loads data
+```
+
+Unlike the rules below, this one fails at COMPILE time — which is why it belongs first: the
+sizing rules only matter once the thing builds. Full treatment in `references/anti-patterns.md`.
+
+## Rule 1 — exactly one target
+
+`conversationWith` is a `User` **or** a `Group`, never both. Set one:
+
+```swift
+if let user { list.set(user: user) } else if let group { list.set(group: group) }
+```
+
+Setting both is not a compile error; it produces a surface bound to the wrong conversation.
+
+## Rule 2 — `set(controller:)` is REQUIRED. Omitting it CRASHES the app.
+
+Call `set(controller: self)` on the header, the list and the composer. It hands the kit a
+controller to present its OWN sub-screens from — the action sheet behind a long-press, the media
+picker, the details screen.
+
+**Measured: omitting it is not a degradation, it is a crash.** Long-press any message in a surface
+built without `set(controller:)` and the app dies:
+
+```
+EXC_BREAKPOINT (SIGTRAP) — nil force-unwrap
+  MessagePopupViewController.buildUI()
+  ← CometChatMessageList.onCellLongPressGestureRecognized
+  ← CometChatMessageBubble.onLongPressEnded
+```
+
+The kit force-unwraps the presenting controller it was never given. There is no error, no no-op,
+no degraded mode — the process terminates on a gesture any user will perform within minutes.
+
+**An earlier version of this file said the opposite.** It reported that omitting `set(controller:)`
+"affects neither rendering nor primary navigation" and called the kit's presented sub-screens
+"genuinely untested" — because our own gate only tapped, and a tap never reaches this path. The
+sub-screens were testable all along; the answer is a crash. `Fixtures/broken-no-controller` scored
+WORKING for the entire life of this project while modelling an app that dies on first long-press.
+The gate now long-presses and detects process death, so the fixture fails as it always should have.
+
+The lesson is the one this pack keeps relearning: an untested path reported as "probably fine" is a
+claim, not a measurement. Say "untested" and stop there, or test it.
+
+## Rule 3 — pin to the safe area, top AND bottom
+
+```swift
+headerView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor)
+composerView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
+```
+
+Both anchors come straight from the published recipe. **Do not pin the composer to
+`view.keyboardLayoutGuide.topAnchor`.** `CometChatCompactMessageComposer` does its own keyboard
+adjustment, so that double-applies the offset. Measured on iPhone 16 / iOS 18.2 with the keyboard
+raised:
+
+<!-- Provenance: the table below was measured against `CometChatMessageComposer`, which the golden
+     path used before it moved to the compact composer. The rule carries over because the compact
+     composer self-adjusts the same way — it registers
+     `UIResponder.keyboardWillChangeFrameNotification` and offsets itself (source-verified on
+     master-v5). The numbers are NOT a re-measurement of the compact composer; re-measure before
+     quoting them as such. -->
+
+
+| | safe-area pin (correct) | keyboardLayoutGuide pin |
+|---|---|---|
+| message list | `(0, 109, 393, 267)` — survives | **height 0 — gone** |
+| composer internal stack | on the keyboard top | **`(0, -249, 393, 0)`** |
+
+The user taps to type and the entire conversation disappears, along with the text field they were
+about to type into. It compiles, and it looks perfect until that first tap.
+
+This skill previously taught the keyboardLayoutGuide pin as a "hardening delta" over the docs, and
+asserted it was simulator-verified. That assertion was false: no gate raised the keyboard, so
+nothing could contradict it. The gate now taps the composer and grades whether a list survives
+above the keyboard (`Fixtures/broken-keyboard-double-pin` is the standing regression case).
+
+## Rule 4 — divide the vertical space EXPLICITLY
+
+The list must be pinned top and bottom so it scrolls internally instead of growing its parent:
+
+```swift
+messageListView.topAnchor.constraint(equalTo: headerView.bottomAnchor),
+messageListView.bottomAnchor.constraint(equalTo: composerView.topAnchor),
+```
+
+Without both, the surface collapses to its intrinsic content height. **This is the defect the
+harness catches most often**: a collapsed pane measured 10% of screen height where a correct one
+measures ~90%. It compiles, it mounts, and a launch-only screenshot of the conversation list
+looks perfectly fine — the collapse is one tap away, on the pushed screen.
+
+## Rule 5 — one navigation bar, not two
+
+`CometChatMessageHeader` carries its own title and back control. Left alone, `UINavigationController`
+adds a second bar above it:
+
+```swift
+override func viewDidLoad() {
+    super.viewDidLoad()
+    navigationController?.setNavigationBarHidden(true, animated: false)
+}
+override func viewWillDisappear(_ animated: Bool) {
+    super.viewWillDisappear(animated)
+    navigationController?.setNavigationBarHidden(false, animated: true)   // restore for the list
+}
+```
+
+Hide it on the message screen only, and restore it on the way out — hiding it globally strips
+the conversation list's own bar.
+
+## Navigation, not panes
+
+The web kit's default is side-by-side. iOS composes by NAVIGATION: the conversation list
+pushes the message pane. Wire selection or the list is a dead end:
+
+```swift
+conversations.set(onItemClick: { [weak nav] conversation, _ in
+    let vc = MessagesVC()
+    vc.user  = conversation.conversationWith as? CometChatSDK.User
+    vc.group = conversation.conversationWith as? CometChatSDK.Group
+    nav?.pushViewController(vc, animated: true)
+})
+```
+
+## Surface errors
+
+A failed load and an empty account render the SAME empty list. Wire `set(onError:)` or a
+failure is indistinguishable from "no conversations yet".
+
+### Own the bar centrally — the per-screen recipe does not survive real flows
+
+The published recipe (hide in `viewDidLoad`, restore in `viewWillDisappear`) works for a single
+push and breaks in three flows we measured:
+
+| flow | result |
+|---|---|
+| activate the list's search field, then open a conversation | host bar returns |
+| chat → thread | host bar returns — and on the THREAD screen that is what you want: it has no back control of its own (see below) |
+| pop back thread → chat | chat screen ends with two headers |
+
+Measured on the search flow: `(0,109,393,579)` becomes `(0,199,393,488)` — two headers, 91pt lost.
+
+**Why the obvious fixes fail.** `viewDidLoad` runs once, so it cannot correct a later transition.
+`viewWillAppear` cannot either: the INCOMING screen's `viewWillAppear` runs BEFORE the outgoing
+screen's `viewWillDisappear`, so the restore lands last and clobbers the hide. `isMovingFromParent`
+handles the pushes but not the pop-back.
+
+**What works, measured, with no flash** — decide the bar on the navigation controller:
+
+```swift
+final class NavBarCoordinator: NSObject, UINavigationControllerDelegate {
+    // Hide the bar ONLY on screens whose kit header has its own back control (your composed chat
+    // screen). Do NOT hide it on a pushed thread screen: CometChatThreadedMessageHeader ships NO
+    // back/close of its own (measured — its public surface is hideReceipt/hideBubbleHeader/
+    // hideReplyCount/hideReplyCountBar/hideAvatar plus setters), and edge-swipe does not pop it.
+    // Hiding the host bar there removes the ONLY exit and strands the user. Same rule for any
+    // pushed kit list (CometChatGroupMembers etc.): keep the host bar, hide the KIT's — see the
+    // placement skill.
+    private func shouldHide(_ vc: UIViewController) -> Bool { vc is MessagesVC }   // your chat screens ONLY
+
+    func navigationController(_ nav: UINavigationController, willShow vc: UIViewController, animated: Bool) {
+        nav.setNavigationBarHidden(shouldHide(vc), animated: animated)
+    }
+    func navigationController(_ nav: UINavigationController, didShow vc: UIViewController, animated: Bool) {
+        let want = shouldHide(vc)                       // re-assert ONLY if clobbered, so no flash
+        if nav.isNavigationBarHidden != want { nav.setNavigationBarHidden(want, animated: false) }
+    }
+}
+```
+
+Hold the coordinator somewhere that outlives the push — `UINavigationController.delegate` is weak.
+With it in place the message pane measures `(0,109,393,579)` through all four flows.
+
+**Note on how this was found.** An earlier pass reported the defect with `CometChatSearch` as the
+trigger; a fixture built around presenting and dismissing `CometChatSearch` measured clean every
+time, and this file recorded it as unreproduced. The real trigger is activating the list's OWN
+`UISearchController` — which is simply how a user reaches search, so the original report was right
+about the symptom and wrong about the cause. `Fixtures/broken-navbar-after-search` is the standing
+regression case, and the gate now asserts `navBars == 0` on the message pane, because the collapse
+ratio cannot see this (488/852 = 57%, over the 50% minimum).