@callstack/react-native-brownfield 5.0.2 → 5.1.1

package/ios/BrownfieldReactHostPreloader.m

@@ -0,0 +1,113 @@
+#import "BrownfieldReactHostPreloader.h"
+
+// This file is plain Objective-C, and not Objective-C++. The umbrella header of
+// React-RCTAppDelegate imports the Hermes and JSI headers if `__cplusplus` is set. This pod does
+// not have the necessary search paths for those headers. Without C++, the compiler ignores those
+// imports. The compiler then builds the module in the same way that Swift imports it.
+//
+// The name of the pod changes if the build makes it a framework. Thus you must try each possible
+// name. Expo uses the same method in `RCTAppDelegateUmbrella.h`.
+#if __has_include(<React_RCTAppDelegate/RCTRootViewFactory.h>)
+#import <React_RCTAppDelegate/RCTReactNativeFactory.h>
+#import <React_RCTAppDelegate/RCTRootViewFactory.h>
+#elif __has_include(<React-RCTAppDelegate/RCTRootViewFactory.h>)
+#import <React-RCTAppDelegate/RCTReactNativeFactory.h>
+#import <React-RCTAppDelegate/RCTRootViewFactory.h>
+#else
+#import <React/RCTReactNativeFactory.h>
+#import <React/RCTRootViewFactory.h>
+#endif
+
+NS_ASSUME_NONNULL_BEGIN
+
+// `RCTBundleConfiguration` first exists in React Native 0.84. React Native 0.83 does not declare
+// the class. This forward declaration lets the file name the type with both versions.
+@class RCTBundleConfiguration;
+
+/**
+ * The two shapes of `initializeReactHostWithLaunchOptions:...`. React Native 0.83 has the shape
+ * without `bundleConfiguration:`. React Native 0.84 added that parameter and removed the earlier
+ * shape. No header tells the two versions apart at compile time, thus this file declares both
+ * shapes and `respondsToSelector:` selects one at run time. The declarations are equal to the
+ * React Native declarations. The compiler then accepts the file with both versions.
+ */
+@protocol BrownfieldReactHostInitializing <NSObject>
+
+- (void)initializeReactHostWithLaunchOptions:(NSDictionary *__nullable)launchOptions
+                         bundleConfiguration:(RCTBundleConfiguration *)bundleConfiguration
+                        devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration;
+
+- (void)initializeReactHostWithLaunchOptions:(NSDictionary *__nullable)launchOptions
+                        devMenuConfiguration:(RCTDevMenuConfiguration *)devMenuConfiguration;
+
+@end
+
+/**
+ * `RCTReactNativeFactory.bundleConfiguration` also first exists in React Native 0.84.
+ */
+@protocol BrownfieldBundleConfigurationProviding <NSObject>
+
+@property (nonatomic, readonly) RCTBundleConfiguration *bundleConfiguration;
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+@implementation BrownfieldReactHostPreloader
+
++ (void)preloadWithReactNativeFactory:(id)reactNativeFactory
+                        launchOptions:(NSDictionary *_Nullable)launchOptions
+{
+  RCTReactNativeFactory *factory = (RCTReactNativeFactory *)reactNativeFactory;
+  RCTRootViewFactory *rootViewFactory = factory.rootViewFactory;
+
+  // `initializeReactHostWithLaunchOptions:...` returns early if a view, or an earlier preload,
+  // created a host. Thus this method makes no other check. React Native declares
+  // `rootViewFactory` as not nullable, and this guard is only a protection.
+  if (rootViewFactory == nil) {
+    return;
+  }
+
+  id<BrownfieldReactHostInitializing> hostInitializer = (id)rootViewFactory;
+  SEL initializeWithBundleConfiguration =
+      @selector(initializeReactHostWithLaunchOptions:bundleConfiguration:devMenuConfiguration:);
+  SEL initializeWithDevMenuConfiguration =
+      @selector(initializeReactHostWithLaunchOptions:devMenuConfiguration:);
+
+  // Get the configurations from the factory. Do not make new configurations from the default
+  // values. The Expo runtime sends `RCTReactNativeFactory.devMenuConfiguration` from
+  // `ExpoReactNativeFactory.recreateRootView:`, thus the factory value keeps the two runtimes
+  // equal.
+  //
+  // The preloaded host is equal to a host that a view creates later, but the two paths send
+  // different objects. The bare runtime creates the view with
+  // `viewWithModuleName:initialProperties:launchOptions:`, and that method sends
+  // `[RCTBundleConfiguration defaultConfiguration]` and `[RCTDevMenuConfiguration
+  // defaultConfiguration]`. The values are equal:
+  //   - `RCTReactNativeFactory.bundleConfiguration` gives `[RCTBundleConfiguration
+  //     defaultConfiguration]` while nobody sets another value.
+  //   - `RCTReactNativeFactory.devMenuConfiguration` is nil by default.
+  //     `RCTDevMenuConfigurationDecorator` does nothing with nil, and `RCTDevMenu` and
+  //     `RCTDevSettings` keep their own default values. Those values are equal to
+  //     `[RCTDevMenuConfiguration defaultConfiguration]`, because the two sides read `RCT_DEV_MENU`.
+  if ([hostInitializer respondsToSelector:initializeWithBundleConfiguration]) {
+    id<BrownfieldBundleConfigurationProviding> configurationProvider = (id)factory;
+
+    [hostInitializer initializeReactHostWithLaunchOptions:launchOptions
+                                      bundleConfiguration:configurationProvider.bundleConfiguration
+                                     devMenuConfiguration:factory.devMenuConfiguration];
+  } else if ([hostInitializer respondsToSelector:initializeWithDevMenuConfiguration]) {
+    [hostInitializer initializeReactHostWithLaunchOptions:launchOptions
+                                     devMenuConfiguration:factory.devMenuConfiguration];
+  } else {
+    // A React Native version with a third shape of the method. Do not crash. The first React
+    // Native view creates the host, as without a preload.
+    NSLog(
+        @"%@",
+        @"ReactNativeBrownfield: startReactNative did not preload the JavaScript bundle, because "
+        @"this React Native version has no known initializeReactHostWithLaunchOptions: method. The "
+        @"first React Native view loads the bundle.");
+  }
+}
+
+@end

