@cometchat/skills 4.4.2 → 5.0.0

package/contracts.ios-v5.json

@@ -0,0 +1,436 @@
+{
+  "generatedFrom": "Minimum-completeness oracle for the iOS UI Kit v5 family. Capabilities are NOT ported from contracts.json (web-react v7) — each was checked against the shipped CometChatUIKitSwift 5.1.19 public .swiftinterface, and the surface/layout ones were verified EMPIRICALLY by the native harness on a simulator (test-suite/harness/ios, Fixtures/good-core-surface vs the three broken fixtures). Where a React capability has no iOS equivalent it is recorded in `notTransferred` with the reason, rather than silently dropped.",
+  "family": "ios-uikit",
+  "major": "v5",
+  "catalog": "ios-v5",
+  "notTransferred": [
+    {
+      "webCapability": "error-boundary-wrap",
+      "reason": "No CometChatErrorBoundary equivalent ships in the iOS kit (0 matches for 'errorboundary' in the 5.1.19 interface). The nearest real affordances are per-component: errorStateView / errorStateTitleText / errorStateSubTitleText on CometChatListBase, and set(onError:) on the list components. Covered by `error-state-handled` below."
+    },
+    {
+      "webCapability": "in-chat-message-search-default",
+      "reason": "CometChatMessageHeader has NO search affordance on iOS — its only menu API is set(options:) ([CometChatPopupMenu.MenuItem]). React's header search icon has no counterpart, so an in-chat scoped search is NOT part of the iOS default surface. Global search stays (Conversations.onSearchClick -> CometChatSearch)."
+    },
+    {
+      "webCapability": "prepared-ancestor-chain / pinned-viewport-height / column-min-height-0 / no-load-transition-reflow",
+      "reason": "These are CSS-cascade concerns with no native analogue. The equivalent iOS obligations are `safe-area-pinned`, `keyboard-avoiding-composer` and `explicit-vertical-division` below — all three empirically verified by the harness rather than reasoned by analogy."
+    },
+    {
+      "webCapability": "responsive-one-pane-on-mobile",
+      "reason": "iOS is one-pane by construction: the default UX is a UINavigationController push, not side-by-side panes. There is nothing to collapse. (An iPad split-view variant is a placement concern, not a core-surface floor.)"
+    },
+    {
+      "webCapability": "active-item-reflected",
+      "reason": "React needs activeConversation because the list stays on screen beside the message pane. In a push-navigation stack the list is covered, so there is no active row to reflect. No activeConversation/selected-row API exists on CometChatConversations. Revisit if an iPad split-view placement lands."
+    }
+  ],
+  "contracts": [
+    {
+      "for": "core-chat-surface",
+      "kind": "feature",
+      "min_capabilities": [
+        "init-login-gate",
+        "conversations-list",
+        "message-pane-header-list-composer",
+        "single-target-user-or-group",
+        "controller-wired",
+        "navigation-push-to-messages",
+        "safe-area-pinned",
+        "keyboard-avoiding-composer",
+        "explicit-vertical-division",
+        "no-duplicate-navigation-bar",
+        "affordances-wired-or-hidden",
+        "error-state-handled",
+        "prod-auth-token-guidance",
+        "no-double-keyboard-pin"
+      ],
+      "docs_topic": "/ui-kit/ios/ios-conversation",
+      "notes": "APP-LEVEL floor for an unscoped 'add chat'. HOST-COMPOSED — v5 ships no composite component (IOS-DOCS-001), so the developer owns the chat screen and the navigation. Capability meanings, all verified on device by the harness: `single-target-user-or-group` — pass exactly ONE of user/group to header, list and composer, taken from conversation.conversationWith; never both. `controller-wired` — call set(controller:) on all three; this is an iOS-specific obligation with NO React analogue, and omitting it leaves the kit's built-in affordances rendering but silently inert when tapped, which no compile gate catches. `navigation-push-to-messages` — wire set(onItemClick:) to push the chat screen; an unwired list is the iOS form of a dead-end affordance. `safe-area-pinned` — header to view.safeAreaLayoutGuide.topAnchor so nothing sits under the notch. `keyboard-avoiding-composer` — pin the composer to view.keyboardLayoutGuide.topAnchor (iOS 15+; the kit's floor is 15.1), NOT to safeAreaLayoutGuide.bottomAnchor as the published recipe shows — the doc's version is covered by the keyboard the moment the user types. This is a HARDENING DELTA on top of the guide, and the gap is logged for the docs. `explicit-vertical-division` — header fixed height, composer at the bottom, list filling between, so the list scrolls internally instead of growing its parent. `no-duplicate-navigation-bar` — the kit header carries its own title and back control, so hide the host navigation bar in viewDidLoad and restore it in viewWillDisappear, or the screen shows two headers."
+    },
+    {
+      "for": "chat-experience",
+      "kind": "feature",
+      "min_capabilities": [
+        "selector-conversations",
+        "selector-users-groups-tabs",
+        "message-pane-header-list-composer",
+        "single-target-user-or-group",
+        "controller-wired",
+        "navigation-push-to-messages",
+        "screen-dismiss-round-trip",
+        "safe-area-pinned",
+        "keyboard-avoiding-composer",
+        "explicit-vertical-division",
+        "no-dead-end-affordances",
+        "error-state-handled"
+      ],
+      "docs_topic": "/ui-kit/ios/ios-tab-based-chat",
+      "notes": "The grown app: users/groups tabs, group details, call logs. The tab host is a UITabBarController the developer owns. `screen-dismiss-round-trip` — a PUSHED screen gets its back control from UINavigationController for free, but anything PRESENTED modally (search, details, a picker) owns its own dismissal; an opened modal with no way out is the iOS form of the AUDIT-017 defect."
+    },
+    {
+      "for": "threaded-replies",
+      "kind": "feature",
+      "min_capabilities": [
+        "thread-header-with-parent-message",
+        "thread-list-and-composer-scoped",
+        "single-target-user-or-group",
+        "controller-wired",
+        "screen-dismiss-round-trip"
+      ],
+      "docs_topic": "/ui-kit/ios/guide-threaded-messages",
+      "notes": "THREE components, TWO different parent APIs — a real trap, verified against 5.1.19: CometChatThreadedMessageHeader takes set(parentMessage: BaseMessage), while CometChatMessageList and CometChatCompactMessageComposer take set(parentMessageId: Int). The thread list and composer ALSO need the conversation target (user or group) alongside the parent id — the iOS counterpart of AUDIT-060, where passing the parent alone makes replies silently never send."
+    },
+    {
+      "for": "message-search",
+      "kind": "feature",
+      "min_capabilities": [
+        "global-search-entry-wired",
+        "search-scope-set",
+        "search-result-click-wired",
+        "screen-dismiss-round-trip"
+      ],
+      "docs_topic": "/ui-kit/ios/search",
+      "notes": "GLOBAL search only on iOS (see notTransferred: the message header has no search affordance). Entry is CometChatConversations.onSearchClick — an assignable property, not a setter. Scope with set(searchIn: [SearchScope]) and offer chips with set(searchFilters:initialFilter:); there is no request builder. Results dead-end unless onConversationClicked / onMessageClicked are assigned."
+    },
+    {
+      "for": "voice-video-calls",
+      "kind": "feature",
+      "min_capabilities": [
+        "calls-sdk-linked",
+        "call-buttons-or-programmatic-initiate",
+        "incoming-call-handling",
+        "call-screen-dismiss-round-trip",
+        "call-logs"
+      ],
+      "docs_topic": "/ui-kit/ios/calling-integration",
+      "notes": "`calls-sdk-linked` is NOT optional on 5.1.19: the shipped kit interface itself does `import CometChatCallsSDK`, so the Calls SDK must be linked for ANY integration to build — including a chat-only one. That is a departure from the web pack, where the calls SDK is an add-on for the calls feature alone, and it belongs in core's install step rather than being deferred to the calls skill. Harness-pinned trio: kit 5.1.19 / CometChatSDK 4.1.7 / CometChatCallsSDK 5.0.3 — the kit is a prebuilt binary compiled against ONE SDK version and SPM does not resolve that transitively, so the versions are exact, not floors."
+    },
+    {
+      "for": "CometChatConversations",
+      "kind": "component",
+      "min_capabilities": [
+        "conversation-list",
+        "last-message-preview",
+        "unread-count",
+        "presence",
+        "receipts",
+        "realtime-updates",
+        "item-click-wired"
+      ],
+      "docs_topic": "/ui-kit/ios/conversations"
+    },
+    {
+      "for": "CometChatMessageList",
+      "kind": "component",
+      "min_capabilities": [
+        "render-messages",
+        "message-bubbles-by-type",
+        "delivery-read-receipts",
+        "reactions-when-enabled",
+        "thread-open",
+        "realtime-updates"
+      ],
+      "docs_topic": "/ui-kit/ios/message-list"
+    },
+    {
+      "for": "CometChatCompactMessageComposer",
+      "kind": "component",
+      "min_capabilities": [
+        "send-text",
+        "attach-media-file",
+        "voice-recording"
+      ],
+      "docs_topic": "/ui-kit/ios/compact-message-composer"
+    },
+    {
+      "for": "CometChatGroupMembers",
+      "kind": "component",
+      "min_capabilities": [
+        "view-members",
+        "kick-member",
+        "ban-member",
+        "change-scope",
+        "search-members"
+      ],
+      "docs_topic": "/ui-kit/ios/group-members",
+      "notes": "Adding members is NOT a component — the kit ships none (CometChatAddMembers does not exist). It is the documented SDK fallback: build a picker from CometChatUsers with selectionMode, then CometChat.addMembersToGroup(guid:groupMembers:bannedUIDs:onSuccess:onError:). UI Kit first, SDK where the kit has nothing."
+    }
+  ],
+  "_detectors": "G4 checks a capability by looking for EVIDENCE of it in the emitted Swift. A regex is evidence of presence, not proof of correctness — it can confirm the emit pins to keyboardLayoutGuide, not that the result looks right; that is G6's job. Capabilities that cannot honestly be evidenced by an emit carry kind:'unchecked' with a reason, and contract-check.mjs REPORTS them rather than counting them as met. A gate that silently scores an undetectable capability green is the phantom-green this pack exists to prevent.",
+  "capabilityDetectors": {
+    "conversations-list": {
+      "kind": "regex",
+      "any": [
+        "CometChatConversations\\s*\\("
+      ],
+      "why": "the list component is instantiated"
+    },
+    "message-pane-header-list-composer": {
+      "kind": "regex",
+      "all": [
+        "CometChatMessageHeader\\s*\\(",
+        "CometChatMessageList\\s*\\(",
+        "CometChat(?:Compact)?MessageComposer\\s*\\("
+      ],
+      "why": "all three message components are composed (either composer satisfies this — the skill teaches the compact one, but composition is what this gate checks)"
+    },
+    "single-target-user-or-group": {
+      "kind": "regex",
+      "all": [
+        "as\\?\\s*User",
+        "as\\?\\s*Group"
+      ],
+      "why": "conversationWith is narrowed to exactly one of User/Group"
+    },
+    "controller-wired": {
+      "kind": "regex",
+      "minCount": {
+        "set\\(controller:": 3
+      },
+      "why": "set(controller:) on header, list and composer — the docs' recipe calls it on all three"
+    },
+    "navigation-push-to-messages": {
+      "kind": "regex",
+      "any": [
+        "pushViewController"
+      ],
+      "why": "selection actually navigates somewhere"
+    },
+    "safe-area-pinned": {
+      "kind": "regex",
+      "any": [
+        "safeAreaLayoutGuide"
+      ],
+      "why": "the surface is pinned to the safe area"
+    },
+    "keyboard-avoiding-composer": {
+      "kind": "regex",
+      "all": [
+        "composerView\\.bottomAnchor|composer\\.bottomAnchor"
+      ],
+      "why": "the composer pins to safeAreaLayoutGuide.bottomAnchor and lets the kit handle the keyboard. This detector previously REQUIRED keyboardLayoutGuide, so G4 actively enforced a defect: an emit that followed the published recipe FAILED the contract, and the double-pinned version that destroys the screen PASSED it."
+    },
+    "explicit-vertical-division": {
+      "kind": "regex",
+      "all": [
+        "heightAnchor\\.constraint",
+        "bottomAnchor"
+      ],
+      "why": "header height fixed and the list bounded, so it scrolls internally"
+    },
+    "no-duplicate-navigation-bar": {
+      "kind": "regex",
+      "any": [
+        "setNavigationBarHidden"
+      ],
+      "why": "the host nav bar is hidden so the kit header is not a second one"
+    },
+    "error-state-handled": {
+      "kind": "regex",
+      "any": [
+        "set\\(onError:",
+        "errorStateView",
+        "set\\(errorView:"
+      ],
+      "why": "failures surface somewhere instead of looking like an empty list"
+    },
+    "screen-dismiss-round-trip": {
+      "kind": "regex",
+      "any": [
+        "dismiss\\(",
+        "popViewController",
+        "setNavigationBarHidden\\(false"
+      ],
+      "why": "anything opened can be closed"
+    },
+    "selector-conversations": {
+      "kind": "regex",
+      "any": [
+        "CometChatConversations\\s*\\("
+      ]
+    },
+    "selector-users-groups-tabs": {
+      "kind": "regex",
+      "all": [
+        "CometChatUsers\\s*\\(",
+        "CometChatGroups\\s*\\("
+      ]
+    },
+    "thread-header-with-parent-message": {
+      "kind": "regex",
+      "all": [
+        "CometChatThreadedMessageHeader",
+        "set\\(parentMessage:"
+      ],
+      "why": "the thread header takes the message object, unlike the list/composer"
+    },
+    "thread-list-and-composer-scoped": {
+      "kind": "regex",
+      "all": [
+        "set\\(parentMessageId:",
+        "set\\((user|group):"
+      ],
+      "why": "parent id AND the conversation target, or replies never send"
+    },
+    "global-search-entry-wired": {
+      "kind": "regex",
+      "any": [
+        "onSearchClick"
+      ]
+    },
+    "search-scope-set": {
+      "kind": "regex",
+      "any": [
+        "set\\(searchIn:",
+        "set\\(searchFilters:"
+      ]
+    },
+    "search-result-click-wired": {
+      "kind": "regex",
+      "any": [
+        "onConversationClicked",
+        "onMessageClicked"
+      ]
+    },
+    "calls-sdk-linked": {
+      "kind": "regex",
+      "any": [
+        "CometChatCallsSDK"
+      ]
+    },
+    "call-buttons-or-programmatic-initiate": {
+      "kind": "regex",
+      "any": [
+        "CometChatCallButtons",
+        "onVoiceCallClick",
+        "onVideoCallClick"
+      ]
+    },
+    "incoming-call-handling": {
+      "kind": "regex",
+      "any": [
+        "CometChatIncomingCall",
+        "CometChatCallEventListener"
+      ]
+    },
+    "call-screen-dismiss-round-trip": {
+      "kind": "regex",
+      "any": [
+        "set\\(onCancelClick:",
+        "dismiss\\("
+      ]
+    },
+    "call-logs": {
+      "kind": "regex",
+      "any": [
+        "CometChatCallLogs"
+      ]
+    },
+    "item-click-wired": {
+      "kind": "regex",
+      "any": [
+        "set\\(onItemClick:"
+      ]
+    },
+    "init-login-gate": {
+      "kind": "unchecked",
+      "why": "the review harness performs init+login before mounting the emit, so an emit CANNOT evidence it. Enforced instead by the harness refusing to mount until login resolves."
+    },
+    "prod-auth-token-guidance": {
+      "kind": "unchecked",
+      "why": "prose guidance in the skill, not code in the emit. Covered by the skill checklist, not by G4."
+    },
+    "affordances-wired-or-hidden": {
+      "kind": "unchecked",
+      "why": "already enforced by G3 via golden.defaultOnAffordances — re-checking here would double-count, not double-check."
+    },
+    "no-dead-end-affordances": {
+      "kind": "unchecked",
+      "why": "same as above — G3 owns this."
+    },
+    "last-message-preview": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "unread-count": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "presence": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "receipts": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "realtime-updates": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "send-text": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "attach-media-file": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "voice-recording": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "render-messages": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "message-bubbles-by-type": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "delivery-read-receipts": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "reactions-when-enabled": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "thread-open": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "conversation-list": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "view-members": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "kick-member": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "ban-member": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "change-scope": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "search-members": {
+      "kind": "unchecked",
+      "why": "a behaviour the KIT renders once the component is mounted with a target — no emit code evidences it, so a regex would only prove the component exists (already G0/G1) while implying more was checked. Runtime-only: G6 sees it or it does not."
+    },
+    "no-double-keyboard-pin": {
+      "kind": "regex",
+      "none": [
+        "keyboardLayoutGuide"
+      ],
+      "why": "keyboardLayoutGuide must NOT appear: CometChatCompactMessageComposer does its own keyboard adjustment, so pinning to it double-applies the offset and collapses the message list to height 0 (measured, iPhone 16 / iOS 18.2)."
+    }
+  }
+}

