@callstack/react-native-brownfield 5.3.0 → 6.0.1

package/ios/Expo/ExpoUpdatesStartup.swift

@@ -0,0 +1,50 @@
+#if canImport(EXUpdates)
+import Foundation
+internal import EXUpdates
+
+final class ExpoUpdatesStartup: NSObject {
+  private var updatesReady = false
+  private var updatesCallbacks: [() -> Void] = []
+
+  // Updates belongs to the application lifetime, not to a view or React Host session.
+  // Inactive controllers (including DevLauncherAppController) must never be started here.
+  func prepareReactNative(_ completion: @escaping () -> Void) {
+    if !Thread.isMainThread {
+      DispatchQueue.main.async { [weak self] in self?.prepareReactNative(completion) }
+      return
+    }
+    AppController.initializeWithoutStarting()
+    let controller = AppController.sharedInstance
+    guard controller.isActiveController else { completion(); return }
+    // expo-updates 57 traps in launchAssetUrl() until start() sets its startup procedure.
+    if updatesReady || (controller.isStarted && controller.launchAssetUrl() != nil) {
+      completion()
+      return
+    }
+    updatesCallbacks.append(completion)
+    controller.delegate = self
+    if !controller.isStarted {
+      controller.start()
+    }
+  }
+
+  func cancelPendingRequests() { updatesCallbacks.removeAll() }
+}
+#endif
+
+#if canImport(EXUpdates)
+extension ExpoUpdatesStartup: AppControllerDelegate {
+  func appController(_ appController: any AppControllerInterface, didStartWithSuccess success: Bool) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      self.updatesReady = true
+      if !success {
+        NSLog("%@", "Expo Updates failed to select a launch asset; using the bundle resolver fallback.")
+      }
+      let callbacks = self.updatesCallbacks
+      self.updatesCallbacks.removeAll()
+      callbacks.forEach { $0() }
+    }
+  }
+}
+#endif

package/ios/JSBundleLoadObserver.swift

@@ -1,33 +1,39 @@
 import Foundation
 
 /**
- * Watches the `RCTInstanceDidLoadBundle` notification, and calls the callback that waits for it.
+ * Watches the Brownfield timing-ready 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 timing observer forwards React Native completion to the main thread after capturing
+ * timings. This class also delivers callbacks on the main thread for UI updates.
  *
  * 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 pendingCallback: (() -> Void)?
+  private var pendingCallback: ((JSBundleTimings) -> Void)?
   private var didLoadBundle = false
-  private var observerToken: NSObjectProtocol?
+  private var latestTimings: JSBundleTimings?
+  private var observerTokens: [NSObjectProtocol] = []
 
   init() {
-    observerToken = NotificationCenter.default.addObserver(
-      forName: NSNotification.Name("RCTInstanceDidLoadBundle"),
+    observerTokens.append(NotificationCenter.default.addObserver(
+      forName: .JSBundleTimingDidLoad,
       object: nil,
       queue: .main
     ) { [weak self] _ in
       self?.bundleDidLoad()
-    }
+    })
+    observerTokens.append(NotificationCenter.default.addObserver(
+      forName: NSNotification.Name("RCTJavaScriptDidFailToLoadNotification"),
+      object: nil,
+      queue: .main
+    ) { [weak self] _ in
+      self?.bundleDidFailToLoad()
+    })
   }
 
   deinit {
-    if let observerToken {
-      NotificationCenter.default.removeObserver(observerToken)
-    }
+    observerTokens.forEach(NotificationCenter.default.removeObserver)
   }
 
   /**
@@ -35,31 +41,37 @@ final class JSBundleLoadObserver {
    * 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.
+   * @param onBundleLoaded The class always calls this callback on the main thread, with the
+   *   timings of the session that loaded the bundle.
    */
