react-native-tvos 0.76.2-0 → 0.77.0-0rc1

package/ReactAndroid/src/main/java/com/facebook/react/HeadlessJsTaskService.java

@@ -19,7 +19,7 @@ import androidx.annotation.Nullable;
 import com.facebook.infer.annotation.Assertions;
 import com.facebook.react.bridge.ReactContext;
 import com.facebook.react.bridge.UiThreadUtil;
-import com.facebook.react.config.ReactFeatureFlags;
+import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags;
 import com.facebook.react.jstasks.HeadlessJsTaskConfig;
 import com.facebook.react.jstasks.HeadlessJsTaskContext;
 import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
@@ -167,7 +167,7 @@ public abstract class HeadlessJsTaskService extends Service implements HeadlessJ
   }
 
   protected ReactContext getReactContext() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       ReactHost reactHost = getReactHost();
       Assertions.assertNotNull(reactHost, "getReactHost() is null in New Architecture");
       return reactHost.getCurrentReactContext();

package/ReactAndroid/src/main/java/com/facebook/react/NativeModuleRegistryBuilder.kt

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+package com.facebook.react
+
+import com.facebook.react.bridge.ModuleHolder
+import com.facebook.react.bridge.NativeModuleRegistry
+import com.facebook.react.bridge.ReactApplicationContext
+
+/** Helper class to build NativeModuleRegistry. */
+public class NativeModuleRegistryBuilder(
+    private val reactApplicationContext: ReactApplicationContext,
+) {
+
+  private val modules = HashMap<String, ModuleHolder>()
+
+  @Deprecated(
+      "ReactInstanceManager is not used",
+      ReplaceWith("NativeModuleRegistryBuilder(reactApplicationContext)"))
+  public constructor(
+      reactApplicationContext: ReactApplicationContext,
+      @Suppress("UNUSED_PARAMETER") reactInstanceManager: ReactInstanceManager
+  ) : this(reactApplicationContext) {}
+
+  public fun processPackage(reactPackage: ReactPackage) {
+    // We use an iterable instead of an iterator here to ensure thread safety, and that this list
+    // cannot be modified
+    val moduleHolders =
+        @Suppress("DEPRECATION")
+        if (reactPackage is LazyReactPackage) {
+          reactPackage.getNativeModuleIterator(reactApplicationContext)
+        } else if (reactPackage is BaseReactPackage) {
+          reactPackage.getNativeModuleIterator(reactApplicationContext)
+        } else {
+          ReactPackageHelper.getNativeModuleIterator(reactPackage, reactApplicationContext)
+        }
+    for (moduleHolder in moduleHolders) {
+      val name = moduleHolder.name
+      val existingNativeModule = modules[name]
+      if (existingNativeModule != null) {
+        check(moduleHolder.canOverrideExistingModule) {
+          """
+Native module $name tried to override ${existingNativeModule.className}.
+
+Check the getPackages() method in MainApplication.java, it might be that module is being created twice. 
+If this was your intention, set canOverrideExistingModule=true. This error may also be present if the 
+package is present only once in getPackages() but is also automatically added later during build time 
+by autolinking. Try removing the existing entry and rebuild.
+"""
+        }
+      }
+      modules[name] = moduleHolder
+    }
+  }
+
+  public fun build(): NativeModuleRegistry = NativeModuleRegistry(reactApplicationContext, modules)
+}

package/ReactAndroid/src/main/java/com/facebook/react/ReactActivity.java

@@ -148,6 +148,10 @@ public abstract class ReactActivity extends AppCompatActivity
     return mDelegate.getReactNativeHost();
   }
 
+  protected ReactHost getReactHost() {
+    return mDelegate.getReactHost();
+  }
+
   protected final ReactInstanceManager getReactInstanceManager() {
     return mDelegate.getReactInstanceManager();
   }

package/ReactAndroid/src/main/java/com/facebook/react/ReactActivityDelegate.java

@@ -18,8 +18,11 @@ import android.view.KeyEvent;
 import androidx.annotation.Nullable;
 import com.facebook.infer.annotation.Assertions;
 import com.facebook.react.bridge.Callback;