package/contracts.json

@@ -0,0 +1,82 @@
+{
+  "generatedFrom": "cometchat.com/docs — ui-kit/react component pages (conversations, group-members) verified 2026-07-29; message-composer/message-list minimums from features.json + component docs (entries noting VERIFY need the exact toggle confirmed).",
+  "family": "web-react",
+  "major": "v7",
+  "capabilityDetectors": {
+    "global-conversation-search": {
+      "kind": "regex",
+      "why": "global search is rendered AND entered from CometChatConversations' OWN search bar affordance (showSearchBar + onSearchBarClicked) — NOT a standalone <CometChatSearch> stacked above the list. Clicking the conversation list's search bar opens the search view (the canonical React v7 placement; parity with Angular searchBarClick / iOS onSearchClick).",
+      "all": [
+        "CometChatSearch",
+        "onSearchBarClicked"
+      ]
+    }
+  },
+  "contracts": [
+    {
+      "for": "core-chat-surface",
+      "kind": "feature",
+      "min_capabilities": ["error-boundary-wrap", "init-login-gate", "conversations-list", "message-pane-header-list-composer", "threaded-replies-panel-default", "thread-surface-differentiated", "in-chat-message-search-default", "global-conversation-search", "affordances-wired-or-hidden", "active-item-reflected", "panel-close-round-trip", "prepared-ancestor-chain", "pinned-viewport-height", "column-min-height-0", "no-load-transition-reflow", "responsive-one-pane-on-mobile", "prod-auth-token-guidance"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/overview",
+      "notes": "APP-LEVEL floor for an unscoped 'add chat' — the production-ready CORE surface (features.json 'core-chat-surface'; composition in .claude/skills/cometchat-skill-creator/references/FULL-APP-BLUEPRINT.md §7). Capabilities are the whole surface, not per-component features: wrap the app in CometChatErrorBoundary; gate render on init->login; a CometChatConversations LIST <-> a message pane (MessageHeader+MessageList+MessageComposer); THREADED REPLIES ARE INCLUDED BY DEFAULT (threaded-replies-panel-default): wire MessageList onThreadRepliesClick -> a thread panel (CometChatThreadHeader + a thread MessageList + MessageComposer scoped to parentMessageId, with a back/close round-trip) — set hideReplyInThreadOption ONLY if the user explicitly opts out of threads; the thread reads as a DISTINCT surface (thread-surface-differentiated): scope --cometchat-message-list-bg: var(--cometchat-background-color-01) on the thread wrapper so the thread MESSAGE LIST matches its header/composer and differs from the main list's -03 — REQUIRED because the message list paints its OWN opaque bg and does NOT inherit a wrapper background (a wrapper bg alone leaves the thread list undifferentiated; verified vs 7.1.0 CSS, AUDIT-020/024). TWO searches, both default-on: (a) GLOBAL conversation search over the LIST column (Conversations onSearchBarClicked -> CometChatSearch, no uid/guid) or showSearchBar={false}; (b) IN-CHAT scoped message search in the SIDE PANEL (MessageHeader onSearchOptionClicked -> CometChatSearch with the current uid/guid so it searches only that chat, mutually exclusive with the thread, onBack closes, onMessageClicked jumps to the hit) — the sample-app CometChatHome pattern; opt-out via showSearchOption={false}. Wire-or-hide any other default-on affordance so nothing dead-ends; SIZE the surface per the reflow-free-surface standard (skills/cometchat-react-v7-core/references/layout.md) so it is full-size from frame 1 and never reflows — the four sizing capabilities are checkable invariants, not one vague token: prepared-ancestor-chain = html,body,#root{height:100%;margin:0} (prepare a bare app's missing chain AND reset the Vite/CRA/Next scaffold center+cap+pad, AUDIT-019); pinned-viewport-height = the surface box pinned to a content-INDEPENDENT height (full-page 100dvh; embedded a fixed height or a sized grid/flex cell) — NEVER min-height/auto; column-min-height-0 = each column height:100%;min-height:0;overflow:hidden so flex children SCROLL rather than grow the parent (sizing the root alone leaves the kit filling nothing); no-load-transition-reflow = the surface is full-size BEFORE content loads, not grow into it — render the kit's OWN loadingView/emptyView inside the pinned box so the loading->loaded swap causes zero shift (don't gate the whole surface behind a placeholder->chat swap; the kit fills its parent by design, so a content-driven box is the defect, not the kit). Collapse to one pane on mobile (header hideBackButton/onBack); and TELL the user the prod auth-token path (loginWithAuthToken; Auth Key dev-only). Complete and wired but LEAN: NOT a bare/broken two-pane demo, and NOT the whole combined app. Do NOT add selector tabs / a user-or-group details side panel / a scoped search side panel / call logs / incoming call (those are the GROWTHS -> chat-experience) or gated extensions/AI/plugins unless asked — the thread panel IS part of the default. Growing to the whole app raises the floor to the chat-experience contract below; a scoped-down ask (embed/popup/sidebar) opts into the specific placement instead. Per-pane minimums are still fixed by the CometChatConversations/MessageList/MessageComposer contracts below."
+    },
+    {
+      "for": "chat-experience",
+      "kind": "feature",
+      "min_capabilities": ["error-boundary-wrap", "selector-conversations", "selector-users-groups-calls-tabs", "message-pane-header-list-composer", "side-panel-user-group-details", "side-panel-thread", "side-panel-or-column-search", "incoming-call-handling", "active-item-reflected", "panel-close-round-trip", "prepared-ancestor-chain", "pinned-viewport-height", "column-min-height-0", "no-load-transition-reflow", "responsive-one-pane-on-mobile", "no-dead-end-affordances"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/overview",
+      "notes": "The GROW target — the whole combined single-page app, emitted when the user asks for the full app (NOT the default for a plain 'add chat' — that is core-chat-surface above). Composition in .claude/skills/cometchat-skill-creator/references/FULL-APP-BLUEPRINT.md §4. Capabilities are PANES, not per-component features: the core surface PLUS a selector (Conversations + Users/Groups/CallLogs tabs) <-> a message pane <-> a mutually-exclusive side panel (user/group details OR thread OR scoped search), CometChatIncomingCall at root, global search over the list column, all wrapped in CometChatErrorBoundary, with a mobile collapse to one pane. It is the UNION of the core surface + the growths. Wire every default-on affordance to its destination in the right pane, or hide it — nothing dead-ends. TWO composition invariants make 'nothing dead-ends' concrete (AUDIT-079): active-item-reflected = the selection is REFLECTED in the list — pass activeConversation / activeUser / activeGroup back to CometChatConversations/CometChatUsers/CometChatGroups so the selected row highlights (the kit ships these props; without them there is no active state and the user can't tell what's open); panel-close-round-trip = EVERY side panel the app opens (user/group details via CometChatGroupMembers, thread via CometChatThreadHeader, scoped/global search via CometChatSearch) MUST wire its close — onBack/onClose (the components render a back/close button whose handler is the host's job; a host-composed user-details panel must add its own close). These generalize the search/thread round-trip (AUDIT-017) to the details/members panel and add active-state reflection; both apply to core-chat-surface too. SIZE it per the reflow-free-surface standard (skills/cometchat-react-v7-core/references/layout.md): the same four sizing invariants as core-chat-surface (prepared-ancestor-chain, pinned-viewport-height, column-min-height-0, no-load-transition-reflow) apply to the three-column app — the 3-column CSS in cometchat-react-v7-placement satisfies them; the surface must be full-size from frame 1 and not grow-into-place as content loads. Least-code = drop-ins for HOW. Do NOT turn on gated extensions/AI/plugins (that's a separate opt-in). Per-pane minimums are still fixed by the CometChatConversations/MessageList/MessageComposer/GroupMembers contracts below."
+    },
+    {
+      "for": "CometChatConversations",
+      "kind": "component",
+      "min_capabilities": ["conversation-list", "last-message-preview", "unread-count", "delete-conversation", "search", "presence", "receipts", "infinite-scroll", "realtime-updates"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/conversations",
+      "notes": "Ships all of these by default; surface (don't hand-build). Toggles: hideUnreadCount / hideUserStatus / hideReceipts (FETCH exact props)."
+    },
+    {
+      "for": "CometChatGroupMembers",
+      "kind": "component",
+      "min_capabilities": ["view-members", "kick-member", "ban-member", "view-banned-members", "change-scope", "search-members"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/group-members",
+      "notes": "Role-based: destructive actions surface for admin/owner. add-member + banned-members are related flows (ui events member-added / member-banned). A group DETAILS screen must include all of these."
+    },
+    {
+      "for": "CometChatMessageList",
+      "kind": "component",
+      "min_capabilities": ["render-messages", "message-bubbles-by-type", "delivery-read-receipts", "reactions-when-enabled", "thread-open", "realtime-updates"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/message-list",
+      "notes": "Reactions/threads render when the feature is enabled (features.json). VERIFY exact prop toggles from docs."
+    },
+    {
+      "for": "CometChatMessageComposer",
+      "kind": "component",
+      "min_capabilities": ["send-text", "attach-media-file", "emoji", "voice-recording"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/message-composer",
+      "notes": "voice-recording built in (hideVoiceRecordingButton default false). AI copilot actions auto-appear here when enabled. VERIFY exact prop names."
+    },
+    {
+      "for": "voice-video-calls",
+      "kind": "feature",
+      "min_capabilities": ["initiate-call", "incoming-call-ui", "outgoing-call-ui", "call-logs"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/call-features",
+      "notes": "Maps to CometChatCallButtons + CometChatIncomingCall + CometChatOutgoingCall + CometChatCallLogs. Needs @cometchat/calls-sdk-javascript@5 (see features.json)."
+    },
+    {
+      "for": "sdk-chat-surface",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": ["init-before-anything", "init-then-login-ordering", "prod-auth-token-guidance", "send-message", "receive-via-listener", "listener-register-with-id", "listener-remove-on-teardown", "sdk-error-handling", "pagination-via-request-builder", "production-ready-design-system", "sized-shell-no-overflow", "conversations-users-groups-lists", "list-search", "delete-conversation", "message-actions-working", "thread-panel", "user-group-detail-with-actions", "optimistic-ui-mutations", "loading-empty-error-states"],
+      "docs_topic": "https://www.cometchat.com/docs/sdk/javascript/overview",
+      "notes": "HEADLESS (build-your-own-UI) FLOOR for a Chat SDK skill — the SDK analogue of core-chat-surface, gating any SDK-type skill (there is no SDK skill in THIS react-v7 UI-Kit pack yet; this entry is the production-ready minimum an SDK skill inherits from the factory template, matched to the JS SDK catalog sdk-jsv4 landed in AUDIT-021). Capabilities are SDK behaviours the emitted code MUST include, mapped to the JS SDK (FETCH exact signatures from docs — bake the map, fetch the manual): init-before-anything = init resolves BEFORE any other SDK call — use CometChat.initFromSettings(settings) (persists integrationSource='ai-agent' for telemetry attribution, AUDIT-084), NOT the classic CometChat.init(appId, appSettings). init-then-login-ordering = CometChat.login(uid, authToken|authKey) runs AFTER init and BEFORE send/fetch/listeners. prod-auth-token-guidance = loginWithAuthToken / server-side token exchange; Auth Key dev-only. send-message = build a CometChat.TextMessage and CometChat.sendMessage(...), awaited. receive-via-listener = a registered listener DELIVERS incoming messages (onTextMessageReceived/onMediaMessageReceived), not polling. listener-register-with-id = CometChat.addMessageListener(UNIQUE_ID, new CometChat.MessageListener({...})). listener-remove-on-teardown = CometChat.removeMessageListener(UNIQUE_ID) on teardown — register AND remove; a leaked listener FAILS this contract. sdk-error-handling = every awaited SDK call handles the CometChatException path. pagination-via-request-builder = new CometChat.MessagesRequestBuilder().setLimit(n).build() + fetchNext(), not one unbounded call. Least-code = use the SDK's own builders/listeners (HOW), never drop the teardown or error path (WHAT). BECAUSE THE SDK HAS NO UI, the emitted app must ALSO be production-ready UI, deterministically (spec: the SDK skill's references/app-surface.md; AUDIT-024): production-ready-design-system = REUSE the app's existing design system (Tailwind/MUI/Chakra/shadcn/CSS-var theme/tokens) or, if fresh, ESTABLISH a small token-based one (theme.css palette/spacing/radii + reusable primitives) — NEVER ad-hoc inline styles / one-off hex. sized-shell-no-overflow = 100dvh 3-region shell, message list scrolls internally, min-width:0 (no page horizontal scrollbar), scaffold boilerplate reset. conversations-users-groups-lists + list-search = all three lists, EACH searchable (setSearchKeyword + client filter). delete-conversation = deleteConversation action per row. message-actions-working = Reply-in-thread/React/Edit/Delete each wired to the SDK AND reflected in the UI (own-message gating for edit/delete). thread-panel = setParentMessageId thread view + composer. user-group-detail-with-actions = user detail (block/unblock) + group detail (add/kick/ban member, change scope, leave), scope-gated. optimistic-ui-mutations = send/edit/delete/react update the UI IMMEDIATELY (temp/sending state) then reconcile with the SDK Promise (confirm on resolve, roll back + surface CometChatException.message on reject) — never wait for the round-trip. loading-empty-error-states = skeleton/empty/error on every surface, never blank or [object Object]. This is the full default for a GENERIC 'build chat with the SDK' prompt; a UI that renders only bare bubbles UNDER-DELIVERS. All symbols named here (User/Group/TextMessage/MessagesRequestBuilder/UsersRequestBuilder/MessageListener/init/login/sendMessage/addMessageListener/removeMessageListener) are in the JS-SDK namespace API surface the AUDIT-021 --members extractor recovers (5→396); regenerate the sdk-jsv4 catalog with build-catalog.mjs --exports-only --members before authoring the SDK skill this contract gates."
+    },
+    {
+      "for": "onboarding-plan",
+      "kind": "plan",
+      "consumption": "plan",
+      "min_capabilities": ["discovery-summary", "intent-capability-map", "numbered-actions", "files-that-change", "packages", "credential-auth-strategy", "modify-or-approve-gate"],
+      "docs_topic": "https://www.cometchat.com/docs/ui-kit/react/overview",
+      "notes": "JOURNEY FLOOR for the framework-agnostic onboarding front door (cometchat-onboarding, type `onboarding`) — the DISCOVER->UNDERSTAND->PLAN skill the entry router gates on FIRST (peers.yaml gate:). It emits NO CometChat symbols, so it has NO symbol catalog and no per-component contract; its completeness oracle is THIS plan-level contract (kind:plan, consumption:plan) — the analogue of core-chat-surface for a plan instead of a UI. min_capabilities are the SECTIONS the plan artifact MUST contain (skills/cometchat-onboarding/references/plan-artifact.md): discovery-summary = every beat-1 signal, each a value or explicit null (framework/bundler/language/pkg-mgr/auth/styling/state/routing/ssr/existing-cometchat/version_conflict/env). intent-capability-map = the confirmed archetype+modality+scope translated to CometChat capabilities (from the baked archetype map in references/archetypes.md). numbered-actions = the scoped build steps in order. files-that-change = the concrete additive paths (APPEND, never replace). packages = exact package(s) with major pins (the core owns exact coordinates). credential-auth-strategy = dev Auth-Key vs prod server-minted token, CHOSEN from discovery. modify-or-approve-gate = an explicit edit-or-approve invitation; nothing is written before approval. TWO behavioural must-dos accompany the sections (CHECKLIST row 25): every beat-2 intent question carries a repo-inferred recommended default (no blank asks); and the boundary is at PLAN (onboarding does discover+understand+plan, then hands a SCOPED build directive to the framework core, e.g. cometchat-react-v7-core — it must NOT fork the core's detect/credential flow). Least-code is n/a (no emitted code). Platform-agnostic: every family reuses the ONE onboarding skill, so this contract is inherited from templates/contracts.example.json. A non-React framework with no core yet still gets the full plan + an honest 'core not built yet' posture; do NOT hand off to a nonexistent core."
+    }
+  ]
+}

package/contracts.rn-calls-v5.json

@@ -0,0 +1,77 @@
+{
+  "generatedFrom": "@cometchat/calls-sdk-react-native@5.0.5 (bundled dist/index.d.ts) + /calls/react-native docs (v5, via docs MCP)",
+  "family": "rn-calls-v5",
+  "major": "v5",
+  "capabilityDetectors": {},
+  "contracts": [
+    {
+      "for": "calls-session-surface",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "init-before-anything",
+        "init-result-checked",
+        "init-then-login-ordering",
+        "prod-auth-token-guidance",
+        "generate-token-before-render",
+        "render-component-not-joinsession",
+        "component-in-flex-sized-view",
+        "listener-registered-before-render",
+        "listener-unsub-on-teardown",
+        "leave-session-on-teardown",
+        "single-active-session",
+        "no-redundant-call-controls",
+        "native-permissions-declared",
+        "sdk-error-handling"
+      ],
+      "docs_topic": "/calls/react-native/join-session",
+      "notes": "HEADLESS meet-style FLOOR for the RN Calls SDK v5 skill (cometchat-react-native-v5-sdk). This is the NATIVE FORK of web's calls-session-surface: the wiring concept is identical, the join step is NOT. init-before-anything = init via the ai-agent/telemetry-attributed CometChatCalls.initFromSettings(settings) (persists integrationSource='ai-agent'; RULES \u00a75 / AUDIT-084/175), settings passed INLINE (CometChatSettings shape baked in references/docs-map.md; intentionally undocumented/@nodoc, DOCS-BACKLOG F4/C1). The documented CometChatCalls.init({appId, region}) is FALLBACK ONLY. init-result-checked = BOTH init entry points resolve to a Result object ({success:false,error:{...}} | {success:true,error:null}), NOT a rejecting promise \u2014 a bare `await init(...)` that ignores `.success` silently continues on a validation failure and FAILS this contract. init-then-login-ordering = CometChatCalls.login(uid, authKey) | loginWithAuthToken(token) runs AFTER init and BEFORE generateToken/render/listeners. In v5 the Calls SDK authenticates ITSELF \u2014 do NOT hand generateToken a Chat-SDK auth token (that is the v4 pattern; generateToken's authToken param is optional and unnecessary after login). prod-auth-token-guidance = loginWithAuthToken / server-minted token; Auth Key dev-only. generate-token-before-render = const {token} = await CometChatCalls.generateToken(sessionId) resolves BEFORE the component mounts; render null/a loader until then. render-component-not-joinsession = THE NATIVE FORK: React Native has NO joinSession() and NO DOM container. You join by RENDERING <CometChatCalls.Component callToken={token} sessionSettings={settings} />. An emit that calls joinSession(...) or startSession(...) FAILS \u2014 startSession is the deprecated v4 path and joinSession does not exist on this platform at all. component-in-flex-sized-view = the Component is wrapped in a View with real dimensions (style={{flex:1}} or explicit height); a zero-height parent renders the call invisibly \u2014 the RN analogue of web's sized containerEl. listener-registered-before-render = CometChatCalls.addEventListener(eventName, cb, { signal }) registered BEFORE the component mounts. listener-unsub-on-teardown = every listener is removed on unmount \u2014 either by calling the unsubscribe function addEventListener returns, or via an AbortController whose signal was passed and whose abort() runs in the effect cleanup. A leaked listener FAILS. leave-session-on-teardown = CometChatCalls.leaveSession() on unmount (no session id \u2014 see single-active-session). single-active-session = CometChatCalls is a SINGLETON holding ONE active session: exactly one Component is mounted at a time, and switching sessions means leaveSession() -> await the onSessionLeft event -> generateToken(next) -> re-render. Every action method (leaveSession/muteAudio/setLayout/...) takes NO session id because it always targets the active session. no-redundant-call-controls = the Component ALREADY renders mute / video / switch-camera / leave / layout / recording controls. Do NOT add external buttons around it (AUDIT-170). The action methods are for CUSTOM controls only, and then the built-ins must first be hidden via the sessionSettings hide* flags. native-permissions-declared = iOS NSCameraUsageDescription + NSMicrophoneUsageDescription in Info.plist (+ pod install), Android CAMERA + RECORD_AUDIO + Bluetooth permissions in AndroidManifest.xml. Unlike web there is no getUserMedia prompt to fall back on \u2014 a missing native permission fails the call with no UI signal. sdk-error-handling = generateToken rejects with errorCode/errorDescription (ERROR_SESSION_ID_MISSING / ERROR_AUTH_TOKEN_MISSING / ERROR_SDK_NOT_INITIALIZED) and every await handles it. Least-code = use the SDK's own component + methods (HOW); never drop teardown, permissions, or the error path (WHAT). Meet-style needs ONLY the Calls SDK \u2014 no Chat SDK. Every CometChatCalls.* symbol named here is in the rn-calls-v5 catalog."
+    },
+    {
+      "for": "calls-oneonone-ringing",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "chat-sdk-init-login",
+        "initiate-call-signaling",
+        "incoming-call-listener-with-id",
+        "accept-or-reject-call",
+        "generate-token-from-accepted-session",
+        "render-component-after-accept",
+        "call-listener-remove-on-teardown",
+        "sdk-error-handling",
+        "voip-included-by-default"
+      ],
+      "docs_topic": "/calls/react-native/ringing",
+      "notes": "1:1 RINGING FLOOR \u2014 adds the Chat SDK signaling layer on top of calls-session-surface. Ringing = a specific user is called, gets an incoming prompt, accepts or rejects. The Chat SDK (@cometchat/chat-sdk-react-native@4) does the SIGNALING; the Calls SDK carries the MEDIA. Chat-SDK signatures are FETCHED via references/docs-map.md \u00a7 '1:1 RINGING' \u2014 never baked, and never sourced from search('default calling') (that surfaces the stale /sdk/<p>/3.0/ tree with the deprecated startSession flow and no incoming-call UI). chat-sdk-init-login = the Chat SDK is init'd and logged in alongside the Calls SDK login. initiate-call-signaling = CometChat.initiateCall(...) starts the ring. incoming-call-listener-with-id = CometChat.addCallListener(UNIQUE_ID, new CometChat.CallListener({ onIncomingCallReceived, onOutgoingCallAccepted, onOutgoingCallRejected, onIncomingCallCancelled })) \u2014 the id is required so the listener can be removed. accept-or-reject-call = CometChat.acceptCall(sessionId) / CometChat.rejectCall(sessionId, status). generate-token-from-accepted-session = CometChatCalls.generateToken(acceptedCall.getSessionId()) \u2014 the session id comes FROM the accepted call, never invented. render-component-after-accept = the media half then follows calls-session-surface exactly: render <CometChatCalls.Component> once the token resolves (NOT joinSession). call-listener-remove-on-teardown = CometChat.removeCallListener(UNIQUE_ID) on teardown, IN ADDITION TO the Calls-SDK listener teardown the inherited floor requires \u2014 two SDKs, two teardowns, and missing either one FAILS. sdk-error-handling = every awaited call handles the CometChatException path. This contract INHERITS the calls-session-surface floor for the media half (component sizing, listener teardown, leaveSession, permissions, no-redundant-controls). voip-included-by-default = RINGING SHIPS WITH VoIP. Signaling alone rings the callee only while their app is open, so an emit that stops there delivers half a feature and fails the first real device test. Whenever ringing is chosen the emit MUST ALSO produce the background half per the calls-ringing-voip contract \u2014 native VoIP setup (iOS PushKit+CallKit, Android FCM + ConnectionService), typed token registration, and a plain statement of the steps only the user can do (Apple VoIP certificate, Firebase server key, Xcode capabilities). Do NOT offer VoIP as an optional follow-up and do NOT ask whether it is wanted: 'ringing' means the phone rings. Meet-style is exempt \u2014 it has no ringing. Ringing cannot be verified with one client \u2014 it needs TWO logged-in users on separate devices/simulators; a single-client run proves the outgoing half only and must be reported as such. foreground-only-ringing-stated = the emit MUST state, in code comments or the README it writes, that this rings the callee ONLY while their app is in the foreground: onIncomingCallReceived arrives over the Chat SDK websocket, so a backgrounded or killed app receives nothing and the caller's call simply times out (default 45s). Ringing a CLOSED app is a SEPARATE native build \u2014 VoIP push with iOS CallKit/PushKit and Android FCM + ConnectionService/CallKeep, registered via CometChat.registerTokenForPushNotification \u2014 covered by /calls/react-native/voip-calling and out of scope for this contract. Silently shipping foreground-only ringing as if it were complete is the single most common way this feature disappoints in device testing, so the limitation is a REQUIRED capability, not a nicety."
+    },
+    {
+      "for": "calls-ringing-voip",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "voip-capabilities-and-credentials",
+        "native-incoming-call-surface",
+        "typed-token-registration-after-login",
+        "answer-rejoins-normal-flow",
+        "device-verification-stated",
+        "platform-correct-token-source"
+      ],
+      "docs_topic": "/calls/react-native/voip-calling",
+      "notes": "BACKGROUND-RINGING FLOOR. voip-capabilities-and-credentials = iOS Push Notifications + Background Modes/Voice over IP + a VoIP .p12 uploaded to Dashboard -> Notifications; Android Firebase + server key. Credentials are dashboard work the emit CANNOT do \u2014 it must say so rather than imply code alone suffices. native-incoming-call-surface = iOS PushKit + CallKit (and reportNewIncomingCall MUST be called on every VoIP push or iOS terminates the app), Android a self-managed ConnectionService with MANAGE_OWN_CALLS + READ_PHONE_STATE + BIND_TELECOM_CONNECTION_SERVICE. typed-token-registration-after-login = use the TYPED CometChatNotifications.registerPushToken(token, PushPlatforms.APNS_REACT_NATIVE_VOIP on iOS | FCM_REACT_NATIVE_ANDROID on Android), NOT the legacy CometChat.registerTokenForPushNotification(token, { voip: true }) that /calls/react-native/voip-calling still shows (DOCS-BACKLOG C16). iOS VoIP is a DISTINCT platform from ordinary iOS push, so an app that both rings and notifies registers two tokens. It runs AFTER login, re-runs on token refresh, and CometChatNotifications.unregisterPushToken() runs on logout \u2014 otherwise the next user on the device inherits the previous user's calls. This also keeps the calls skill consistent with the pack's own cometchat-react-native-push skill, which already uses CometChatNotifications. answer-rejoins-normal-flow = the OS answer action leads to CometChat.acceptCall(sessionId) -> CometChatCalls.generateToken(sessionId) -> render <CometChatCalls.Component>; it does NOT fork into a second call path. device-verification-stated = the emit states this cannot be verified on a simulator or in CI and needs two real devices \u2014 an unqualified 'ringing works' claim FAILS. Recipe: references/ringing-voip.md Part 1. platform-correct-token-source = the two platforms obtain the device token from DIFFERENT places and the emit must not conflate them. iOS: PushKit hands it to the native module, which posts VoIPTokenReceived \u2014 the JS MUST subscribe to that event, or the Swift side emits into nothing and no token is ever registered. Android: the token comes from the messaging library (messaging().getToken() / onTokenRefresh via @react-native-firebase/messaging), NOT from an event. CallKitManager is iOS-ONLY and emits EXACTLY VoIPTokenReceived, CallKitAnswerCall and CallKitEndCall; subscribing to any other name (e.g. an invented FcmTokenReceived) throws at runtime \u2014 'X is not a supported event type for CallKitManager' \u2014 which is a redbox on a real device that no compile or mock gate can catch. Both paths converge on the same registerPushToken call with their own PushPlatforms value."
+    },
+    {
+      "for": "call-background-handling",
+      "kind": "feature",
+      "consumption": "sdk",
+      "min_capabilities": [
+        "ios-background-audio-mode",
+        "android-foreground-service-permissions",
+        "appstate-pip-transitions",
+        "connection-events-handled"
+      ],
+      "docs_topic": "/calls/react-native/background-handling",
+      "notes": "ACTIVE-CALL-IN-BACKGROUND FLOOR. ios-background-audio-mode = Background Modes -> Audio, AirPlay and Picture in Picture; the emit states that video PAUSES while backgrounded on iOS and only audio continues. android-foreground-service-permissions = FOREGROUND_SERVICE + _MICROPHONE + _CAMERA + _MEDIA_PLAYBACK + _MEDIA_PROJECTION + WAKE_LOCK + POST_NOTIFICATIONS in AndroidManifest.xml. Without these an Android 10+ call DIES on backgrounding, which is the most common omission because it looks fine in foreground testing. The emit must NOT declare its own call service \u2014 the SDK ships and auto-merges CometChatOngoingCallService, and must NOT add its own wake locks. appstate-pip-transitions = an AppState listener drives enablePictureInPictureLayout on background and disable on foreground, and is removed on teardown. connection-events-handled = onConnectionLost / onConnectionRestored / onConnectionClosed are subscribed (reconnect UI + end-of-call), torn down with the rest. Recipe: references/ringing-voip.md Part 2."
+    }
+  ]
+}