-  func observe(onBundleLoaded: @escaping () -> Void) {
+  func observe(onBundleLoaded: @escaping (JSBundleTimings) -> 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.
+   * Removes the callback that waits, forgets the bundle of the earlier session, and clears stored
+   * JS bundle timings. Call this method when you stop React Native. A callback of the earlier
+   * session must not run in the next session, and the next session must not reuse the last timings.
    */
   func reset() {
     onMainThread { [weak self] in
       self?.pendingCallback = nil
       self?.didLoadBundle = false
+      self?.latestTimings = nil
+      JSBundleTimingObserver.reset()
     }
   }
 
   // MARK: - Main thread only
 
-  private func register(_ onBundleLoaded: @escaping () -> Void) {
+  private func register(_ onBundleLoaded: @escaping (JSBundleTimings) -> Void) {
     guard !didLoadBundle else {
-      DispatchQueue.main.async(execute: onBundleLoaded)
+      let timings = latestTimings ?? Self.snapshotTimings()
+      DispatchQueue.main.async {
+        onBundleLoaded(timings)
+      }
       return
     }
 
@@ -68,11 +80,36 @@ final class JSBundleLoadObserver {
 
   private func bundleDidLoad() {
     didLoadBundle = true
+    latestTimings = Self.snapshotTimings()
 
     let callback = pendingCallback
     pendingCallback = nil
 
-    callback?()
+    if let callback, let timings = latestTimings {
+      callback(timings)
+    }
+  }
+
+  /**
+   * A failed load, for example a reload in development, replaces the bundle that loaded earlier.
+   * Forget it and its timings, so a new callback waits for the next load. A callback that waits
+   * keeps waiting: it belongs to this session, and runs when a reload succeeds.
+   */
+  private func bundleDidFailToLoad() {
+    didLoadBundle = false
+    latestTimings = nil
+  }
+
+  /**
+   * The timing observer posts our notification only after storing the snapshot. This avoids
+   * depending on NotificationCenter observer ordering, including for late registrations.
+   */
+  private static func snapshotTimings() -> JSBundleTimings {
+    JSBundleTimings(
+      jsBundleLoadTime: JSBundleTimingObserver.jsBundleLoadTime,
+      jsBundleEvaluationTime: JSBundleTimingObserver.jsBundleEvaluationTime,
+      timeline: JSBundleTimingObserver.timeline
+    )
   }
 
   private func onMainThread(_ work: @escaping () -> Void) {

package/ios/JSBundleTimingObserver.h

@@ -0,0 +1,26 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Posted on main after the timing snapshot is ready.
+FOUNDATION_EXPORT NSNotificationName const JSBundleTimingDidLoadNotification;
+
+/**
+ * Captures JS bundle timings from `RCTPerformanceLogger` when React Native
+ * finishes (or fails) loading the bundle.
+ *
+ * The observer registers at binary load, before Swift host singletons run.
+ */
+@interface JSBundleTimingObserver : NSObject
+
+@property (class, nonatomic, readonly, nullable) NSNumber *jsBundleLoadTime;
+@property (class, nonatomic, readonly, nullable) NSNumber *jsBundleEvaluationTime;
+
+// Completed startup intervals, in monotonic milliseconds.
+@property (class, nonatomic, readonly) NSArray<NSDictionary<NSString *, id> *> *timeline;
+
++ (void)reset;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/JSBundleTimingObserver.m

@@ -0,0 +1,140 @@
+#import "JSBundleTimingObserver.h"
+
+#import <React/RCTBridge.h>
+#import <React/RCTConstants.h>
+#import <React/RCTPerformanceLogger.h>
+#import <React/RCTPLTag.h>
+#import <objc/runtime.h>
+
+static NSNumber *sJSBundleLoadTime;
+static NSNumber *sJSBundleEvaluationTime;
+static NSArray *sTimeline;
+
+static NSString *const kRCTInstanceDidLoadBundleNotification = @"RCTInstanceDidLoadBundle";
+
+NSNotificationName const JSBundleTimingDidLoadNotification = @"BrownfieldJSBundleTimingDidLoad";
+
+// Check the endpoints: a completed interval can round to zero milliseconds,
+// while an unfinished interval can produce a negative durationForTag: value.
+static NSNumber *JSBundleTimingNumberOrNil(NSArray<NSNumber *> *values, RCTPLTag tag)
+{
+  NSUInteger index = (NSUInteger)tag * 2;
+  if (values.count <= index + 1) {
+    return nil;
+  }
+  int64_t start = values[index].longLongValue;
+  int64_t stop = values[index + 1].longLongValue;
+  return start > 0 && stop >= start ? @(stop - start) : nil;
+}
+
+static void JSBundleTimingClearTagSnapshot(void)
+{
+  sJSBundleLoadTime = nil;
+  sJSBundleEvaluationTime = nil;
+  sTimeline = @[];
+}
+
+@implementation JSBundleTimingObserver
+
++ (NSNumber *)jsBundleLoadTime
+{
+  return sJSBundleLoadTime;
+}
+
++ (NSNumber *)jsBundleEvaluationTime
+{
+  return sJSBundleEvaluationTime;
+}
+
++ (NSArray *)timeline { return sTimeline ?: @[]; }
+
++ (void)reset
+{
+  if ([NSThread isMainThread]) {
+    JSBundleTimingClearTagSnapshot();
+  } else {
+    dispatch_async(dispatch_get_main_queue(), ^{
+      [self reset];
+    });
+  }
+}
+
++ (RCTPerformanceLogger *)performanceLoggerFromNotification:(NSNotification *)notification
+{
+  id bridge = notification.userInfo[@"bridge"];
+  RCTPerformanceLogger *logger = nil;
+
+  // RCTBridgeProxy inherits NSProxy's forwarding-based respondsToSelector:.
+  // It can report NO even for its synthesized performanceLogger getter. Inspect
+  // the actual class method table so we can safely call an implemented getter.
+  Class bridgeClass = object_getClass(bridge);
+  BOOL hasLoggerGetter = class_getInstanceMethod(bridgeClass, @selector(performanceLogger)) != NULL;
+  if (hasLoggerGetter) {
+    logger = [bridge performanceLogger];
+  }
+
+  return logger;
+}
+
++ (void)captureTimingsFromNotification:(NSNotification *)notification
+{
+  RCTPerformanceLogger *logger = [self performanceLoggerFromNotification:notification];
+  if (logger == nil) {
+    JSBundleTimingClearTagSnapshot();
+    return;
+  }
+
+  NSArray<NSNumber *> *values = [logger valuesForTags];
+  sJSBundleLoadTime = JSBundleTimingNumberOrNil(values, RCTPLScriptDownload);
+  sJSBundleEvaluationTime = JSBundleTimingNumberOrNil(values, RCTPLScriptExecution);
+  // These intervals can overlap. Preserve endpoints instead of adding durations.
+  RCTPLTag tags[] = {RCTPLScriptDownload, RCTPLScriptExecution};
+  NSArray *names = @[@"RCTPLScriptDownload", @"RCTPLScriptExecution"];
+  NSMutableArray *timeline = [NSMutableArray new];
+  for (NSUInteger i = 0; i < 2; i++) {
+    NSUInteger index = (NSUInteger)tags[i] * 2;
+    if (JSBundleTimingNumberOrNil(values, tags[i]) != nil) {
+      [timeline addObject:@{@"tag": names[i], @"startMs": values[index], @"stopMs": values[index + 1]}];
+    }
+  }
+  sTimeline = [timeline sortedArrayUsingDescriptors:@[[NSSortDescriptor sortDescriptorWithKey:@"startMs" ascending:YES]]];
+}
+
+@end
+
+__attribute__((constructor)) static void JSBundleTimingObserverRegister(void)
+{
+  NSNotificationCenter *center = [NSNotificationCenter defaultCenter];
+  NSOperationQueue *mainQueue = [NSOperationQueue mainQueue];
+
+  [center addObserverForName:RCTJavaScriptDidLoadNotification
+                      object:nil
+                       queue:mainQueue
+                  usingBlock:^(NSNotification *notification) {
+                    [JSBundleTimingObserver captureTimingsFromNotification:notification];
+                    [[NSNotificationCenter defaultCenter] postNotificationName:JSBundleTimingDidLoadNotification object:nil];
+                  }];
+
+  [center addObserverForName:kRCTInstanceDidLoadBundleNotification
+                      object:nil
+                       queue:mainQueue
+                  usingBlock:^(NSNotification *notification) {
+                    // RN versions that expose the instance logger on the bridge proxy
+                    // send RCTJavaScriptDidLoadNotification next, with that proxy.
+                    // currentBridge is a stub, and this earlier notification has no payload.
+                    Class proxyClass = NSClassFromString(@"RCTBridgeProxy");
+                    BOOL hasLoggerSetter = [proxyClass instancesRespondToSelector:NSSelectorFromString(@"setPerformanceLogger:")];
+                    if (hasLoggerSetter) {
+                      return;
+                    }
+                    [JSBundleTimingObserver captureTimingsFromNotification:notification];
+                    [[NSNotificationCenter defaultCenter] postNotificationName:JSBundleTimingDidLoadNotification object:nil];
+                  }];
+
+  [center addObserverForName:RCTJavaScriptDidFailToLoadNotification
+                      object:nil
+                       queue:mainQueue
+                  usingBlock:^(__unused NSNotification *notification) {
+                    [JSBundleTimingObserver reset];
+                  }];
+}

package/ios/ReactHostPreloading.swift

@@ -103,10 +103,14 @@ protocol ReactHostPreloading: AnyObject {
    */
   func canPreloadReactNative() -> Bool
 
+  func prepareReactNative(_ completion: @escaping () -> Void)
+
   func prepareDevLoadingView()
 }
 
 extension ReactHostPreloading {
+  func prepareReactNative(_ completion: @escaping () -> Void) { completion() }
+
   /**
    * The implementation of
    * `ReactNativeBrownfield.startReactNative(launchOptions:preloadBundle:onBundleLoaded:)`, which
@@ -115,7 +119,7 @@ extension ReactHostPreloading {
   func startReactNative(
     launchOptions: [AnyHashable: Any]?,
     preloadBundle: Bool,
-    onBundleLoaded: (() -> Void)?
+    onBundleLoaded: ((JSBundleTimings) -> Void)?
   ) {
     preloadState.storeLaunchOptions(launchOptions)
 
@@ -131,10 +135,10 @@ extension ReactHostPreloading {
     preloadState.requestPreload()
 
     if Thread.isMainThread {
-      createReactHost()
+      prepareReactNative { [weak self] in self?.createReactHost() }
     } else {
       DispatchQueue.main.async { [weak self] in
-        self?.createReactHost()
+        self?.prepareReactNative { [weak self] in self?.createReactHost() }
       }
     }
   }

package/ios/ReactNativeBrownfield.swift

@@ -4,6 +4,35 @@ import UIKit
 internal import Expo
 #endif
 
+/**
+ * JS bundle timings from React Native's performance logger.
+ *
+ * - `jsBundleLoadTime` is `RCTPLScriptDownload` (Metro HTTP in Debug, file read in Release).
+ * - `jsBundleEvaluationTime` is `RCTPLScriptExecution`.
+ *
+ * A tag field is `nil` when the tag never completed (failed load, logger missing, or
+ * bridgeless React Native below 0.87).
+ */
+@objc public class JSBundleTimings: NSObject {
+  @objc public let jsBundleLoadTime: NSNumber?
+  @objc public let jsBundleEvaluationTime: NSNumber?
+  @objc public let timeline: [[String: Any]]
+
+  @objc public init(jsBundleLoadTime: NSNumber?, jsBundleEvaluationTime: NSNumber?) {
+    self.timeline = []
+    self.jsBundleLoadTime = jsBundleLoadTime
+    self.jsBundleEvaluationTime = jsBundleEvaluationTime
+    super.init()
+  }
+
+  @objc public init(jsBundleLoadTime: NSNumber?, jsBundleEvaluationTime: NSNumber?, timeline: [[String: Any]]) {
+    self.jsBundleLoadTime = jsBundleLoadTime
+    self.jsBundleEvaluationTime = jsBundleEvaluationTime
+    self.timeline = timeline
+    super.init()
+  }
+}
+
 @objc public class ReactNativeBrownfield: NSObject {
   public static let shared = ReactNativeBrownfield()
 
@@ -100,6 +129,7 @@ internal import Expo
    * Stops React Native.
    */
   @objc public func stopReactNative() {
+    NotificationCenter.default.post(name: Notification.Name("BrownfieldPerformanceStop"), object: nil)
     #if canImport(Expo)
     ExpoHostRuntime.shared.stopReactNative()
     #else
@@ -112,19 +142,57 @@ internal import Expo
     initialProps: [AnyHashable: Any]?,
     launchOptions: [AnyHashable: Any]? = nil
   ) -> UIView? {
+    makeView(moduleName: moduleName, initialProps: initialProps, launchOptions: launchOptions,
+             session: nil, isHostVisible: nil)
+  }
+
+  /// Creates a measured presentation. The completion receives one immutable snapshot on main.
+  /// Opt in to wait for JS `markFullyDisplayed(brownfieldPresentationID)`.
+  /// Thread sampling requires both collectThreadMetrics and an onMetrics callback.
+  @objc public func view(
+    moduleName: String,
+    initialProps: [AnyHashable: Any]?,
+    launchOptions: [AnyHashable: Any]? = nil,
+    waitForFullDisplay: Bool = false,
+    collectThreadMetrics: Bool = false,
+    onMetrics: ((BrownfieldDisplayMetrics) -> Void)?
+  ) -> UIView? {
+    let session = BrownfieldDisplaySession(moduleName: moduleName,
+      waitForFullDisplay: waitForFullDisplay, collectThreadMetrics: collectThreadMetrics,
+      callback: onMetrics)
+    return makeView(moduleName: moduleName, initialProps: initialProps,
+                    launchOptions: launchOptions, session: session, isHostVisible: nil)
+  }
+
+  /// Only measured presentations get a session. Without one, `initialProps` pass through as is.
+  /// `isHostVisible` is set by `ReactNativeViewController`, which reports appearance itself.
+  internal func makeView(moduleName: String, initialProps: [AnyHashable: Any]?,
+                        launchOptions: [AnyHashable: Any]?, session: BrownfieldDisplaySession?,
+                        isHostVisible: (() -> Bool)?) -> UIView? {
+    var props = initialProps
+    if let session {
+      props = (props ?? [:]).merging(["brownfieldPresentationID": session.id]) { $1 }
+    }
+    // The probe goes into the React Native root, not into a placeholder, so initial display
+    // can't complete before the root exists.
+    let attachProbe: (UIView?) -> Void = { rootView in
+      guard let session else { return }
+      guard let rootView else { session.cancel(); return }
+      let probe = BrownfieldAppearanceProbe(session: session)
+      probe.isHostVisible = isHostVisible
+      session.hasRootView = true
+      rootView.addSubview(probe)
+    }
     #if canImport(Expo)
-    ExpoHostRuntime.shared.view(
-      moduleName: moduleName,
-      initialProps: initialProps,
-      launchOptions: launchOptions
-    )
+    let view = ExpoHostRuntime.shared.view(moduleName: moduleName, initialProps: props,
+                                           launchOptions: launchOptions, onRootView: attachProbe)
     #else
-    ReactNativeHostRuntime.shared.view(
-      moduleName: moduleName,
-      initialProps: initialProps,
-      launchOptions: launchOptions
-    )
+    let view = ReactNativeHostRuntime.shared.view(moduleName: moduleName, initialProps: props,
+                                                  launchOptions: launchOptions)
+    attachProbe(view)
     #endif
+    if view == nil { session?.cancel() }
+    return view
   }
 
   /**
@@ -193,10 +261,10 @@ internal import Expo
    * Starts React Native with optional callback when bundle is 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.
+   *   fully loaded. It receives `JSBundleTimings`. 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)?) {
+  @objc public func startReactNative(onBundleLoaded: ((JSBundleTimings) -> Void)?) {
     #if canImport(Expo)
     ExpoHostRuntime.shared.startReactNative(onBundleLoaded: onBundleLoaded)
     #else
@@ -220,7 +288,7 @@ internal import Expo
   @objc public func startReactNative(
     launchOptions: [AnyHashable: Any]?,
     preloadBundle: Bool,
-    onBundleLoaded: (() -> Void)?
+    onBundleLoaded: ((JSBundleTimings) -> Void)?
   ) {
     #if canImport(Expo)
     ExpoHostRuntime.shared.startReactNative(

package/ios/ReactNativeBrownfield.xcodeproj/project.pbxproj

@@ -17,6 +17,9 @@
 		79FEE77E2FB499E400E407DE /* ReactNativeViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 79FEE77C2FB499E400E407DE /* ReactNativeViewController.swift */; };
 		79FEE7802FB499EC00E407DE /* ReactNativeHostRuntime.swift in Sources */ = {isa = PBXBuildFile; fileRef = 79FEE77F2FB499EC00E407DE /* ReactNativeHostRuntime.swift */; };
 		79FEE7822FB499F300E407DE /* ExpoHostRuntime.swift in Sources */ = {isa = PBXBuildFile; fileRef = 79FEE7812FB499F300E407DE /* ExpoHostRuntime.swift */; };
+		79FEE7852FB500A100E407DE /* JSBundleTimingObserver.m in Sources */ = {isa = PBXBuildFile; fileRef = 79FEE7842FB500A100E407DE /* JSBundleTimingObserver.m */; };
+		BEAF10000000000000000000 /* BrownfieldDisplayMetrics.swift in Sources */ = {isa = PBXBuildFile; fileRef = BEAF00000000000000000000 /* BrownfieldDisplayMetrics.swift */; };
+		BEAF10000000000000000002 /* BrownfieldPerformanceBridge.mm in Sources */ = {isa = PBXBuildFile; fileRef = BEAF00000000000000000002 /* BrownfieldPerformanceBridge.mm */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXCopyFilesBuildPhase section */
@@ -44,6 +47,11 @@
 		79FEE77C2FB499E400E407DE /* ReactNativeViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReactNativeViewController.swift; sourceTree = "<group>"; };
 		79FEE77F2FB499EC00E407DE /* ReactNativeHostRuntime.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReactNativeHostRuntime.swift; sourceTree = "<group>"; };
 		79FEE7812FB499F300E407DE /* ExpoHostRuntime.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ExpoHostRuntime.swift; sourceTree = "<group>"; };
+		79FEE7832FB500A100E407DE /* JSBundleTimingObserver.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = JSBundleTimingObserver.h; sourceTree = "<group>"; };
+		79FEE7842FB500A100E407DE /* JSBundleTimingObserver.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = JSBundleTimingObserver.m; sourceTree = "<group>"; };
+		BEAF00000000000000000000 /* BrownfieldDisplayMetrics.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BrownfieldDisplayMetrics.swift; sourceTree = "<group>"; };
+		BEAF00000000000000000001 /* BrownfieldPerformanceBridge.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = BrownfieldPerformanceBridge.h; sourceTree = "<group>"; };
+		BEAF00000000000000000002 /* BrownfieldPerformanceBridge.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; path = BrownfieldPerformanceBridge.mm; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -65,7 +73,12 @@
 				79FEE7692FB4997100E407DE /* Expo */,
 				696CB22A230EF910000207AF /* Products */,
 				79FEE76D2FB499C700E407DE /* BrownfieldBundlePathResolver.swift */,
+				BEAF00000000000000000000 /* BrownfieldDisplayMetrics.swift */,
+				BEAF00000000000000000001 /* BrownfieldPerformanceBridge.h */,
+				BEAF00000000000000000002 /* BrownfieldPerformanceBridge.mm */,
 				79FEE76E2FB499C700E407DE /* JSBundleLoadObserver.swift */,
+				79FEE7832FB500A100E407DE /* JSBundleTimingObserver.h */,
+				79FEE7842FB500A100E407DE /* JSBundleTimingObserver.m */,
 				79FEE76F2FB499C700E407DE /* Notification+Brownfield.swift */,
 				79FEE7702FB499C700E407DE /* ReactNativeBrownfield.swift */,
 				79FEE7712FB499C700E407DE /* ReactNativeBrownfieldModule.h */,
@@ -170,7 +183,10 @@
 				79FEE7762FB499C700E407DE /* Notification+Brownfield.swift in Sources */,
 				79FEE7822FB499F300E407DE /* ExpoHostRuntime.swift in Sources */,
 				79FEE7772FB499C700E407DE /* ReactNativeBrownfieldModule.swift in Sources */,
+				BEAF10000000000000000000 /* BrownfieldDisplayMetrics.swift in Sources */,
+				BEAF10000000000000000002 /* BrownfieldPerformanceBridge.mm in Sources */,
 				79FEE7782FB499C700E407DE /* JSBundleLoadObserver.swift in Sources */,
+				79FEE7852FB500A100E407DE /* JSBundleTimingObserver.m in Sources */,
 				79FEE7792FB499C700E407DE /* ReactNativeBrownfield.swift in Sources */,
 				79FEE77D2FB499E400E407DE /* ReactNativeView.swift in Sources */,
 				79FEE77E2FB499E400E407DE /* ReactNativeViewController.swift in Sources */,

package/ios/Vanilla/ReactNativeHostRuntime.swift

@@ -191,7 +191,7 @@ final class ReactNativeHostRuntime {
    *
    * @param onBundleLoaded Optional callback invoked on the main thread after JS bundle is fully loaded.
    */
-  public func startReactNative(onBundleLoaded: (() -> Void)?) {
+  public func startReactNative(onBundleLoaded: ((JSBundleTimings) -> 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 {

package/ios/Views/ReactNativeView.swift

@@ -17,11 +17,17 @@ struct ReactNativeViewRepresentable: UIViewControllerRepresentable {
   var moduleName: String
   var initialProperties: [String: Any] = [:]
   var host: BrownfieldSurfaceHost
+  var waitForFullDisplay = false
+  var collectThreadMetrics = false
+  var onMetrics: ((BrownfieldDisplayMetrics) -> Void)?
 
   func makeUIViewController(context: Context) -> UIViewController {
     let controller = ReactNativeViewController(
       moduleName: moduleName,
-      initialProperties: initialProperties
+      initialProperties: initialProperties,
+      waitForFullDisplay: waitForFullDisplay,
+      collectThreadMetrics: collectThreadMetrics,
+      onMetrics: onMetrics
     )
     controller.isHostedBySwiftUI = true
     host.controller = controller
@@ -45,17 +51,29 @@ public struct ReactNativeView: View {
   @State private var host = BrownfieldSurfaceHost()
   var moduleName: String
   var initialProperties: [String: Any] = [:]
+  var waitForFullDisplay = false
+  var collectThreadMetrics = false
+  var onMetrics: ((BrownfieldDisplayMetrics) -> Void)?
 
-  public init(moduleName: String, initialProperties: [String : Any] = [:]) {
+  public init(moduleName: String, initialProperties: [String : Any] = [:],
+              waitForFullDisplay: Bool = false,
+              collectThreadMetrics: Bool = false,
+              onMetrics: ((BrownfieldDisplayMetrics) -> Void)? = nil) {
     self.moduleName = moduleName
     self.initialProperties = initialProperties
+    self.waitForFullDisplay = waitForFullDisplay
+    self.collectThreadMetrics = collectThreadMetrics
+    self.onMetrics = onMetrics
   }
 
   public var body: some View {
     ReactNativeViewRepresentable(
       moduleName: moduleName,
       initialProperties: initialProperties,
-      host: host
+      host: host,
+      waitForFullDisplay: waitForFullDisplay,
+      collectThreadMetrics: collectThreadMetrics,
+      onMetrics: onMetrics
     )
     .ignoresSafeArea(.all)
     // `.popToNative` is public API and may be posted from any thread, while