-import com.facebook.react.config.ReactFeatureFlags;
+import com.facebook.react.bridge.ReactContext;
+import com.facebook.react.common.annotations.DeprecatedInNewArchitecture;
+import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags;
 import com.facebook.react.modules.core.PermissionListener;
+import com.facebook.systrace.Systrace;
 
 /**
  * Delegate class for {@link ReactActivity}. You can subclass this to provide custom implementations
@@ -75,17 +78,25 @@ public class ReactActivityDelegate {
   }
 
   /**
-   * Get the {@link ReactNativeHost} used by this app. By default, assumes {@link
-   * Activity#getApplication()} is an instance of {@link ReactApplication} and calls {@link
+   * Get the {@link ReactNativeHost} used by this app with Bridge enabled. By default, assumes
+   * {@link Activity#getApplication()} is an instance of {@link ReactApplication} and calls {@link
    * ReactApplication#getReactNativeHost()}. Override this method if your application class does not
    * implement {@code ReactApplication} or you simply have a different mechanism for storing a
    * {@code ReactNativeHost}, e.g. as a static field somewhere.
    */
+  @DeprecatedInNewArchitecture(message = "Use getReactHost()")
   protected ReactNativeHost getReactNativeHost() {
     return ((ReactApplication) getPlainActivity().getApplication()).getReactNativeHost();
   }
 
