@cometchat/skills 4.2.1 → 4.3.0

package/skills/cometchat-flutter-v6-core/SKILL.md

@@ -302,4 +302,181 @@ Every component follows this structure:
 - [ ] Theme cached in `didChangeDependencies()`, not `build()`
 - [ ] SDK listeners registered with unique ID, removed in `dispose()`
 - [ ] Colors from `CometChatThemeHelper`, never hardcoded
-- [ ] Strings from `Translations.of(context)`, never hardcoded
+
+## Visual Builder integration
+
+> **⚠ The Visual Builder emits V5-shaped code.** The canonical builder repo at the `chat_builder/` directory inside the Flutter Visual Builder ZIP (download from https://preview.cometchat.com/downloads/cometchat-builder-flutter.zip) uses `cometchat_chat_uikit: ^5.2.12` + `cometchat_calls_uikit: ^5.0.13` — the **V5** Flutter UI Kit packages. There is no V6-native Visual Builder canonical from vendor side yet ([F22 finding, 2026-05-22](https://github.com/cometchat/cometchat-skills/issues)). When a V6 project picks the Visually path, the copied `chat_builder/` path-dep brings V5 deps in transitively — your V6 host app code is untouched, but the Visual-Builder-emitted screens are V5-flavored. Treat as transitional until vendor publishes a V6 canonical. V6 customers preferring a single-version dep tree should use the In-code path.
+>
+> The recipe below is identical to what `cometchat-flutter-v5-core` §"Visual Builder integration" prescribes (both reference the same canonical). This page kept for V6 customers who still hit the Visually flow.
+
+When the dispatcher's Step 3.1 sets `customize=visual` and the platform resolves to `flutter`, skills runs **`cometchat builder export --platform flutter`** — a single CLI command that downloads the canonical static template ZIP from `preview.cometchat.com/downloads/cometchat-builder-flutter.zip`, fetches the per-builder settings JSON, applies F3 + F10 missing-field defaults, and writes the entire `chat_builder/` package to `--output` (default: `chat_builder/`).
+
+The `chat_builder/` directory is wired **as a path dependency** in the customer's project — it owns the entire chat surface (conversations, messages, users, groups, calls). The customer's app initializes settings and launches a screen via `ChatBuilder.launchBuilder(context)` or `ChatBuilder.launchMessages(...)`.
+
+This is intentionally a heavier copy than iOS (Pod) / Android (Gradle plugin) — the Flutter builder package is not yet published to pub.dev.
+
+### 1. Run `cometchat builder export`
+
+```bash
+cometchat builder export --platform flutter --json
+```
+
+Defaults to `--output chat_builder/`. The command writes the entire canonical `chat_builder/` Dart package (~50 files: `lib/`, `assets/`, `android/`, `ios/`, `pubspec.yaml`) — verbatim from the canonical ZIP — and patches `chat_builder/assets/sample_app/cometchat-builder-settings.json` with the **envelope-shape JSON** `{ builderId, name, settings: {...} }` (F3 + F10 defaults injected: `mentionAll: true`, `inAppSounds: { incomingMessageSound: true, outgoingMessageSound: true }`). No SKILLS-AUTO-GENERATED sentinel (JSON forbids `//` comments).
+
+`BuilderSettingsHelper.loadFromAsset()` reads this exported settings file at runtime.
+
+Resync = re-run the same command with `--force` (full re-download + replace). See `cometchat-core` §11.6 for the resync contract.
+
+#### F56 + F57 + F58 — known canonical-ZIP rough edges (re-apply after every export)
+
+Three issues live in the upstream canonical `chat_builder/` Dart package (verified 2026-05-25 against `preview.cometchat.com/downloads/cometchat-builder-flutter.zip`). Vendor-side fixes pending; agent must work around them on **every** `builder export` (first emit AND every resync, since `--force` re-overwrites the patches):
+
+**F56 — Wrong asset path in `api_services.dart`**
+
+`chat_builder/lib/services/api_services.dart` line ~41:
+
+```dart
+// Canonical (broken):
+await loadJsonFromAssets('assets/chat_builder/sample_data.json');
+
+// Agent must patch to:
+await loadJsonFromAssets('assets/sample_app/sample_data.json');
+```
+
+The canonical references `assets/chat_builder/sample_data.json` — a path that doesn't exist in the customer's host app after the standard `cp -r chat_builder/assets/ assets/` copy. The actual file lands at `assets/sample_app/sample_data.json`. Without this patch, the login screen's "default users" list silently falls back to empty and customers see an empty user picker.
+
+**F57 — F56 patch is overwritten on every resync**
+
+`builder export --platform flutter --force` re-copies the canonical's `api_services.dart` verbatim — re-introducing the wrong path. Agent must re-apply the F56 patch after every resync. This is a known re-apply task; document it in the customer-facing summary so they know "the agent will need to patch this each time the dashboard settings change".
+
+**F58 — Asset copy is additive, not idempotent**
+
+The standard prescription `cp -r chat_builder/assets/ assets/` is additive — files removed from the canonical (e.g., a deprecated icon) stay in the customer's `assets/` directory because cp doesn't delete. On resync, use `rsync -a --delete chat_builder/assets/ assets/` instead, OR `rm -rf assets/ && cp -r chat_builder/assets/ assets/` first.
+
+**Tracking**: a single vendor ticket bundles F22 (V5-shaped canonical), F56 (wrong asset path), F57 (resync overwrite of F56 fix), F48 lineage (font paths in earlier Android-ZIP iterations) — see CometChat Linear for the consolidated upstream-fix request. v4.3.0 ships with the agent-side workarounds documented above; a future release picks up the upstream fixes when they land.
+
+### Files skills writes (after `builder export`)
+
+| Path | Content |
+|---|---|
+| `lib/cometchat/cometchat_app.dart` | Thin `StatefulWidget` that initializes the kit then exposes a launch trigger calling `ChatBuilder.launchBuilder(context)` |
+| `lib/cometchat/secrets.dart` | Credentials class (`Secrets.appId / region / authKey`) populated by Step 2c, added to `.gitignore` |
+
+### Files patched
+
+| Path | Patch |
+|---|---|
+| `pubspec.yaml` | Add `chat_builder: { path: ./chat_builder }` to dependencies. Add `assets/` + `assets/sample_app/` to `flutter.assets`. Add font families `arial / inter / roboto / times New Roman` exactly as defined in `chat_builder/pubspec.yaml` |
+| `lib/main.dart` | Insert `WidgetsFlutterBinding.ensureInitialized()` + `await BuilderSettingsHelper.loadFromAsset()` before `runApp()` |
+| `ios/Podfile` | `platform :ios, '13.0'` (raise if lower) |
+| `android/app/build.gradle.kts` | `ndkVersion = "27.0.12077973"`, `minSdk = 24` (raise if lower) |
+| `android/gradle.properties` | **Non-negotiable:** append `android.enableJetifier=true`. CometChat Chat SDK transitively pulls `com.android.support:support-compat:26.1.0` which collides with `androidx.core:core` — without Jetifier the build fails with `Duplicate class android.support.v4.os.ResultReceiver` etc. Same root cause as `cometchat-android-v6-core` §1.3a — Flutter's Android side has identical exposure. Validated 2026-05-19 on smoke test |
+| `android/app/src/main/AndroidManifest.xml` + `ios/Runner/Info.plist` | `RECORD_AUDIO` / `CAMERA` permissions + `NSMicrophoneUsageDescription` / `NSCameraUsageDescription` if any call feature is enabled |
+
+### Init flow (lib/main.dart)
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:chat_builder/builder/builder_settings_helper.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await BuilderSettingsHelper.loadFromAsset();
+  runApp(const MyApp());
+}
+```
+
+`BuilderSettingsHelper.loadFromAsset()` reads `chat_builder/assets/cometchat-builder-settings.json` and populates the in-memory settings the `ChatBuilder.*` screens consume. Standard `CometChatUIKit.init(uiKitSettings: ...)` (see this file's `INIT_FIRST` rule) is still required and runs before any chat surface mounts — the wrapper below handles that.
+
+### The wrapper template
+
+```dart
+// lib/cometchat/cometchat_app.dart
+import 'package:flutter/material.dart';
+import 'package:chat_builder/builder/chat_builder.dart';
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+import 'secrets.dart';
+
+/// Top-level chat surface emitted by the Visual Builder Visually path.
+/// The `chat_builder` package owns the UI; this widget bootstraps UI Kit init
+/// then renders a launch trigger. Step 3c placement decides where this widget
+/// mounts in the host app (a route, a tab, a dialog).
+class CometChatApp extends StatefulWidget {
+  const CometChatApp({super.key});
+
+  @override
+  State<CometChatApp> createState() => _CometChatAppState();
+}
+
+class _CometChatAppState extends State<CometChatApp> {
+  bool _isReady = false;
+  String? _initError;
+
+  @override
+  void initState() {
+    super.initState();
+    _bootstrap();
+  }
+
+  void _bootstrap() {
+    final settings = (UIKitSettingsBuilder()
+          ..appId = Secrets.appId
+          ..region = Secrets.region
+          ..authKey = Secrets.authKey
+          ..subscriptionType = CometChatSubscriptionType.allUsers)
+        .build();
+
+    CometChatUIKit.init(
+      uiKitSettings: settings,
+      onSuccess: (_) => setState(() => _isReady = true),
+      onError: (e) => setState(() => _initError = e.message),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (_initError != null) {
+      return Scaffold(body: Center(child: Text('CometChat init failed: $_initError')));
+    }
+    if (!_isReady) {
+      return const Scaffold(body: Center(child: CircularProgressIndicator()));
+    }
+    return Scaffold(
+      resizeToAvoidBottomInset: false,
+      body: Center(
+        child: ElevatedButton(
+          onPressed: () => ChatBuilder.launchBuilder(context),
+          child: const Text('Open chat'),
+        ),
+      ),
+    );
+  }
+}
+```
+
+`ChatBuilder.launchBuilder(context)` opens the builder's login / dashboard flow; once a user is logged in, the package's internal navigation handles conversations → messages.
+
+For direct deep-links into a specific user or group thread (skipping the dashboard), use:
+
+```dart
+ChatBuilder.launchMessages(context: context, user: user);
+ChatBuilder.launchMessages(context: context, group: group);
+```
+
+These are the two public entry points the `chat_builder` package exposes — see `chat_builder/lib/builder/chat_builder.dart` (inside the Flutter Visual Builder ZIP at https://preview.cometchat.com/downloads/cometchat-builder-flutter.zip).
+
+`resizeToAvoidBottomInset: false` is non-negotiable on any `Scaffold` whose body chain reaches `CometChatMessageComposer` (see this file's `SCAFFOLD_NO_RESIZE` rule). The composer handles keyboard spacing internally.
+
+### Calls + builder
+
+If `CometChatBuilderSettings` reports any call feature enabled, the `chat_builder` package handles incoming/outgoing call surfaces internally (it ships its own call routes). External wiring still required:
+1. Add `cometchat_calls_uikit` to `pubspec.yaml`
+2. iOS `Info.plist` + Android `AndroidManifest.xml` permissions per `cometchat-flutter-v6-calls`
+3. Apply the `navigatorKey: CallNavigationContext.navigatorKey` workaround documented in `cometchat-flutter-v6-calls` §1.7 (kit 6.0.0-beta2 requires this for incoming-call routing)
+4. Push wiring — defer to `cometchat-flutter-v6-push` (audit-verified namespace `PNRegistry`, NOT `CometChatNotifications` — [[project_sdk_symbol_audit_2026_05_14]])
+5. **Vendor blocker:** outgoing→in-call transition is broken on `cometchat_chat_uikit 6.0.0-beta2` ([[project_v6_flutter_calls_partial]]); Flutter V5 cohort is production-recommended until vendor fix lands
+
+### What is NOT honored in v1
+
+Skills emits a launch-button trigger, not the full multi-tab layout the `chat_builder` package's internal `Dashboard` provides. Customers get the dashboard once they tap "Open chat" — but the host-app surface is intentionally minimal so Step 3c placement (route, tab, dialog) can decide the mount shape. Theme color + typography + chat-feature toggles ARE honored via the embedded package. For deep customization beyond what the builder JSON allows, fall back to the code-driven path (see this file's standard placement pattern) and skip `chat_builder` entirely.

package/skills/cometchat-flutter-v6-push/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cometchat-flutter-v6-push
-description: Push notifications for CometChat Flutter UIKit v6 (beta, Bloc-based). Covers firebase_messaging setup for FCM (Android) + APNs (iOS via Firebase), CometChat dashboard PushPlatform configuration, token registration via the Notifications SDK, background isolate handler (Dart entry-point rule), foreground vs background message routing, notification tap deep-link to chat threads, and the Bloc patterns for surfacing push state. Sister skill of cometchat-flutter-v5-push — same FCM stack, Bloc-flavored client integration.
+description: Push notifications for CometChat Flutter UIKit v6 (stable, Bloc-based). Covers firebase_messaging setup for FCM (Android) + APNs (iOS via Firebase), CometChat dashboard PushPlatform configuration, token registration via the Notifications SDK, background isolate handler (Dart entry-point rule), foreground vs background message routing, notification tap deep-link to chat threads, and the Bloc patterns for surfacing push state. Sister skill of cometchat-flutter-v5-push — same FCM stack, Bloc-flavored client integration.
 license: "MIT"
 compatibility: "Flutter >= 2.5, Dart >= 3.0; cometchat_chat_uikit ^6.0.0-beta2; firebase_messaging ^14.0.0; firebase_core ^2.0.0; Android minSdk 26+; iOS 13+ deployment target"
 allowed-tools: "shell, file-read, file-search, file-list, ask-user"
@@ -56,7 +56,7 @@ Unlike Web Push (which requires you to run a push server), CometChat hosts the c
 dependencies:
   flutter:
     sdk: flutter
-  cometchat_chat_uikit: ^6.0.0-beta2
+  cometchat_chat_uikit: ^6.0
   firebase_messaging: ^14.0.0
   firebase_core: ^2.0.0
   flutter_local_notifications: ^16.0.0    # for foreground notifications + iOS in-app banner

package/skills/cometchat-flutter-v6-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cometchat-flutter-v6-testing
-description: Testing patterns for CometChat Flutter UIKit v6 (beta, Bloc-based). Covers flutter_test + bloc_test for Bloc unit tests, mocktail for SDK mocking, widget tests around the Bloc-driven CometChat widgets, integration_test for real-device flows, golden tests for theming, and CI on GitHub Actions / Codemagic. Sister skill of cometchat-flutter-v5-testing — the cohorts have different state-management primitives (GetX vs Bloc) so the patterns differ.
+description: Testing patterns for CometChat Flutter UIKit v6 (stable, Bloc-based). Covers flutter_test + bloc_test for Bloc unit tests, mocktail for SDK mocking, widget tests around the Bloc-driven CometChat widgets, integration_test for real-device flows, golden tests for theming, and CI on GitHub Actions / Codemagic. Sister skill of cometchat-flutter-v5-testing — the cohorts have different state-management primitives (GetX vs Bloc) so the patterns differ.
 license: "MIT"
 compatibility: "Flutter >= 2.5, Dart >= 3.0; flutter_test (built-in); bloc_test >= 9.0; mocktail >= 1.0; integration_test (built-in); cometchat_chat_uikit ^6.0.0-beta2"
 allowed-tools: "shell, file-read, file-search, file-list, ask-user"
@@ -12,7 +12,7 @@ metadata:
 
 ## Purpose
 
-Test recipes for Flutter UIKit v6 (beta, Bloc-based). Most of the v5 patterns carry over; the deltas are around state-management primitives (Bloc, not GetX) and the unified `cometchat_chat_uikit` package (calls bundled — see `cometchat-flutter-v6-calls`).
+Test recipes for Flutter UIKit v6 (stable, Bloc-based). Most of the v5 patterns carry over; the deltas are around state-management primitives (Bloc, not GetX) and the unified `cometchat_chat_uikit` package (calls bundled — see `cometchat-flutter-v6-calls`).
 
 **Read these other skills first:**
 - `cometchat-flutter-v6-core` — UIKitSettings, init/login order, hard rules

package/skills/cometchat-ios-core/SKILL.md

@@ -820,3 +820,145 @@ pod 'CometChatCallsSDK', '~> 4.0'
 ```
 
 The UI Kit automatically detects and enables calling features when the Calls SDK is present.
+
+## Visual Builder integration
+
+When the dispatcher's Step 3.1 sets `customize=visual` and the platform resolves to `ios`, skills runs **`cometchat builder export --platform ios`** — a single CLI command that downloads the canonical static template ZIP from `preview.cometchat.com/downloads/cometchat-builder-ios.zip`, fetches the per-builder settings JSON, applies F3 + F10 missing-field defaults, and writes 3 files to `--output` (default: `CometChat/`):
+
+- `MessagesVC.swift` — verbatim view controller composing header + list + composer
+- `ThreadedMessagesVC.swift` — verbatim helper VC (imported by MessagesVC)
+- `cometchat-builder-settings.json` — **envelope-shape JSON** `{ builderId, name, settings: {...} }` (no sentinel — JSON forbids `//` comments)
+
+### 1. Run `cometchat builder export`
+
+```bash
+cometchat builder export --platform ios --json
+```
+
+Defaults to `--output CometChat/`. Adjust the output if the customer's project uses a different chat-surface group name (e.g. `--output Chat/` for projects that use a `Chat` group).
+
+`CometChatBuilderSettings.loadFromJSON()` looks for the envelope shape — handing it the raw settings blob causes `CometChatBuilderSettings.shared` to fall back to defaults silently (no error logged). The CLI always writes the envelope, so this trap is closed.
+
+Resync = re-run the same command with `--force`. See `cometchat-core` §11.6 for the resync contract.
+
+### 2. Files skills writes (after `builder export`)
+
+| Path | Content |
+|---|---|
+| `CometChat/CometChatApp.swift` | SwiftUI wrapper that mounts `CometChatConversations` + pushes `MessagesVC` on tap. Feature flags read from `CometChatBuilderSettings.shared`. Skills emits this — not from the ZIP. |
+
+### Files patched
+
+| Path | Patch |
+|---|---|
+| `Podfile` | Add `pod 'CometChatBuilder'` (the canonical pod surfacing `CometChatBuilderSettings.shared` + `loadFromJSON()`). Add `pod 'CometChatUIKitSwift', '~> 5.1'` if not already declared. SPM equivalent: add `https://github.com/cometchat/cometchat-builder-ios` |
+| `AppDelegate.swift` (UIKit) / `App.swift` (SwiftUI) | Add `CometChatBuilderSettings.loadFromJSON()` + theme application + `CometChatUIKit.init(uiKitSettings:)` in `application(_:didFinishLaunchingWithOptions:)` — see init code below |
+| App target | Toggle `cometchat-builder-settings.json` for **target membership** in Xcode (else `loadFromJSON()` silently returns defaults) |
+| Entry view — `ContentView.swift` (SwiftUI) or root `UIViewController` (UIKit) | Mount `CometChatApp()` per Step 3c placement (modal sheet, push-navigation destination, tab item, or embedded view) |
+| `Info.plist` | `NSMicrophoneUsageDescription` + `NSCameraUsageDescription` if `CometChatBuilderSettings.shared.callFeatures` has any enabled feature |
+
+### Init code — AppDelegate
+
+```swift
+// AppDelegate.swift — inside application(_:didFinishLaunchingWithOptions:)
+import CometChatBuilder
+import CometChatUIKitSwift
+
+// 1. Load builder settings from bundled JSON
+CometChatBuilderSettings.loadFromJSON()
+
+// 2. Apply builder theme tokens to the kit's global theme
+CometChatTheme.primaryColor = UIColor.dynamicColor(
+    lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor),
+    darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor)
+)
+CometChatTheme.textColorPrimary = UIColor.dynamicColor(
+    lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextLight),
+    darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextDark)
+)
+CometChatTheme.textColorSecondary = UIColor.dynamicColor(
+    lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextLight),
+    darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextDark)
+)
+CometChatTypography.customFontFamilyName = CometChatBuilderSettings.shared.style.typography.font
+
+// 3. Standard UI Kit init (this file's §2 — credentials from Secrets.swift)
+CometChatManager.shared.initialize(
+    appID: Secrets.appID, authKey: Secrets.authKey, region: Secrets.region
+) { _, _ in }
+```
+
+`loadFromJSON()` reads `cometchat-builder-settings.json` from the main bundle. If the file isn't a target member (Xcode → file inspector → Target Membership), `CometChatBuilderSettings.shared` silently falls back to defaults — this is the #1 integration bug. Sanity-check by printing `CometChatBuilderSettings.shared.style.color.brandColor` after `loadFromJSON()`.
+
+### The wrapper template
+
+```swift
+// CometChat/CometChatApp.swift
+import SwiftUI
+import UIKit
+import CometChatBuilder
+import CometChatUIKitSwift
+import CometChatSDK
+
+/// Top-level chat surface emitted by the Visual Builder Visually path.
+/// Master/detail SwiftUI host: `CometChatConversations` at root, `MessagesVC` pushed on tap.
+/// Feature visibility flags are read from `CometChatBuilderSettings.shared`.
+public struct CometChatApp: View {
+    public init() {}
+    public var body: some View {
+        ConversationsContainer().ignoresSafeArea()
+    }
+}
+
+private struct ConversationsContainer: UIViewControllerRepresentable {
+    func makeUIViewController(context: Context) -> UINavigationController {
+        let conversationsVC = CometChatConversations()
+        let core = CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience
+        conversationsVC.hideUserStatus = !core.userAndFriendsPresence
+        conversationsVC.hideReceipts = !core.messageDeliveryAndReadReceipts
+
+        let nav = UINavigationController(rootViewController: conversationsVC)
+        conversationsVC.set(onItemClick: { [weak nav] conversation, _ in
+            let vc = MessagesVC()
+            if let user = conversation.conversationWith as? User { vc.user = user }
+            else if let group = conversation.conversationWith as? Group { vc.group = group }
+            nav?.pushViewController(vc, animated: true)
+        })
+        return nav
+    }
+    func updateUIViewController(_ uiViewController: UINavigationController, context: Context) {}
+}
+
+private extension UIColor {
+    convenience init?(hex: String) {
+        let s = hex.replacingOccurrences(of: "#", with: "")
+        guard s.count == 6, let rgb = UInt32(s, radix: 16) else { return nil }
+        self.init(red: CGFloat((rgb >> 16) & 0xFF) / 255,
+                  green: CGFloat((rgb >> 8) & 0xFF) / 255,
+                  blue: CGFloat(rgb & 0xFF) / 255,
+                  alpha: 1)
+    }
+    static func dynamicColor(lightModeColor: UIColor?, darkModeColor: UIColor?) -> UIColor {
+        UIColor { traits in
+            (traits.userInterfaceStyle == .dark ? darkModeColor : lightModeColor) ?? UIColor.label
+        }
+    }
+}
+```
+
+`MessagesVC.swift` is **copied verbatim** from `CometChatBuilderSwift/BuilderApp/View Controllers/CometChat Components/MessagesVC.swift` (inside the Ios Visual Builder ZIP at https://preview.cometchat.com/downloads/cometchat-builder-ios.zip). It composes header + list + composer in a `UIViewController` and wires reaction / thread / typing per `CometChatBuilderSettings.shared.chatFeatures.*`. Do not hand-roll this — the canonical file is the reference.
+
+`Secrets.swift` is the credentials enum (`enum Secrets { static let appID = "..."; static let region = "..."; static let authKey = "..." }`) populated by Step 2c provision. Added to `.gitignore`.
+
+**SwiftUI vs UIKit hosts.** The template above is the SwiftUI host. For pure UIKit apps, skip `UIViewControllerRepresentable` and present `UINavigationController(rootViewController: CometChatConversations())` directly in `SceneDelegate` — see `CometChatBuilderSwift/BuilderApp/SceneDelegate.swift` (inside the Ios Visual Builder ZIP at https://preview.cometchat.com/downloads/cometchat-builder-ios.zip) + `View Controllers/HomeScreenViewController.swift` for the canonical UIKit pattern.
+
+### Calls + builder
+
+If `CometChatBuilderSettings.shared.callFeatures` has any enabled feature:
+1. Init Calls SDK at the same site as UI Kit (see `cometchat-ios-calls`)
+2. Mount `CometChatIncomingCall` at app root (SwiftUI App's `WindowGroup` root, or UIKit's `keyWindow.rootViewController` overlay — the builder repo's `BuilderApplication`-equivalent pattern in `SceneDelegate.swift` is the reference)
+3. PushKit + CallKit wiring — defer to `cometchat-ios-push`
+
+### What is NOT honored in v1
+
+The builder repo's `HomeScreenViewController` is a `UITabBarController` with up to 4 tabs (Chats / Calls / Users / Groups) driven by `CometChatBuilderSettings.shared.layout.tabs`. Skills' thin wrapper emits a single conversations surface, not the tabbed shape. Theme color + typography + chat-feature toggles ARE honored. To get the tabbed shape, copy `HomeScreenViewController.swift` from the builder repo instead of the wrapper template above.

package/skills/cometchat-native-bare-patterns/SKILL.md

@@ -85,9 +85,14 @@ npm install \
   @react-native-community/netinfo \
   react-native-background-timer \
   react-native-callstats \
-  react-native-webrtc
+  react-native-webrtc \
+  react-native-url-polyfill \
+  react-native-performance \
+  valibot
 ```
 
+> **`react-native-url-polyfill`, `react-native-performance`, and `valibot` are not in the calls-sdk `peerDependencies` array** — but the calls-sdk's `dist/polyfills/browser.js` imports them at module top, so Metro fails the bundle without them. Omitting any of the three yields `Unable to resolve module …` at startup with no app render. (Validated 2026-05-26 on `@cometchat/calls-sdk-react-native@5.0.0`.)
+
 WebRTC bloats the binary. Skip until the user actually wants calls.
 
 ---
@@ -256,6 +261,8 @@ allprojects {
 
 Without this fix, the whole Android build fails early. This is a UI Kit-specific gotcha because the kit pins async-storage v3+.
 
+> **Known issue (F78) — chat-sdk 4.0.22 breaks bare RN at runtime.** Separate from the build-time Maven error above: `@cometchat/chat-sdk-react-native@4.0.22` declares `react-native@0.64.2` + async-storage as **hard deps** (4.0.21 had none), so npm installs a nested duplicate react-native inside the SDK. The app builds fine but crashes at JS startup with `Cannot read property 'CometChatThemeProvider' of undefined` (AsyncStorage native module mismatch). **Expo is unaffected.** Fix: add npm `overrides` to dedupe, or pin `@cometchat/chat-sdk-react-native@4.0.21`. Full root cause + exact `overrides` block in `cometchat-native-troubleshooting` §3bc. Tracked in ENG-35653.
+
 ### 3c. Android: Metro config for custom fonts or assets (if applicable)
 
 If the project uses custom icon fonts or bundled assets, confirm `react-native.config.js` includes:
@@ -510,3 +517,17 @@ Use Expo + `npx expo prebuild` to generate native projects on demand. Stay on `c
 | `cometchat-native-customization` | Text formatters, events, custom views |
 | `cometchat-native-production` | Server-side auth tokens + user management |
 | `cometchat-native-troubleshooting` | pod install fails, build errors, missing modules, privacy manifest rejection |
+
+## Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the bare RN recipe diverges from the standard provider chain. Skills runs `cometchat builder export --platform react-native --json` to emit `src/config/{store.ts, config.json}` (the Zustand-backed config store + 7-field envelope JSON), then patches `App.tsx` with `useConfig` + theme derivation.
+
+**Full recipe lives in `cometchat-native-core` §"Visual Builder integration".** Bare RN-specific notes:
+
+- No `npx expo install` — install deps via `npm install` and pin manually. The 11 explicit peer-dep list applies in full (see §"Mandatory peer deps").
+- Env via `react-native-dotenv` Babel plugin — the standard bare-RN convention. Add `[['module:react-native-dotenv']]` to `babel.config.js` plugins. Import via `import { COMETCHAT_APP_ID, COMETCHAT_REGION, COMETCHAT_AUTH_KEY } from "@env"`. Add a `src/env.d.ts` type declaration so TS recognizes the `@env` module.
+- Required additional deps: `zustand`, `@react-native-async-storage/async-storage`, plus the standard 11 peers from §"Mandatory peer deps".
+- `useConfig(s => s.settings.style)` — note the selector takes `AppConfig` directly, NOT `s.config.settings.style` (Finding F6, 2026-05-21).
+- iOS host: run `cd ios && pod install` after the deps land. B6 smoke validated: Metro bundles 4.6 MB iOS bundle clean on RN 0.81.5 + React 19.1.0.
+
+If the customer picks **In code**, ignore this section — the standard four-wrapper chain + provider pattern applies.

package/skills/cometchat-native-calls/SKILL.md

@@ -133,9 +133,67 @@ Required:
 - Android — runtime requests via `PermissionsAndroid.requestMultiple` for `RECORD_AUDIO`, `CAMERA`, `POST_NOTIFICATIONS` (Android 13+)
 - Expo managed — declare in `app.json` `expo.ios.infoPlist` and `expo.android.permissions`; the prebuild merges into native manifests
 
-### 1.7 IncomingCall mounted at app root
+### 1.7 IncomingCall + OutgoingCall + OngoingCall — full event-listener wiring
 
-`<CometChatIncomingCall />` (additive mode) goes inside the root navigator OR in the App.tsx wrapper, ABOVE all stacks/tabs. Same rule as web — calls only ring on screens where the listener exists.
+`<CometChatIncomingCall />`, `<CometChatOutgoingCall />`, and `<CometChatOngoingCall />` are **NOT auto-mounted by each other**. The parent component must register both `CometChat.addCallListener` (SDK socket) and `CometChatUIEventHandler.addCallListener` (UI events fired by `<CometChatCallButtons>` / `<CometChatMessageHeader>`), then conditionally render whichever overlay matches current state. Validated 2026-05-26 on Pixel 3 + `@cometchat/chat-uikit-react-native@5.3.5`.
+
+Mount this wiring inside the root navigator OR in the App.tsx wrapper, ABOVE all stacks/tabs — calls only ring on screens where the listener exists.
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import {
+  CometChatIncomingCall,
+  CometChatOutgoingCall,
+  CometChatOngoingCall,
+  CometChatUIEventHandler,
+} from "@cometchat/chat-uikit-react-native";
+import { StyleSheet, View } from "react-native";
+
+const CALL_LISTENER_ID = "app-call-listener";
+
+function CallSurfaces() {
+  const [outgoingCall, setOutgoingCall] = useState<CometChat.Call | null>(null);
+  const [incomingCall, setIncomingCall] = useState<CometChat.Call | null>(null);
+  const [ongoingCall, setOngoingCall] = useState<CometChat.Call | null>(null);
+
+  useEffect(() => {
+    // SDK socket — incoming + outgoing-rejected
+    CometChat.addCallListener(
+      CALL_LISTENER_ID,
+      new CometChat.CallListener({
+        onIncomingCallReceived: (call: CometChat.Call) => setIncomingCall(call),
+        onIncomingCallCancelled: () => setIncomingCall(null),
+        onOutgoingCallAccepted: () => {},
+        onOutgoingCallRejected: () => setOutgoingCall(null),
+      })
+    );
+    // UI events fired by the kit's CallButtons / MessageHeader on tap
+    CometChatUIEventHandler.addCallListener(CALL_LISTENER_ID, {
+      ccOutgoingCall: ({ call }) => setOutgoingCall(call),
+      ccCallEnded: () => {
+        setOutgoingCall(null);
+        setIncomingCall(null);
+        setOngoingCall(null);
+      },
+      ccShowOngoingCall: ({ call }) => setOngoingCall(call),
+    });
+    return () => {
+      CometChat.removeCallListener(CALL_LISTENER_ID);
+      CometChatUIEventHandler.removeCallListener(CALL_LISTENER_ID);
+    };
+  }, []);
+
+  return (
+    <>
+      {incomingCall && <View style={StyleSheet.absoluteFill}><CometChatIncomingCall call={incomingCall} /></View>}
+      {outgoingCall && <View style={StyleSheet.absoluteFill}><CometChatOutgoingCall call={outgoingCall} /></View>}
+      {ongoingCall && <View style={StyleSheet.absoluteFill}><CometChatOngoingCall call={ongoingCall} /></View>}
+    </>
+  );
+}
+```
+
+> **Don't skip the `ccOutgoingCall` listener.** Without it, tapping the video/voice button in `<CometChatMessageHeader>` triggers the call at the SDK level (WebRTC, camera, audio init) but no overlay UI ever mounts — the user sees nothing change after the tap. This was [[project_v4_3_f75_rn_call_ui_missing]] — F75.
 
 In standalone mode, CallKit/ConnectionService own the foreground UI; `<CometChatIncomingCall />` is not used. Instead, a `react-native-callkeep` event listener at app root reports new calls to the OS.
 
@@ -376,9 +434,9 @@ Same names + shapes as the JavaScript SDK (Section 3 of `cometchat-react-calls`)
 | Component | Purpose |
 |---|---|
 | `<CometChatCallButtons user={u} group={g} />` | Voice + video icon row (typically inside `CometChatMessageHeader`). **Group + user semantics differ** — see callout below |
-| `<CometChatIncomingCall />` | Root-mounted listener |
-| `<CometChatOutgoingCall />` | Auto-mounted by IncomingCall on initiate |
-| `<CometChatOngoingCall />` | Active call view |
+| `<CometChatIncomingCall />` | Root-mounted; renders ringing UI for incoming call (controlled by parent state — see §1.7) |
+| `<CometChatOutgoingCall />` | Root-mounted; renders "Calling…" UI for outgoing call (controlled by parent state — see §1.7) |
+| `<CometChatOngoingCall />` | Root-mounted; renders active in-call view (controlled by parent state — see §1.7) |
 | `<CometChatCallLogs onItemClick={fn} />` | History |
 
 #### ⚠️ Group calls use message-based join, not the ringing channel (validated 2026-05-15)

package/skills/cometchat-native-components/SKILL.md

@@ -268,20 +268,22 @@ Voice + video call initiators. Drop into `AuxiliaryButtonView` on `CometChatMess
 
 ### CometChatIncomingCall
 
-Incoming call notification. Render at the app root so it's visible on any screen.
+Incoming call notification. **Parent-controlled — must be conditionally rendered when an incoming-call event fires on `CometChat.addCallListener`'s `onIncomingCallReceived`.** Render at the app root so it's visible on any screen.
+
+> **DO NOT pass `onAccept`** — it short-circuits the kit's internal `acceptCall` + transition to `<CometChatOngoingCall>`. The kit fires `ccShowOngoingCall` after acceptance; let the parent's `CometChatUIEventHandler.addCallListener` mount the ongoing surface. Only handle `onDecline` + `onError`. See `cometchat-native-calls` §1.8.c and full wiring in `cometchat-native-features` §3d.
 
 ```tsx
 <CometChatIncomingCall
   call={incomingCall}
-  onAccept={(call) => {}}
-  onDecline={(call) => {}}
+  onDecline={() => setIncomingCall(null)}
+  onError={() => setIncomingCall(null)}
   disableSoundForCalls={false}
 />
 ```
 
 ### CometChatOutgoingCall
 
-Ringing-while-calling screen after `CometChat.initiateCall(...)`.
+Ringing-while-calling screen. **Parent-controlled — NOT auto-mounted by `CometChatIncomingCall` or by tapping the call button.** To make the call button in `<CometChatMessageHeader>` actually mount this overlay, register `CometChatUIEventHandler.addCallListener` and listen for `ccOutgoingCall`. Full wiring template in `cometchat-native-features` §3d.
 
 ```tsx
 <CometChatOutgoingCall
@@ -292,7 +294,7 @@ Ringing-while-calling screen after `CometChat.initiateCall(...)`.
 
 ### CometChatOngoingCall
 
-In-call UI — tiles, controls, mute, end-call.
+In-call UI — tiles, controls, mute, end-call. **Parent-controlled — NOT auto-mounted.** Mount when `CometChatUIEventHandler.addCallListener`'s `ccShowOngoingCall` event fires (kit emits this after `acceptCall` succeeds OR when the caller's outgoing call is accepted by the peer). Full wiring in `cometchat-native-features` §3d.
 
 ```tsx
 <CometChatOngoingCall