package/ios/BrownfieldSurfaceRegistry.swift

@@ -0,0 +1,93 @@
+import Foundation
+
+/// Identifies one live React Native surface. Vended by `BrownfieldSurfaceRegistry`.
+struct BrownfieldSurfaceID: Hashable, CustomStringConvertible {
+  fileprivate let rawValue: UInt64
+
+  var description: String { "surface#\(rawValue)" }
+}
+
+/// Decides which React Native surface may act on a `popToNative()` request.
+///
+/// `popToNative()` is delivered as an app-wide notification, so every live React
+/// Native surface receives it — including ones buried under other screens. Acting
+/// on all of them tears down the whole navigation stack
+/// (https://github.com/callstack/react-native-brownfield/issues/354).
+///
+/// The registry resolves that to a single surface: whichever on-screen surface
+/// was shown most recently.
+///
+/// Visibility is asked for at query time instead of being cached from lifecycle
+/// callbacks. Hosts recreate view controllers — SwiftUI does it freely — and a
+/// cached flag is stale exactly when the notification arrives.
+///
+/// Deliberately free of UIKit so it can be unit tested on macOS via `swift test`.
+/// Internal, like the sibling `BrownfieldBundleSupport` target: it is an
+/// implementation detail of the pod, not API for host apps.
+final class BrownfieldSurfaceRegistry {
+  static let shared = BrownfieldSurfaceRegistry()
+
+  private struct Surface {
+    let isOnScreen: () -> Bool
+    var shownAt: UInt64
+  }
+
+  private let lock = NSLock()
+  private var nextSurfaceValue: UInt64 = 0
+  private var nextShownValue: UInt64 = 0
+  private var surfaces: [BrownfieldSurfaceID: Surface] = [:]
+
+  init() {}
+
+  /// - Parameter isOnScreen: queried on every `popTarget()`. Capture the host
+  ///   weakly so a released surface stops winning the election.
+  func register(isOnScreen: @escaping () -> Bool) -> BrownfieldSurfaceID {
+    lock.lock()
+    defer { lock.unlock() }
+
+    nextSurfaceValue += 1
+    let id = BrownfieldSurfaceID(rawValue: nextSurfaceValue)
+    surfaces[id] = Surface(isOnScreen: isOnScreen, shownAt: 0)
+    return id
+  }
+
+  func unregister(_ surface: BrownfieldSurfaceID) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    surfaces.removeValue(forKey: surface)
+  }
+
+  /// Records that a surface was just shown, ordering it ahead of other on-screen
+  /// surfaces. Only a tiebreaker — a surface never marked shown can still win
+  /// when it is the one on screen.
+  func markShown(_ surface: BrownfieldSurfaceID) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard var entry = surfaces[surface] else { return }
+
+    nextShownValue += 1
+    entry.shownAt = nextShownValue
+    surfaces[surface] = entry
+  }
+
+  /// The single surface allowed to handle `popToNative()`, or `nil` when no
+  /// React Native surface is on screen.
+  func popTarget() -> BrownfieldSurfaceID? {
+    lock.lock()
+    let candidates = surfaces
+    lock.unlock()
+
+    return candidates
+      .filter { $0.value.isOnScreen() }
+      .max { lhs, rhs in
+        (lhs.value.shownAt, lhs.key.rawValue) < (rhs.value.shownAt, rhs.key.rawValue)
+      }?
+      .key
+  }
+
+  func isPopTarget(_ surface: BrownfieldSurfaceID) -> Bool {
+    popTarget() == surface
+  }
+}