-  public ReactHost getReactHost() {
+  /**
+   * Get the {@link ReactHost} used by this app with Bridgeless enabled. By default, assumes {@link
+   * Activity#getApplication()} is an instance of {@link ReactApplication} and calls {@link
+   * ReactApplication#getReactHost()}. Override this method if your application class does not
+   * implement {@code ReactApplication} or you simply have a different mechanism for storing a
+   * {@code ReactHost}, e.g. as a static field somewhere.
+   */
+  public @Nullable ReactHost getReactHost() {
     return ((ReactApplication) getPlainActivity().getApplication()).getReactHost();
   }
 
@@ -93,6 +104,7 @@ public class ReactActivityDelegate {
     return mReactDelegate;
   }
 
+  @DeprecatedInNewArchitecture(message = "Use getReactHost()")
   public ReactInstanceManager getReactInstanceManager() {
     return mReactDelegate.getReactInstanceManager();
   }
@@ -102,35 +114,41 @@ public class ReactActivityDelegate {
   }
 
   public void onCreate(Bundle savedInstanceState) {
-    String mainComponentName = getMainComponentName();
-    final Bundle launchOptions = composeLaunchOptions();
-    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && isWideColorGamutEnabled()) {
-      mActivity.getWindow().setColorMode(ActivityInfo.COLOR_MODE_WIDE_COLOR_GAMUT);
-    }
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
-      mReactDelegate =
-          new ReactDelegate(getPlainActivity(), getReactHost(), mainComponentName, launchOptions);
-    } else {
-      mReactDelegate =
-          new ReactDelegate(
-              getPlainActivity(),
-              getReactNativeHost(),
-              mainComponentName,
-              launchOptions,
-              isFabricEnabled()) {
-            @Override
-            protected ReactRootView createRootView() {
-              ReactRootView rootView = ReactActivityDelegate.this.createRootView();
-              if (rootView == null) {
-                rootView = super.createRootView();
-              }
-              return rootView;
-            }
-          };
-    }
-    if (mainComponentName != null) {
-      loadApp(mainComponentName);
-    }
+    Systrace.traceSection(
+        Systrace.TRACE_TAG_REACT_JAVA_BRIDGE,
+        "ReactActivityDelegate.onCreate::init",
+        () -> {
+          String mainComponentName = getMainComponentName();
+          final Bundle launchOptions = composeLaunchOptions();
+          if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && isWideColorGamutEnabled()) {
+            mActivity.getWindow().setColorMode(ActivityInfo.COLOR_MODE_WIDE_COLOR_GAMUT);
+          }
+          if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
+            mReactDelegate =
+                new ReactDelegate(
+                    getPlainActivity(), getReactHost(), mainComponentName, launchOptions);
+          } else {
+            mReactDelegate =
+                new ReactDelegate(
+                    getPlainActivity(),
+                    getReactNativeHost(),
+                    mainComponentName,
+                    launchOptions,
+                    isFabricEnabled()) {
+                  @Override
+                  protected ReactRootView createRootView() {
+                    ReactRootView rootView = ReactActivityDelegate.this.createRootView();
+                    if (rootView == null) {
+                      rootView = super.createRootView();
+                    }
+                    return rootView;
+                  }
+                };
+          }
+          if (mainComponentName != null) {
+            loadApp(mainComponentName);
+          }
+        });
   }
 
   protected void loadApp(String appKey) {
@@ -219,6 +237,20 @@ public class ReactActivityDelegate {
     return ((Activity) getContext());
   }
 
+  protected ReactActivity getReactActivity() {
+    return ((ReactActivity) getContext());
+  }
+
+  /**
+   * Get the current {@link ReactContext} from ReactHost or ReactInstanceManager
+   *
+   * <p>Do not store a reference to this, if the React instance is reloaded or destroyed, this
+   * context will no longer be valid.
+   */
+  public @Nullable ReactContext getCurrentReactContext() {
+    return mReactDelegate.getCurrentReactContext();
+  }
+
   /**
    * Override this method if you wish to selectively toggle Fabric for a specific surface. This will
    * also control if Concurrent Root (React 18) should be enabled or not.
@@ -226,7 +258,7 @@ public class ReactActivityDelegate {
    * @return true if Fabric is enabled for this Activity, false otherwise.
    */
   protected boolean isFabricEnabled() {
-    return ReactFeatureFlags.enableFabricRenderer;
+    return ReactNativeFeatureFlags.enableFabricRenderer();
   }
 
   /**

package/ReactAndroid/src/main/java/com/facebook/react/ReactDelegate.java

@@ -14,12 +14,14 @@ import android.os.Bundle;
 import android.view.KeyEvent;
 import androidx.annotation.Nullable;
 import com.facebook.infer.annotation.Assertions;
+import com.facebook.react.bridge.ReactContext;
 import com.facebook.react.bridge.UiThreadUtil;
-import com.facebook.react.config.ReactFeatureFlags;
+import com.facebook.react.common.annotations.DeprecatedInNewArchitecture;
 import com.facebook.react.devsupport.DoubleTapReloadRecognizer;
 import com.facebook.react.devsupport.ReleaseDevSupportManager;
 import com.facebook.react.devsupport.interfaces.DevSupportManager;
 import com.facebook.react.interfaces.fabric.ReactSurface;
+import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags;
 import com.facebook.react.modules.core.DefaultHardwareBackBtnHandler;
 
 /**
@@ -29,7 +31,7 @@ import com.facebook.react.modules.core.DefaultHardwareBackBtnHandler;
 public class ReactDelegate {
 
   private final Activity mActivity;
-  private ReactRootView mReactRootView;
+  @Nullable private ReactRootView mReactRootView;
 
   @Nullable private final String mMainComponentName;
 
@@ -43,7 +45,7 @@ public class ReactDelegate {
 
   @Nullable private ReactSurface mReactSurface;
 
-  private boolean mFabricEnabled = ReactFeatureFlags.enableFabricRenderer;
+  private boolean mFabricEnabled = ReactNativeFeatureFlags.enableFabricRenderer();
 
   /**
    * Do not use this constructor as it's not accounting for New Architecture at all. You should
@@ -94,7 +96,7 @@ public class ReactDelegate {
 
   @Nullable
   private DevSupportManager getDevSupportManager() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()
         && mReactHost != null
         && mReactHost.getDevSupportManager() != null) {
       return mReactHost.getDevSupportManager();
@@ -111,7 +113,7 @@ public class ReactDelegate {
       throw new ClassCastException(
           "Host Activity does not implement DefaultHardwareBackBtnHandler");
     }
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onHostResume(mActivity, (DefaultHardwareBackBtnHandler) mActivity);
     } else {
       if (getReactNativeHost().hasInstance()) {
@@ -123,7 +125,7 @@ public class ReactDelegate {
   }
 
   public void onUserLeaveHint() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onHostLeaveHint(mActivity);
     } else {
       if (getReactNativeHost().hasInstance()) {
@@ -133,7 +135,7 @@ public class ReactDelegate {
   }
 
   public void onHostPause() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onHostPause(mActivity);
     } else {
       if (getReactNativeHost().hasInstance()) {
@@ -143,17 +145,10 @@ public class ReactDelegate {
   }
 
   public void onHostDestroy() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
-      if (mReactSurface != null) {
-        mReactSurface.stop();
-        mReactSurface = null;
-      }
+    unloadApp();
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onHostDestroy(mActivity);
     } else {
-      if (mReactRootView != null) {
-        mReactRootView.unmountReactApplication();
-        mReactRootView = null;
-      }
       if (getReactNativeHost().hasInstance()) {
         getReactNativeHost().getReactInstanceManager().onHostDestroy(mActivity);
       }
@@ -161,7 +156,7 @@ public class ReactDelegate {
   }
 
   public boolean onBackPressed() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onBackPressed();
       return true;
     } else {
@@ -174,7 +169,7 @@ public class ReactDelegate {
   }
 
   public boolean onNewIntent(Intent intent) {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onNewIntent(intent);
       return true;
     } else {
@@ -188,7 +183,7 @@ public class ReactDelegate {
 
   public void onActivityResult(
       int requestCode, int resultCode, Intent data, boolean shouldForwardToReactInstance) {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onActivityResult(mActivity, requestCode, resultCode, data);
     } else {
       if (getReactNativeHost().hasInstance() && shouldForwardToReactInstance) {
@@ -200,7 +195,7 @@ public class ReactDelegate {
   }
 
   public void onWindowFocusChanged(boolean hasFocus) {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onWindowFocusChange(hasFocus);
     } else {
       if (getReactNativeHost().hasInstance()) {
@@ -210,7 +205,7 @@ public class ReactDelegate {
   }
 
   public void onConfigurationChanged(Configuration newConfig) {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactHost.onConfigurationChanged(Assertions.assertNotNull(mActivity));
     } else {
       if (getReactNativeHost().hasInstance()) {
@@ -222,7 +217,7 @@ public class ReactDelegate {
 
   public boolean onKeyDown(int keyCode, KeyEvent event) {
     if (keyCode == KeyEvent.KEYCODE_MEDIA_FAST_FORWARD
-        && ((ReactFeatureFlags.enableBridgelessArchitecture
+        && ((ReactNativeFeatureFlags.enableBridgelessArchitecture()
                 && mReactHost != null
                 && mReactHost.getDevSupportManager() != null)
             || (getReactNativeHost().hasInstance()
@@ -235,7 +230,7 @@ public class ReactDelegate {
 
   public boolean onKeyLongPress(int keyCode) {
     if (keyCode == KeyEvent.KEYCODE_MEDIA_FAST_FORWARD) {
-      if (ReactFeatureFlags.enableBridgelessArchitecture && mReactHost != null) {
+      if (ReactNativeFeatureFlags.enableBridgelessArchitecture() && mReactHost != null) {
         DevSupportManager devSupportManager = mReactHost.getDevSupportManager();
         // onKeyLongPress is a Dev API and not supported in RELEASE mode.
         if (devSupportManager != null && !(devSupportManager instanceof ReleaseDevSupportManager)) {
@@ -261,7 +256,7 @@ public class ReactDelegate {
     // Reload in RELEASE mode
     if (devSupportManager instanceof ReleaseDevSupportManager) {
       // Do not reload the bundle from JS as there is no bundler running in release mode.
-      if (ReactFeatureFlags.enableBridgelessArchitecture) {
+      if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
         if (mReactHost != null) {
           mReactHost.reload("ReactDelegate.reload()");
         }
@@ -281,13 +276,19 @@ public class ReactDelegate {
     devSupportManager.handleReloadJS();
   }
 
+  /** Start the React surface with the app key supplied in the {@link ReactDelegate} constructor. */
   public void loadApp() {
     loadApp(mMainComponentName);
   }
 
+  /**
+   * Start the React surface for the given app key.
+   *
+   * @param appKey The ID of the app to load into the surface.
+   */
   public void loadApp(String appKey) {
     // With Bridgeless enabled, create and start the surface
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       if (mReactSurface == null) {
         mReactSurface = mReactHost.createSurface(mActivity, appKey, mLaunchOptions);
       }
@@ -302,9 +303,29 @@ public class ReactDelegate {
     }
   }
 
+  /** Stop the React surface started with {@link ReactDelegate#loadApp()}. */
+  public void unloadApp() {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
+      if (mReactSurface != null) {
+        mReactSurface.stop();
+        mReactSurface = null;
+      }
+    } else {
+      if (mReactRootView != null) {
+        mReactRootView.unmountReactApplication();
+        mReactRootView = null;
+      }
+    }
+  }
+
+  @Nullable
   public ReactRootView getReactRootView() {
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
-      return (ReactRootView) mReactSurface.getView();
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
+      if (mReactSurface != null) {
+        return (ReactRootView) mReactSurface.getView();
+      } else {
+        return null;
+      }
     } else {
       return mReactRootView;
     }
