omikit-plugin 4.0.2 → 4.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 The [omikit-plugin](https://www.npmjs.com/package/omikit-plugin) enables VoIP/SIP calling via the OMICALL platform with support for both Old and **New Architecture** (TurboModules + Fabric).
 
-**Status:** Active maintenance | **Version:** 4.0.1
+**Status:** Active maintenance | **Version:** 4.1.1
 
 ---
 
@@ -46,8 +46,37 @@ The [omikit-plugin](https://www.npmjs.com/package/omikit-plugin) enables VoIP/SI
 
 | Platform | SDK | Version |
 |----------|-----|---------|
-| Android | OMIKIT | 2.6.4 |
-| iOS | OmiKit | 1.10.34 |
+| Android | OMIKIT | 2.6.6 |
+| iOS | OmiKit | 1.11.4 |
+
+### Platform Requirements
+
+| | Android | iOS |
+|--|---------|-----|
+| **Min SDK** | API 24 (Android 7.0) | iOS 13.0 |
+| **Target SDK** | API 36 (Android 16) | — |
+| **Compile SDK** | API 36 | — |
+
+### Device Requirements
+
+| Requirement | Platform | Notes |
+|-------------|----------|-------|
+| **Physical device** | iOS (required) | iOS Simulator is **not supported** — OmiKit binary is arm64 device-only |
+| **Physical device** | Android (recommended) | Emulator works for basic UI testing but VoIP/audio routing is unreliable |
+| **Google Play Services** | Android (required) | Required for FCM push notifications |
+| **Microphone** | Both (required) | Required for all calls |
+| **Camera** | Both (optional) | Only required for video calls |
+| **Internet** | Both (required) | SIP registration + RTP media streaming |
+
+### Package Size
+
+| Component | Size |
+|-----------|------|
+| npm package (total) | ~353 KB |
+| Android native code | ~4.7 MB |
+| iOS native code | ~176 KB |
+
+> **Note:** These sizes are for the plugin only. The native SDKs (OmiKit/OMIKIT) are installed separately via CocoaPods/Maven and will add to the final app size.
 
 ---
 
@@ -102,7 +131,32 @@ Add to `android/app/src/main/AndroidManifest.xml`:
 >
 > Make sure to add the `tools` namespace to your manifest tag: `xmlns:tools="http://schemas.android.com/tools"`
 
-### 2. Firebase Cloud Messaging (FCM)
+### 2. Incoming Call Activity (Required)
+
+Your main Activity must handle incoming call intents from the SDK. Add the following `intent-filter` to your `MainActivity` in `AndroidManifest.xml`:
+
+```xml
+<activity
+  android:name=".MainActivity"
+  android:showWhenLocked="true"
+  android:turnScreenOn="true"
+  android:launchMode="singleTask"
+  ...>
+
+  <!-- Incoming call intent-filter (required for lock screen) -->
+  <intent-filter>
+    <action android:name="${applicationId}.ACTION_INCOMING_CALL" />
+    <action android:name="android.intent.action.CALL" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <data android:host="incoming_call" android:scheme="omisdk" />
+  </intent-filter>
+</activity>
+```
+
+> **Important:** The `${applicationId}.ACTION_INCOMING_CALL` action ensures incoming calls show correctly on **lock screen** for Android 9-14. Without this, the default dialer may intercept the intent instead of your app.
+
+### 3. Firebase Cloud Messaging (FCM)
+
 
 Add your `google-services.json` to `android/app/`.
 
@@ -112,7 +166,7 @@ In `android/app/build.gradle`:
 apply plugin: 'com.google.gms.google-services'
 ```
 
-### 3. Maven Repository
+### 4. Maven Repository
 
 **Option A — `settings.gradle.kts` (recommended for new projects)**
 
@@ -172,7 +226,7 @@ OMI_TOKEN=omi_github_access_token
 
 > **Note:** Contact the OMICall development team to get `OMI_USER` and `OMI_TOKEN` credentials.
 
-### 4. New Architecture (Optional)
+### 5. New Architecture (Optional)
 
 To enable New Architecture on Android, in `android/gradle.properties`:
 
@@ -209,13 +263,352 @@ Enable **Push Notifications** capability in Xcode for VoIP push (PushKit).
 
 ### 4. AppDelegate Setup
 
-In your `AppDelegate.mm` (or `.m`):
+The AppDelegate template differs depending on your React Native version. Choose the one that matches your project:
+
+#### RN 0.74 – 0.78 (RCTAppDelegate pattern)
+
+<details>
+<summary>AppDelegate.h</summary>
 
 ```objc
-#import <OmiKit/OmiKit-umbrella.h>
-#import <OmiKit/Constants.h>
+#import <RCTAppDelegate.h>
+#import <UIKit/UIKit.h>
+#import <UserNotifications/UserNotifications.h>
+#import <OmiKit/OmiKit.h>
+
+@interface AppDelegate : RCTAppDelegate <UIApplicationDelegate, RCTBridgeDelegate, UNUserNotificationCenterDelegate>
+
+@property (nonatomic, strong) UIWindow *window;
+@property (nonatomic, strong) PushKitManager *pushkitManager;
+@property (nonatomic, strong) CallKitProviderDelegate *provider;
+@property (nonatomic, strong) PKPushRegistry *voipRegistry;
+
+@end
+```
+
+</details>
+
+<details>
+<summary>AppDelegate.mm</summary>
+
+```objc
+#import "AppDelegate.h"
+#import <Firebase.h>
+#import <React/RCTBundleURLProvider.h>
+#import <OmiKit/OmiKit.h>
+
+#if __has_include("OmikitNotification.h")
+#import "OmikitNotification.h"
+#else
+#import <omikit_plugin/OmikitNotification.h>
+#endif
+
+@implementation AppDelegate
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
+{
+  self.moduleName = @"YourAppName"; // Replace with your app name
+
+  // ----- OmiKit Config ------
+  [OmiClient setEnviroment:KEY_OMI_APP_ENVIROMENT_SANDBOX
+                userNameKey:@"full_name"
+                    maxCall:2
+               callKitImage:@"call_image"
+              typePushVoip:TYPE_PUSH_CALLKIT_DEFAULT];
+
+  self.provider = [[CallKitProviderDelegate alloc]
+      initWithCallManager:[OMISIPLib sharedInstance].callManager];
+  self.voipRegistry = [[PKPushRegistry alloc]
+      initWithQueue:dispatch_get_main_queue()];
+  self.pushkitManager = [[PushKitManager alloc]
+      initWithVoipRegistry:self.voipRegistry];
+
+  if (@available(iOS 10.0, *)) {
+    [UNUserNotificationCenter currentNotificationCenter].delegate =
+        (id<UNUserNotificationCenterDelegate>)self;
+  }
+
+  if ([FIRApp defaultApp] == nil) {
+    [FIRApp configure];
+  }
+  // ----- End OmiKit Config ------
+
+  return [super application:application didFinishLaunchingWithOptions:launchOptions];
+}
+
+// Handle foreground notifications
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+       willPresentNotification:(UNNotification *)notification
+         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
+{
+  completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
+}
+
+// Handle missed call notification tap
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+didReceiveNotificationResponse:(UNNotificationResponse *)response
+         withCompletionHandler:(void (^)())completionHandler
+{
+  NSDictionary *userInfo = response.notification.request.content.userInfo;
+  if (userInfo && [userInfo valueForKey:@"omisdkCallerNumber"]) {
+    [OmikitNotification didRecieve:userInfo];
+  }
+  completionHandler();
+}
+
+// Register push notification token
+- (void)application:(UIApplication *)app
+    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)devToken
+{
+  const unsigned char *data = (const unsigned char *)[devToken bytes];
+  NSMutableString *token = [NSMutableString string];
+  for (NSUInteger i = 0; i < [devToken length]; i++) {
+    [token appendFormat:@"%02.2hhX", data[i]];
+  }
+  [OmiClient setUserPushNotificationToken:[token copy]];
+}
+
+// Terminate all calls when app is killed
+- (void)applicationWillTerminate:(UIApplication *)application {
+  @try {
+    [OmiClient OMICloseCall];
+  } @catch (NSException *exception) {}
+}
+
+- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
+{
+  return [self bundleURL];
+}
+
+- (NSURL *)bundleURL
+{
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+#endif
+}
+
+@end
 ```
 
+</details>
+
+#### RN 0.79+ (RCTReactNativeFactory pattern)
+
+RN 0.79+ uses `RCTReactNativeFactory` instead of `RCTAppDelegate`. Add OmiKit setup in your existing AppDelegate:
+
+<details>
+<summary>AppDelegate.swift (Swift template)</summary>
+
+```swift
+import UIKit
+import React
+import ReactAppDependencyProvider
+import OmiKit
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
+  var window: UIWindow?
+  var provider: CallKitProviderDelegate?
+  var pushkitManager: PushKitManager?
+  var voipRegistry: PKPushRegistry?
+
+  func application(_ application: UIApplication,
+                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    // React Native setup
+    let delegate = ReactNativeDelegate()
+    let factory = RCTReactNativeFactory(delegate: delegate)
+    delegate.dependencyProvider = RCTAppDependencyProvider()
+
+    window = UIWindow(frame: UIScreen.main.bounds)
+    factory.startReactNative(
+      withModuleName: "YourAppName",
+      in: window,
+      launchOptions: launchOptions
+    )
+
+    // ----- OmiKit Config ------
+    #ifdef DEBUG
+    OmiClient.setEnviroment(KEY_OMI_APP_ENVIROMENT_SANDBOX,
+                            userNameKey: "full_name",
+                            maxCall: 1,
+                            callKitImage: "call_image",
+                            typePushVoip: TYPE_PUSH_CALLKIT_DEFAULT)
+    #else
+    OmiClient.setEnviroment(KEY_OMI_APP_ENVIROMENT_PRODUCTION,
+                            userNameKey: "full_name",
+                            maxCall: 1,
+                            callKitImage: "call_image",
+                            typePushVoip: TYPE_PUSH_CALLKIT_DEFAULT)
+    #endif
+
+    provider = CallKitProviderDelegate(callManager: OMISIPLib.sharedInstance().callManager)
+    voipRegistry = PKPushRegistry(queue: .main)
+    pushkitManager = PushKitManager(voipRegistry: voipRegistry!)
+
+    UNUserNotificationCenter.current().delegate = self
+    FirebaseApp.configure()
+    // ----- End OmiKit Config ------
+
+    return true
+  }
+
+  // Handle missed call notification tap
+  func userNotificationCenter(_ center: UNUserNotificationCenter,
+                              didReceive response: UNNotificationResponse,
+                              withCompletionHandler completionHandler: @escaping () -> Void) {
+    let userInfo = response.notification.request.content.userInfo
+    if userInfo["omisdkCallerNumber"] != nil {
+      OmikitNotification.didRecieve(userInfo)
+    }
+    completionHandler()
+  }
+
+  // Register push notification token
+  func application(_ application: UIApplication,
+                   didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+    let token = deviceToken.map { String(format: "%02.2hhX", $0) }.joined()
+    OmiClient.setUserPushNotificationToken(token)
+  }
+
+  // Terminate all calls when app is killed
+  func applicationWillTerminate(_ application: UIApplication) {
+    try? OmiClient.omiCloseCall()
+  }
+}
+
+class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
+  override func sourceURL(for bridge: RCTBridge) -> URL? {
+    return bundleURL()
+  }
+
+  override func bundleURL() -> URL? {
+    #if DEBUG
+    return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+    #else
+    return Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+    #endif
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>AppDelegate.mm (Objective-C template)</summary>
+
+```objc
+#import "AppDelegate.h"
+#import <Firebase.h>
+#import <React/RCTBundleURLProvider.h>
+#import <React/RCTReactNativeFactory.h>
+#import <ReactAppDependencyProvider/RCTAppDependencyProvider.h>
+#import <OmiKit/OmiKit.h>
+
+#if __has_include("OmikitNotification.h")
+#import "OmikitNotification.h"
+#else
+#import <omikit_plugin/OmikitNotification.h>
+#endif
+
+@interface ReactNativeDelegate : RCTDefaultReactNativeFactoryDelegate
+@end
+
+@implementation AppDelegate
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
+{
+  ReactNativeDelegate *delegate = [ReactNativeDelegate new];
+  RCTReactNativeFactory *factory = [[RCTReactNativeFactory alloc] initWithDelegate:delegate];
+  delegate.dependencyProvider = [RCTAppDependencyProvider new];
+
+  self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
+  [factory startReactNativeWithModuleName:@"YourAppName" in:self.window launchOptions:launchOptions];
+
+  // ----- OmiKit Config ------
+  #ifdef DEBUG
+        [OmiClient setEnviroment:KEY_OMI_APP_ENVIROMENT_SANDBOX userNameKey:@"full_name" maxCall:1 callKitImage:@"icYourApp" typePushVoip:@"background"];
+  #else
+        [OmiClient setEnviroment:KEY_OMI_APP_ENVIROMENT_PRODUCTION userNameKey:@"full_name" maxCall:1 callKitImage:@"icYourApp" typePushVoip:@"background"];
+  #endif
+
+  self.provider = [[CallKitProviderDelegate alloc]
+      initWithCallManager:[OMISIPLib sharedInstance].callManager];
+  self.voipRegistry = [[PKPushRegistry alloc]
+      initWithQueue:dispatch_get_main_queue()];
+  self.pushkitManager = [[PushKitManager alloc]
+      initWithVoipRegistry:self.voipRegistry];
+
+  if (@available(iOS 10.0, *)) {
+    [UNUserNotificationCenter currentNotificationCenter].delegate =
+        (id<UNUserNotificationCenterDelegate>)self;
+  }
+
+  if ([FIRApp defaultApp] == nil) {
+    [FIRApp configure];
+  }
+  // ----- End OmiKit Config ------
+
+  return YES;
+}
+
+// Handle missed call notification tap
+- (void)userNotificationCenter:(UNUserNotificationCenter *)center
+didReceiveNotificationResponse:(UNNotificationResponse *)response
+         withCompletionHandler:(void (^)())completionHandler
+{
+  NSDictionary *userInfo = response.notification.request.content.userInfo;
+  if (userInfo && [userInfo valueForKey:@"omisdkCallerNumber"]) {
+    [OmikitNotification didRecieve:userInfo];
+  }
+  completionHandler();
+}
+
+// Register push notification token
+- (void)application:(UIApplication *)app
+    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)devToken
+{
+  const unsigned char *data = (const unsigned char *)[devToken bytes];
+  NSMutableString *token = [NSMutableString string];
+  for (NSUInteger i = 0; i < [devToken length]; i++) {
+    [token appendFormat:@"%02.2hhX", data[i]];
+  }
+  [OmiClient setUserPushNotificationToken:[token copy]];
+}
+
+// Terminate all calls when app is killed
+- (void)applicationWillTerminate:(UIApplication *)application {
+  @try {
+    [OmiClient OMICloseCall];
+  } @catch (NSException *exception) {}
+}
+
+@end
+
+@implementation ReactNativeDelegate
+
+- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
+{
+  return [self bundleURL];
+}
+
+- (NSURL *)bundleURL
+{
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+#endif
+}
+
+@end
+```
+
+</details>
+
+> **Note:** Replace `YourAppName` with your app's module name. For production, change `KEY_OMI_APP_ENVIROMENT_SANDBOX` to `KEY_OMI_APP_ENVIROMENT_PRODUCTION`.
+
 ### 5. New Architecture (Optional)
 
 In your `Podfile`:
@@ -224,15 +617,20 @@ In your `Podfile`:
 ENV['RN_NEW_ARCH_ENABLED'] = '1'
 ```
 
-For **full bridgeless mode**, in `AppDelegate.mm`:
+For **New Architecture with video call support**, add Fabric interop registration in `AppDelegate.mm` inside `didFinishLaunchingWithOptions`, **before** `return [super ...]`:
 
 ```objc
-- (BOOL)bridgelessEnabled
-{
-  return YES;
-}
+// Required imports at the top of AppDelegate.mm
+#import <React-RCTFabric/React/RCTComponentViewFactory.h>
+#import <React-RCTFabric/React/RCTLegacyViewManagerInteropComponentView.h>
+
+// Inside didFinishLaunchingWithOptions, before return:
+[RCTLegacyViewManagerInteropComponentView supportLegacyViewManagerWithName:@"OmiLocalCameraView"];
+[RCTLegacyViewManagerInteropComponentView supportLegacyViewManagerWithName:@"OmiRemoteCameraView"];
 ```
 
+> **Important:** Bridgeless mode is **not yet supported** for video call views. If you use New Architecture, keep bridge mode enabled (do **not** add `bridgelessEnabled` returning `YES`).
+
 Then run `cd ios && pod install`.
 
 ---
@@ -264,7 +662,7 @@ Then run `cd ios && pod install`.
    │      │      │                  │      │       │
    │      ▼      │                  │      ▼       │
    │  OMIKIT SDK │                  │  OmiKit SDK  │
-   │  (v2.6.4)   │                  │  (v1.10.34)  │
+   │  (v2.6.5)   │                  │  (v1.11.4)  │
    │      │      │                  │      │       │
    │      ▼      │                  │      ▼       │
    │  SIP Stack  │                  │  SIP Stack   │
@@ -945,44 +1343,259 @@ omiEmitter.addListener(OmiCallEvent.onCallStateChanged, (data) => {
 
 ## Video Calls
 
-### Setup
+> **Important:** To use video calls, you must login with `isVideo: true` in `initCallWithUserPassword()`. This enables camera support during SIP registration.
+
+### Prerequisites
 
 ```typescript
-import { OmiLocalCamera, OmiRemoteCamera } from 'omikit-plugin';
+// Login with video support enabled
+await initCallWithUserPassword({
+  userName: 'sip_user',
+  password: 'sip_password',
+  realm: 'your_realm',
+  isVideo: true,       // Required for video call support
+  fcmToken: fcmToken,
+});
 ```
 
 ### Video Components
 
 ```tsx
-// Local camera preview (your camera)
-<OmiLocalCamera style={{ width: 120, height: 160 }} />
-
-// Remote camera view (other party's video)
-<OmiRemoteCamera style={{ width: '100%', height: '100%' }} />
+import {
+  OmiLocalCameraView,   // Your camera preview
+  OmiRemoteCameraView,  // Remote party's video
+  registerVideoEvent,
+  removeVideoEvent,
+  refreshRemoteCamera,
+  refreshLocalCamera,
+  switchOmiCamera,
+  toggleOmiVideo,
+  setupVideoContainers, // iOS Fabric only
+  setCameraConfig,      // iOS Fabric only
+  omiEmitter,
+  OmiCallEvent,
+  OmiCallState,
+} from 'omikit-plugin';
 ```
 
-### Video Call Flow
+### Platform Differences
 
-```typescript
-// 1. Register for video events BEFORE starting call
-await registerVideoEvent();
+| Feature | Android | iOS (Old Arch) | iOS (New Arch / Fabric) |
+|---------|---------|----------------|------------------------|
+| Video rendering | JSX components | JSX components | Native window containers |
+| Camera views | `<OmiRemoteCameraView>` in JSX | `<OmiRemoteCameraView>` in JSX | `setupVideoContainers()` from JS |
+| Style control | React `style` props | React `style` props | `setCameraConfig()` from JS |
+| Controls overlay | Overlay on video | Overlay on video | Below video (split layout) |
+
+### Cross-Platform Video Call Example
 
-// 2. Start video call
-await startCall({ phoneNumber: '0901234567', isVideo: true });
+Complete example supporting both Android and iOS (Old + New Architecture):
+
+```tsx
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, Platform, Dimensions } from 'react-native';
+import {
+  OmiRemoteCameraView, OmiLocalCameraView,
+  omiEmitter, OmiCallEvent, OmiCallState,
+  registerVideoEvent, removeVideoEvent,
+  refreshRemoteCamera, refreshLocalCamera,
+  setupVideoContainers, setCameraConfig,
+  switchOmiCamera, toggleOmiVideo, toggleMute, endCall,
+} from 'omikit-plugin';
 
-// 3. Toggle video during call
-await toggleOmiVideo();   // on/off video stream
-await switchOmiCamera();  // front/back camera
+const { width: SW, height: SH } = Dimensions.get('window');
+
+export const VideoCallScreen = ({ navigation, route }) => {
+  const [isCallActive, setIsCallActive] = useState(false);
+  const [isMuted, setIsMuted] = useState(false);
+  const [cameraOn, setCameraOn] = useState(true);
+  const hasNavigated = useRef(false);
+
+  // iOS Fabric: configure native video container position/size
+  const configureIOSVideo = useCallback(() => {
+    setCameraConfig({
+      target: 'remote',
+      x: 0, y: 0, width: SW, height: SH * 0.65,
+      scaleMode: 'fill', backgroundColor: '#000',
+    });
+    setCameraConfig({
+      target: 'local',
+      x: SW - 136, y: 60, width: 120, height: 180,
+      borderRadius: 12, scaleMode: 'fill',
+    });
+  }, []);
+
+  useEffect(() => {
+    // iOS: register video events before call
+    if (Platform.OS === 'ios') registerVideoEvent();
+
+    const sub = omiEmitter.addListener(OmiCallEvent.onCallStateChanged, (data) => {
+      const { status } = data;
+
+      if (status === OmiCallState.confirmed) {
+        setIsCallActive(true);
+
+        if (Platform.OS === 'android') {
+          // Android: connect video feeds to TextureView surfaces
+          refreshRemoteCamera();
+          refreshLocalCamera();
+        } else {
+          // iOS Fabric: create native window containers + connect SDK
+          setupVideoContainers().then(() => configureIOSVideo());
+        }
+      }
 
-// 4. Listen for remote video ready
-omiEmitter.addListener(OmiCallEvent.onRemoteVideoReady, () => {
-  // Remote video is now available - show OmiRemoteCamera
+      if ((status === OmiCallState.disconnected || status === 6) && !hasNavigated.current) {
+        hasNavigated.current = true;
+        // iOS: hide native containers before navigating
+        if (Platform.OS === 'ios') {
+          setCameraConfig({ target: 'remote', hidden: true });
+          setCameraConfig({ target: 'local', hidden: true });
+        }
+        setTimeout(() => {
+          navigation.reset({ index: 0, routes: [{ name: 'Home' }] });
+        }, 100);
+      }
+    });
+
+    return () => {
+      sub.remove();
+      if (Platform.OS === 'ios') removeVideoEvent();
+    };
+  }, [navigation, configureIOSVideo]);
+
+  const handleEndCall = useCallback(() => {
+    if (hasNavigated.current) return;
+    hasNavigated.current = true;
+    if (Platform.OS === 'ios') {
+      setCameraConfig({ target: 'remote', hidden: true });
+      setCameraConfig({ target: 'local', hidden: true });
+    }
+    endCall();
+    setTimeout(() => {
+      navigation.reset({ index: 0, routes: [{ name: 'Home' }] });
+    }, 1000);
+  }, [navigation]);
+
+  return (
+    <View style={styles.container}>
+      {/* ============ VIDEO AREA ============ */}
+
+      {/* Android: camera views via JSX — controls can overlay on top */}
+      {Platform.OS === 'android' && isCallActive && (
+        <>
+          <OmiRemoteCameraView style={StyleSheet.absoluteFillObject} />
+          <OmiLocalCameraView style={styles.localPiP} />
+        </>
+      )}
+
+      {/* iOS Fabric: native video renders on window (top ~65%).
+          React controls render below video area. */}
+
+      {/* ============ CONTROLS AREA ============ */}
+
+      {/* Spacer — pushes controls to bottom */}
+      <View style={{ flex: 1 }} />
+
+      {/* Controls panel */}
+      {isCallActive && (
+        <View style={styles.controls}>
+          <TouchableOpacity onPress={() => { toggleMute(); setIsMuted(m => !m); }}>
+            <Text style={styles.btn}>{isMuted ? 'Unmute' : 'Mute'}</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={() => { toggleOmiVideo(); setCameraOn(c => !c); }}>
+            <Text style={styles.btn}>{cameraOn ? 'Cam Off' : 'Cam On'}</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={switchOmiCamera}>
+            <Text style={styles.btn}>Flip</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={handleEndCall}>
+            <Text style={[styles.btn, { backgroundColor: 'red' }]}>End</Text>
+          </TouchableOpacity>
+        </View>
+      )}
+
+      {/* Answer/Reject for incoming calls */}
+      {!isCallActive && (
+        <View style={styles.controls}>
+          <TouchableOpacity onPress={handleEndCall}>
+            <Text style={[styles.btn, { backgroundColor: 'red' }]}>Reject</Text>
+          </TouchableOpacity>
+        </View>
+      )}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: '#1E3050' },
+  localPiP: {
+    position: 'absolute', top: 60, right: 16,
+    width: 120, height: 180, borderRadius: 12, overflow: 'hidden', zIndex: 10,
+  },
+  controls: {
+    flexDirection: 'row', justifyContent: 'space-evenly',
+    paddingVertical: 20, paddingHorizontal: 16,
+    backgroundColor: 'rgba(0,0,0,0.5)', borderTopLeftRadius: 24, borderTopRightRadius: 24,
+    paddingBottom: 40,
+  },
+  btn: {
+    color: '#fff', fontSize: 14, paddingVertical: 12, paddingHorizontal: 16,
+    backgroundColor: 'rgba(255,255,255,0.2)', borderRadius: 24, overflow: 'hidden',
+  },
 });
+```
+
+> **Key differences per platform:**
+> - **Android**: `<OmiRemoteCameraView>` + `<OmiLocalCameraView>` render in JSX. Call `refreshRemoteCamera()` + `refreshLocalCamera()` when confirmed. Controls overlay on video.
+> - **iOS (Old Arch)**: Same as Android — JSX camera views work normally.
+> - **iOS (New Arch/Fabric)**: `RCTViewManager.view()` not called. Use `setupVideoContainers()` to create native window containers, then `setCameraConfig()` to adjust position/style. Controls render below video (split layout).
+> - **Disconnect**: On iOS, call `setCameraConfig({ target: 'remote', hidden: true })` before navigating to prevent stale video overlay. Use `setTimeout` for navigation — native event callback may block immediate navigation.
+> - **End call**: Use `navigation.reset()` instead of `goBack()` to clear stacked screens. Guard with `useRef` to prevent multiple navigations.
 
-// 5. Cleanup when call ends
-await removeVideoEvent();
+### `setCameraConfig()` — iOS Fabric Only
+
+Control native video container style from JS:
+
+```typescript
+setCameraConfig({
+  target: 'local' | 'remote',
+  x?: number,              // X position
+  y?: number,              // Y position
+  width?: number,          // View width
+  height?: number,         // View height
+  borderRadius?: number,   // Corner radius
+  borderWidth?: number,    // Border width
+  borderColor?: string,    // Hex color (#RRGGBB or #RRGGBBAA)
+  backgroundColor?: string,
+  opacity?: number,        // 0.0 - 1.0
+  hidden?: boolean,        // Show/hide
+  scaleMode?: 'fill' | 'fit' | 'stretch',
+});
 ```
 
+### Video API Reference
+
+| Function | Description | Platform |
+|----------|-------------|----------|
+| `registerVideoEvent()` | Register for video notifications | iOS only |
+| `removeVideoEvent()` | Cleanup video notifications | iOS only |
+| `refreshRemoteCamera()` | Connect remote video feed to surface | Both |
+| `refreshLocalCamera()` | Connect local camera feed to surface | Both |
+| `switchOmiCamera()` | Switch front/back camera | Both |
+| `toggleOmiVideo()` | Toggle camera on/off during call | Both |
+| `setupVideoContainers()` | Create native video containers on window | iOS Fabric only |
+| `setCameraConfig()` | Control video container style/position | iOS Fabric only |
+
+### Known Limitations
+
+- **iOS Fabric**: Controls cannot overlay on top of video (native window z-order). Use split layout — video top, controls bottom.
+- **iOS Fabric**: Camera switch has ~3-6s delay (SDK Metal stabilization).
+- **Android**: Must login with `isVideo: true` for camera to initialize. Without it, colorbar test pattern shows instead of camera.
+- **Simulator**: Video calls require physical device on both platforms.
+
+See [Known Issues](./docs/known-issues.md) for full details.
+
 ---
 
 ## Push Notifications
@@ -1214,7 +1827,10 @@ if (initialCall) {
 | Incoming call on Android — no UI | Missing overlay permission | Call `requestSystemAlertWindowPermission()` |
 | `startCall` returns 450/451/452 | Missing runtime permissions | Call `requestPermissionsByCodes([code])` |
 | No audio during call | Audio route issue | Check `getAudio()` and `setAudio()` |
-| Video not showing | Video event not registered | Call `registerVideoEvent()` before the call |
+| Video not showing (iOS) | Video event not registered | Call `registerVideoEvent()` before the call |
+| Video shows colorbar (Android) | Login with `isVideo: false` | Login with `isVideo: true` to enable camera |
+| Video black screen (Android) | Feed not connected | Ensure `refreshRemoteCamera()` + `refreshLocalCamera()` called on confirmed |
+| iOS Fabric: controls hidden | Native video on UIWindow covers React | Use split layout — video top, controls bottom. See [Known Issues](./docs/known-issues.md) |
 | NativeEventEmitter warning (iOS) | Old RN bridge issue | Upgrade to v4.0.x with New Architecture |
 | `Invalid local URI` in logs | Empty proxy/host in login | Pass `host` parameter in `initCallWithUserPassword` |
 | Build error with New Arch | Codegen not configured | Ensure `codegenConfig` exists in `package.json` |
@@ -1227,6 +1843,7 @@ if (initialCall) {
 Full documentation in [`./docs/`](./docs/):
 
 - [API Integration Guide (App-to-App)](./docs/api-integration-guide.md)
+- [Known Issues & Limitations](./docs/known-issues.md)
 - [Project Overview & PDR](./docs/project-overview-pdr.md)
 - [Codebase Summary](./docs/codebase-summary.md)
 - [System Architecture](./docs/system-architecture.md)