package/ios/Expo/ExpoHostRuntime.swift

@@ -11,7 +11,7 @@ internal import EXUpdates
 final class ExpoHostRuntime {
   static let shared = ExpoHostRuntime()
 
-  private let jsBundleLoadObserver = JSBundleLoadObserver()
+  let preloadState = ReactHostPreloadState()
   private var delegate = ExpoHostRuntimeDelegate()
   private var reactNativeFactory: RCTReactNativeFactory?
   private var expoDelegate: ExpoAppDelegate?
@@ -35,9 +35,15 @@ final class ExpoHostRuntime {
   /**
    * Starts React Native with optional callback when bundle is loaded.
    *
-   * @param onBundleLoaded Optional callback invoked after JS bundle is fully loaded.
+   * @param onBundleLoaded Optional callback invoked on the main thread after JS bundle is fully loaded.
    */
   public func startReactNative(onBundleLoaded: (() -> Void)?) {
+    // The callback registration is outside of the guard below. An earlier `startReactNative` call
+    // can already have made the factory, and the callback must still run.
+    if let onBundleLoaded {
+      preloadState.jsBundleLoadObserver.observe(onBundleLoaded: onBundleLoaded)
+    }
+
     guard reactNativeFactory == nil else { return }
 
     let appDelegate = ExpoAppDelegate()
@@ -50,10 +56,6 @@ final class ExpoHostRuntime {
     appDelegate.bindReactNativeFactory(reactNativeFactory)
     #endif
     expoDelegate = appDelegate
-
-    if let onBundleLoaded {
-      jsBundleLoadObserver.observeOnce(onBundleLoaded: onBundleLoaded)
-    }
   }
 
   /**
@@ -70,6 +72,7 @@ final class ExpoHostRuntime {
     }
     reactNativeFactory = nil
     expoDelegate = nil
+    preloadState.reset()
   }
 
   /**
@@ -169,6 +172,8 @@ final class ExpoHostRuntime {
     let bundleURL = delegate.bundleURL()
     configureDevLoadingView(with: bundleURL)
 
+    let resolvedLaunchOptions = preloadState.launchOptions(overriddenBy: launchOptions)
+
     // below: https://github.com/expo/expo/commit/2013760c46cde1404872d181a691da72fbf207a4
     // has moved the recreateRootView method to ExpoReactNativeFactory
     #if EXPO_SDK_GTE_55  // this define comes from the Brownfield Expo config plugin
@@ -176,19 +181,51 @@ final class ExpoHostRuntime {
       withBundleURL: bundleURL,
       moduleName: moduleName,
       initialProps: initialProps,
-      launchOptions: launchOptions
+      launchOptions: resolvedLaunchOptions
     )
     #else
     return expoDelegate?.recreateRootView(
       withBundleURL: bundleURL,
       moduleName: moduleName,
       initialProps: initialProps,
-      launchOptions: launchOptions
+      launchOptions: resolvedLaunchOptions
     )
     #endif
   }
 }
 
+extension ExpoHostRuntime: ReactHostPreloading {
+  var reactNativeFactoryForPreload: AnyObject? {
+    return reactNativeFactory
+  }
+
+  /**
+   * expo-dev-launcher finds the Metro URL only after the user selects an app in the launcher. This
+   * is a Debug behavior. In Release the class is in the binary, but it does nothing. Thus this
+   * check is also only in Debug.
+   *
+   * The check reads the class name, because this pod has no dependency on expo-dev-launcher.
+   * `EXDevLauncherController` is the name in expo-dev-launcher 56 and 57. If a later version
+   * changes the name, this method gives `true`, and a preload can keep a bundle of the launcher
+   * screen. Examine the name again when you add a new Expo SDK.
+   *
+   * `ExpoHostRuntimeDelegate.isBundleURLStable` covers the other conditions.
+   */
+  func canPreloadReactNative() -> Bool {
+    #if DEBUG
+    if NSClassFromString("EXDevLauncherController") != nil {
+      return false
+    }
+    #endif
+
+    return delegate.isBundleURLStable
+  }
+
+  func prepareDevLoadingView() {
+    configureDevLoadingView()
+  }
+}
+
 class ExpoHostRuntimeDelegate: ExpoReactNativeFactoryDelegate {
   var entryFile = ".expo/.virtual-metro-entry"
   var bundlePath = "main.jsbundle"
@@ -242,5 +279,30 @@ class ExpoHostRuntimeDelegate: ExpoReactNativeFactoryDelegate {
       return nil
     }
   }
+
+  /**
+   * `true` if `bundleURL()` gives now the same result as a later resolution. This property follows
+   * the steps of `bundleURL()`, and it must change together with them.
+   *
+   * The override wins over every other step, thus an override makes the URL stable.
+   *
+   * expo-updates selects the launch asset while `AppController` starts. `ReactNativeViewController`
+   * starts `AppController`. Before this operation is complete, `launchAssetUrl()` is nil, and
+   * `bundleURL()` gives the embedded bundle. A host from that time keeps the embedded bundle, and
+   * Expo never applies the update. Thus the URL is stable only after `launchAssetUrl()` has a
+   * value. The class can be in the binary while the app does not use it, thus this check reads the
+   * state and not the class.
+   */
+  var isBundleURLStable: Bool {
+    if bundleURLOverride?() != nil {
+      return true
+    }
+
+    #if canImport(EXUpdates) && !DEBUG
+    return AppController.isInitialized() && AppController.sharedInstance.launchAssetUrl() != nil
+    #else
+    return true
+    #endif
+  }
 }
 #endif

package/ios/JSBundleLoadObserver.swift

@@ -1,38 +1,85 @@
 import Foundation
-internal import React
 
+/**
+ * Watches the `RCTInstanceDidLoadBundle` notification, and calls the callback that waits for it.
+ *
+ * React Native sends the notification from the JavaScript thread. This class always calls the
+ * callback on the main thread, because the callback changes the user interface.
+ *
+ * The class starts to watch at the initialization, and not at the first callback. The class then
+ * knows that React Native loaded the bundle, also if nobody waited for the notification.
+ */
 final class JSBundleLoadObserver {
-  private var onBundleLoaded: (() -> Void)?
+  private var pendingCallback: (() -> Void)?
+  private var didLoadBundle = false
   private var observerToken: NSObjectProtocol?
 
-  func observeOnce(onBundleLoaded: @escaping () -> Void) {
-    removeObserverIfNeeded()
-    self.onBundleLoaded = onBundleLoaded
-
+  init() {
     observerToken = NotificationCenter.default.addObserver(
       forName: NSNotification.Name("RCTInstanceDidLoadBundle"),
       object: nil,
-      queue: nil
+      queue: .main
     ) { [weak self] _ in
-      self?.notifyAndClear()
+      self?.bundleDidLoad()
     }
   }
 
   deinit {
-    removeObserverIfNeeded()
+    if let observerToken {
+      NotificationCenter.default.removeObserver(observerToken)
+    }
+  }
+
+  /**
+   * Keeps one callback, and calls it one time. A new callback replaces the callback that waits. If
+   * React Native already loaded the bundle, the class calls the callback in the next turn of the
+   * main run loop.
+   *
+   * @param onBundleLoaded The class always calls this callback on the main thread.
+   */
+  func observe(onBundleLoaded: @escaping () -> Void) {
+    onMainThread { [weak self] in
+      self?.register(onBundleLoaded)
+    }
+  }
+
+  /**
+   * Removes the callback that waits, and forgets the bundle of the earlier session. Call this
+   * method when you stop React Native. A callback of the earlier session must not run in the next
+   * session.
+   */
+  func reset() {
+    onMainThread { [weak self] in
+      self?.pendingCallback = nil
+      self?.didLoadBundle = false
+    }
   }
 
-  private func notifyAndClear() {
-    let callback = onBundleLoaded
-    onBundleLoaded = nil
-    removeObserverIfNeeded()
+  // MARK: - Main thread only
+
+  private func register(_ onBundleLoaded: @escaping () -> Void) {
+    guard !didLoadBundle else {
+      DispatchQueue.main.async(execute: onBundleLoaded)
+      return
+    }
+
+    pendingCallback = onBundleLoaded
+  }
+
+  private func bundleDidLoad() {
+    didLoadBundle = true
+
+    let callback = pendingCallback
+    pendingCallback = nil
+
     callback?()
   }
 
-  private func removeObserverIfNeeded() {
-    if let observerToken {
-      NotificationCenter.default.removeObserver(observerToken)
-      self.observerToken = nil
+  private func onMainThread(_ work: @escaping () -> Void) {
+    if Thread.isMainThread {
+      work()
+    } else {
+      DispatchQueue.main.async(execute: work)
     }
   }
 }

package/ios/ReactHostPreloading.swift

@@ -0,0 +1,177 @@
+import Foundation
+
+/**
+ * The preload state that `startReactNative`, `view` and `stopReactNative` share.
+ */
+final class ReactHostPreloadState {
+  let jsBundleLoadObserver = JSBundleLoadObserver()
+
+  private let lock = NSLock()
+  private var storedLaunchOptions: [AnyHashable: Any]?
+  private var hasPreloadRequest = false
+
+  /**
+   * Keeps the launch options of a `startReactNative` call.
+   *
+   * `startReactNative` can move its preload work to the main thread. A view on the main thread can
+   * create the React Host before that. Thus this method must run at the call, and not after the
+   * change of thread. The view then finds the options.
+   */
+  func storeLaunchOptions(_ launchOptions: [AnyHashable: Any]?) {
+    guard let launchOptions else { return }
+
+    lock.lock()
+    defer { lock.unlock() }
+
+    storedLaunchOptions = launchOptions
+  }
+
+  /**
+   * Records that a `startReactNative` call must preload the bundle. `consumePreloadRequest` reads
+   * the request one time, and `reset` cancels it.
+   */
+  func requestPreload() {
+    lock.lock()
+    defer { lock.unlock() }
+
+    hasPreloadRequest = true
+  }
+
+  /**
+   * `true` if a preload request waits. The method also removes the request.
+   *
+   * `startReactNative` can move its preload work to the main thread. `stopReactNative` on the main
+   * thread can run before that work. The stop cancels the request, thus this method then gives
+   * `false`, and React Native stays stopped.
+   */
+  func consumePreloadRequest() -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+
+    let hadRequest = hasPreloadRequest
+    hasPreloadRequest = false
+
+    return hadRequest
+  }
+
+  /**
+   * The launch options for a call that can create the React Host. The options of the caller win
+   * over the options of an earlier `startReactNative` call.
+   */
+  func launchOptions(
+    overriddenBy explicitLaunchOptions: [AnyHashable: Any]? = nil
+  ) -> [AnyHashable: Any]? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    return explicitLaunchOptions ?? storedLaunchOptions
+  }
+
+  /**
+   * Removes the state of the session. Call this method when you stop React Native.
+   */
+  func reset() {
+    jsBundleLoadObserver.reset()
+
+    lock.lock()
+    defer { lock.unlock() }
+
+    storedLaunchOptions = nil
+    hasPreloadRequest = false
+  }
+}
+
+/**
+ * The preload sequence that the two host runtimes share. Only one runtime is in a build. The
+ * shared sequence keeps the behavior of the two runtimes equal.
+ */
+protocol ReactHostPreloading: AnyObject {
+  var preloadState: ReactHostPreloadState { get }
+
+  /**
+   * The React Native factory, or nil while React Native did not start. The type is `AnyObject`,
+   * because `BrownfieldReactHostPreloader` also takes the factory as `id`. This file then needs no
+   * React Native import, and it builds with both runtimes.
+   */
+  var reactNativeFactoryForPreload: AnyObject? { get }
+
+  func startReactNative()
+
+  /**
+   * `false` while the bundle URL can still change. The runtime must not create the host in this
+   * condition, because the host keeps the first bundle that it evaluates.
+   */
+  func canPreloadReactNative() -> Bool
+
+  func prepareDevLoadingView()
+}
+
+extension ReactHostPreloading {
+  /**
+   * The implementation of
+   * `ReactNativeBrownfield.startReactNative(launchOptions:preloadBundle:onBundleLoaded:)`, which
+   * holds the contract.
+   */
+  func startReactNative(
+    launchOptions: [AnyHashable: Any]?,
+    preloadBundle: Bool,
+    onBundleLoaded: (() -> Void)?
+  ) {
+    preloadState.storeLaunchOptions(launchOptions)
+
+    if let onBundleLoaded {
+      preloadState.jsBundleLoadObserver.observe(onBundleLoaded: onBundleLoaded)
+    }
+
+    guard preloadBundle else {
+      startReactNative()
+      return
+    }
+
+    preloadState.requestPreload()
+
+    if Thread.isMainThread {
+      createReactHost()
+    } else {
+      DispatchQueue.main.async { [weak self] in
+        self?.createReactHost()
+      }
+    }
+  }
+
+  private func createReactHost() {
+    // `stopReactNative` can run between the request and this method, because a caller that is not
+    // on the main thread moves the work to the main thread. The stop cancels the request, and
+    // React Native must then stay stopped.
+    guard preloadState.consumePreloadRequest() else { return }
+
+    startReactNative()
+
+    guard let factory = reactNativeFactoryForPreload else {
+      logSkippedPreload("React Native did not make the factory")
+      return
+    }
+
+    guard canPreloadReactNative() else {
+      logSkippedPreload("the bundle URL can still change")
+      return
+    }
+
+    // You must configure the dev loading view before React Native loads the bundle. Usually the
+    // `view` method does this.
+    prepareDevLoadingView()
+
+    BrownfieldReactHostPreloader.preload(
+      withReactNativeFactory: factory,
+      launchOptions: preloadState.launchOptions()
+    )
+  }
+
+  private func logSkippedPreload(_ reason: String) {
+    NSLog(
+      "%@",
+      "ReactNativeBrownfield: startReactNative did not preload the JavaScript bundle, because "
+        + reason + ". The first React Native view loads the bundle."
+    )
+  }
+}

package/ios/ReactNativeBrownfield.swift

@@ -192,7 +192,9 @@ internal import Expo
   /**
    * Starts React Native with optional callback when bundle is loaded.
    *
-   * @param onBundleLoaded Optional callback invoked after JS bundle is fully loaded.
+   * @param onBundleLoaded Optional callback invoked on the main thread after the JS bundle is
+   *   fully loaded. It runs in the next turn of the main run loop when the bundle is already
+   *   loaded. A new callback replaces the callback that waits.
    */
   @objc public func startReactNative(onBundleLoaded: (() -> Void)?) {
     #if canImport(Expo)
@@ -202,6 +204,39 @@ internal import Expo
     #endif
   }
 
+  /**
+   * Starts React Native, and optionally loads the JavaScript bundle immediately. Without a
+   * preload, React Native loads the bundle when it creates the first React Native view. On
+   * Android, `ReactNativeBrownfield.initialize` does the same operation.
+   *
+   * @param launchOptions The launch options for the React Host. Only the call that creates the
+   *   host reads these options. This method keeps the options. A view that creates the host later
+   *   uses them, also if this method cannot create the host. Options that you give to `view` win
+   *   over these options.
+   * @param preloadBundle `true` loads and evaluates the JavaScript bundle now. A preload adds
+   *   work to the section of the caller, but the first React Native screen appears faster.
+   * @param onBundleLoaded An optional callback, with the rules of `startReactNative`.
+   */
+  @objc public func startReactNative(
+    launchOptions: [AnyHashable: Any]?,
+    preloadBundle: Bool,
+    onBundleLoaded: (() -> Void)?
+  ) {
+    #if canImport(Expo)
+    ExpoHostRuntime.shared.startReactNative(
+      launchOptions: launchOptions,
+      preloadBundle: preloadBundle,
+      onBundleLoaded: onBundleLoaded
+    )
+    #else
+    ReactNativeHostRuntime.shared.startReactNative(
+      launchOptions: launchOptions,
+      preloadBundle: preloadBundle,
+      onBundleLoaded: onBundleLoaded
+    )
+    #endif
+  }
+
   /**
    * Send a serialized JSON message to the React Native JS application.
    * The message is delivered as a `brownfieldMessage` DeviceEventEmitter event.