@@ -346,14 +367,38 @@ public class ReactDelegate {
   }
 
   /** Get the {@link ReactNativeHost} used by this app. */
+  @DeprecatedInNewArchitecture(message = "Use getReactHost()")
   private ReactNativeHost getReactNativeHost() {
     return mReactNativeHost;
   }
 
+  @DeprecatedInNewArchitecture(message = "Use getReactHost()")
   public ReactInstanceManager getReactInstanceManager() {
     return getReactNativeHost().getReactInstanceManager();
   }
 
+  public @Nullable ReactHost getReactHost() {
+    return mReactHost;
+  }
+
+  /**
+   * Get the current {@link ReactContext} from ReactHost or ReactInstanceManager
+   *
+   * <p>Do not store a reference to this, if the React instance is reloaded or destroyed, this
+   * context will no longer be valid.
+   */
+  public @Nullable ReactContext getCurrentReactContext() {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
+      if (mReactHost != null) {
+        return mReactHost.getCurrentReactContext();
+      } else {
+        return null;
+      }
+    } else {
+      return getReactInstanceManager().getCurrentReactContext();
+    }
+  }
+
   /**
    * Override this method if you wish to selectively toggle Fabric for a specific surface. This will
    * also control if Concurrent Root (React 18) should be enabled or not.

package/ReactAndroid/src/main/java/com/facebook/react/ReactFragment.java

@@ -17,7 +17,7 @@ import android.view.ViewGroup;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.fragment.app.Fragment;
-import com.facebook.react.config.ReactFeatureFlags;
+import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags;
 import com.facebook.react.modules.core.PermissionAwareActivity;
 import com.facebook.react.modules.core.PermissionListener;
 
@@ -31,8 +31,18 @@ public class ReactFragment extends Fragment implements PermissionAwareActivity {
   protected static final String ARG_LAUNCH_OPTIONS = "arg_launch_options";
   protected static final String ARG_FABRIC_ENABLED = "arg_fabric_enabled";
 
+  /**
+   * @deprecated We will remove this and use a different solution for handling Fragment lifecycle
+   *     events
+   */
+  @Deprecated
+  protected static final String ARG_DISABLE_HOST_LIFECYCLE_EVENTS =
+      "arg_disable_host_lifecycle_events";
+
   protected ReactDelegate mReactDelegate;
 
+  private boolean mDisableHostLifecycleEvents;
+
   @Nullable private PermissionListener mPermissionListener;
 
   public ReactFragment() {
@@ -66,14 +76,14 @@ public class ReactFragment extends Fragment implements PermissionAwareActivity {
       mainComponentName = getArguments().getString(ARG_COMPONENT_NAME);
       launchOptions = getArguments().getBundle(ARG_LAUNCH_OPTIONS);
       fabricEnabled = getArguments().getBoolean(ARG_FABRIC_ENABLED);
+      mDisableHostLifecycleEvents = getArguments().getBoolean(ARG_DISABLE_HOST_LIFECYCLE_EVENTS);
     }
     if (mainComponentName == null) {
       throw new IllegalStateException("Cannot loadApp if component name is null");
     }
-    if (ReactFeatureFlags.enableBridgelessArchitecture) {
+    if (ReactNativeFeatureFlags.enableBridgelessArchitecture()) {
       mReactDelegate =
-          new ReactDelegate(
-              getActivity(), getReactHost(), mainComponentName, launchOptions);
+          new ReactDelegate(getActivity(), getReactHost(), mainComponentName, launchOptions);
     } else {
       mReactDelegate =
           new ReactDelegate(
@@ -132,19 +142,27 @@ public class ReactFragment extends Fragment implements PermissionAwareActivity {
   @Override
   public void onResume() {
     super.onResume();
-    mReactDelegate.onHostResume();
+    if (!mDisableHostLifecycleEvents) {
+      mReactDelegate.onHostResume();
+    }
   }
 
   @Override
   public void onPause() {
     super.onPause();
-    mReactDelegate.onHostPause();
+    if (!mDisableHostLifecycleEvents) {
+      mReactDelegate.onHostPause();
+    }
   }
 
   @Override
   public void onDestroy() {
     super.onDestroy();
-    mReactDelegate.onHostDestroy();
+    if (!mDisableHostLifecycleEvents) {
+      mReactDelegate.onHostDestroy();
+    } else {
+      mReactDelegate.unloadApp();
+    }
   }
 
   // endregion

package/ReactAndroid/src/main/java/com/facebook/react/ReactHost.kt

@@ -84,7 +84,7 @@ public interface ReactHost {
       context: Context,
       moduleName: String,
       initialProps: Bundle?
-  ): ReactSurface?
+  ): ReactSurface
 
   /**
    * This function can be used to initialize the ReactInstance in a background thread before a
@@ -111,12 +111,44 @@ public interface ReactHost {
    * Entrypoint to destroy the ReactInstance. If the ReactInstance is reloading, will wait until
    * reload is finished, before destroying.
    *
-   * @param reason describing why ReactHost is being destroyed (e.g. memmory pressure)
+   * The destroy operation is asynchronous and the task returned by this method will complete when
+   * React Native gets destroyed. Note that the destroy operation will execute in multiple threads,
+   * in particular some of the sub-tasks will run in the UIThread. Calling
+   * [TaskInterface.waitForCompletion] from the UIThread will lead into a deadlock. Use [destroy]
+   * passing the onDestroyFinished callback to be notified when React Native gets destroyed.
+   *
+   * @param reason describing why ReactHost is being destroyed (e.g. memory pressure)
+   * @param ex exception that caused the trigger to destroy ReactHost (or null) This exception will
+   *   be used to log properly the cause of destroy operation.
+   * @return A task that completes when React Native gets destroyed.
+   */
+  public fun destroy(
+      reason: String,
+      ex: Exception?,
+  ): TaskInterface<Void>
+
+  /**
+   * Entrypoint to destroy the ReactInstance. If the ReactInstance is reloading, will wait until
+   * reload is finished, before destroying.
+   *
+   * The destroy operation is asynchronous and the task returned by this method will complete when
+   * React Native gets destroyed. Note that the destroy operation will execute in multiple threads,
+   * in particular some of the sub-tasks will run in the UIThread. Calling
+   * [TaskInterface.waitForCompletion] from the UIThread will lead into a deadlock. Use
+   * onDestroyFinished callback to be notified when React Native gets destroyed.
+   *
+   * @param reason describing why ReactHost is being destroyed (e.g. memory pressure)
    * @param ex exception that caused the trigger to destroy ReactHost (or null) This exception will
    *   be used to log properly the cause of destroy operation.
+   * @param onDestroyFinished callback that will be called when React Native gets destroyed, the
+   *   callback will run on a background thread.
    * @return A task that completes when React Native gets destroyed.
    */
-  public fun destroy(reason: String, ex: Exception?): TaskInterface<Void>
+  public fun destroy(
+      reason: String,
+      ex: Exception?,
+      onDestroyFinished: (instanceDestroyedSuccessfully: Boolean) -> Unit = {}
+  ): TaskInterface<Void>
 
   /**
    * Permanently destroys the ReactHost, including the ReactInstance (if any). The application MUST