@callstack/react-native-brownfield 5.3.0 → 6.0.0

package/android/src/main/java/com/callstack/reactnativebrownfield/ReactNativeFragment.kt

@@ -17,6 +17,10 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
     private lateinit var permissionsCallback: Callback
     private var permissionListener: PermissionListener? = null
     private lateinit var moduleName: String
+    private var displaySession: BrownfieldDisplaySession? = null
+
+    /** Reattach after Fragment restoration; callbacks are intentionally not serialized. */
+    var onMetrics: OnDisplayMetrics? = null
 
     override fun onCreate(savedInstanceState: Bundle?) {
         /**
@@ -51,12 +55,34 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
         container: ViewGroup?,
         savedInstanceState: Bundle?
     ): View {
-        return ReactNativeBrownfield.shared.createView(
+        val args = arguments
+        // Only the measured factories set this argument. Plain fragments keep their props as is.
+        val isMeasured = args?.containsKey(ReactNativeFragmentArgNames.ARG_WAIT_FOR_FULL_DISPLAY) == true
+        val session = if (isMeasured) {
+            BrownfieldDisplaySession(
+                moduleName,
+                args!!.getBoolean(ReactNativeFragmentArgNames.ARG_WAIT_FOR_FULL_DISPLAY, false),
+                args.getBoolean(ReactNativeFragmentArgNames.ARG_COLLECT_THREAD_METRICS, false),
+                onMetrics
+            )
+        } else {
+            null
+        }
+        displaySession = session
+        val launchOptions = Bundle(
+            args?.getBundle(ReactNativeFragmentArgNames.ARG_LAUNCH_OPTIONS) ?: Bundle()
+        ).apply { session?.let { putString("brownfieldPresentationID", it.id) } }
+        this.reactDelegate = ReactDelegateWrapper(
+            activity, this.reactHost, moduleName, launchOptions
+        )
+        return ReactNativeBrownfield.shared.createViewInternal(
             activity,
             moduleName,
             this.reactDelegate as ReactDelegateWrapper,
-            launchOptions = null,
-            lifecycleOwner = viewLifecycleOwner
+            launchOptions,
+            viewLifecycleOwner,
+            session,
+            true
         )
     }
 
@@ -69,9 +95,11 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
         } catch (_: ClassCastException) {
             (this.reactDelegate as ReactDelegateWrapper).onReactHostResume()
         }
+        displaySession?.setResumed(true)
     }
 
     override fun onPause() {
+        displaySession?.cancel()
         try {
             super.onPause()
         } catch (error: AssertionError) {
@@ -91,6 +119,12 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
         }
     }
 
+    override fun onDestroyView() {
+        displaySession?.cancel()
+        displaySession = null
+        super.onDestroyView()
+    }
+
     override fun onRequestPermissionsResult(
         requestCode: Int,
         permissions: Array<String>,
@@ -143,6 +177,26 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
             return fragment
         }
 
+        @JvmStatic
+        @JvmOverloads
+        fun createReactNativeFragment(
+            moduleName: String,
+            initialProps: Bundle?,
+            waitForFullDisplay: Boolean,
+            collectThreadMetrics: Boolean = false,
+            onMetrics: OnDisplayMetrics? = null
+        ): ReactNativeFragment {
+            return createReactNativeFragment(moduleName, initialProps).also { fragment ->
+                fragment.arguments?.putBoolean(
+                    ReactNativeFragmentArgNames.ARG_WAIT_FOR_FULL_DISPLAY, waitForFullDisplay
+                )
+                fragment.arguments?.putBoolean(
+                    ReactNativeFragmentArgNames.ARG_COLLECT_THREAD_METRICS, collectThreadMetrics
+                )
+                fragment.onMetrics = onMetrics
+            }
+        }
+
         @JvmStatic
         fun createReactNativeFragment(
             moduleName: String,
@@ -151,6 +205,22 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
             return createReactNativeFragment(moduleName, PropsBundle.fromHashMap(initialProps))
         }
 
+        @JvmStatic
+        @JvmOverloads
+        fun createReactNativeFragment(
+            moduleName: String,
+            initialProps: HashMap<String, *>,
+            waitForFullDisplay: Boolean,
+            collectThreadMetrics: Boolean = false,
+            onMetrics: OnDisplayMetrics? = null
+        ): ReactNativeFragment = createReactNativeFragment(
+            moduleName,
+            PropsBundle.fromHashMap(initialProps),
+            waitForFullDisplay,
+            collectThreadMetrics,
+            onMetrics
+        )
+
         @JvmStatic
         fun createReactNativeFragment(
             moduleName: String,
@@ -158,5 +228,21 @@ class ReactNativeFragment : ReactFragment(), PermissionAwareActivity {
         ): ReactNativeFragment {
             return createReactNativeFragment(moduleName, initialProps.toHashMap())
         }
+
+        @JvmStatic
+        @JvmOverloads
+        fun createReactNativeFragment(
+            moduleName: String,
+            initialProps: WritableMap,
+            waitForFullDisplay: Boolean,
+            collectThreadMetrics: Boolean = false,
+            onMetrics: OnDisplayMetrics? = null
+        ): ReactNativeFragment = createReactNativeFragment(
+            moduleName,
+            initialProps.toHashMap(),
+            waitForFullDisplay,
+            collectThreadMetrics,
+            onMetrics
+        )
     }
 }

package/android/src/main/java/com/callstack/reactnativebrownfield/constants/ReactNativeFragmentArgNames.kt

@@ -16,5 +16,7 @@ class ReactNativeFragmentArgNames private constructor() :
 
         // re-export constants from ReactFragment to enable access
         const val ARG_LAUNCH_OPTIONS: String = "arg_launch_options"
+        const val ARG_WAIT_FOR_FULL_DISPLAY = "arg_wait_for_full_display"
+        const val ARG_COLLECT_THREAD_METRICS = "arg_collect_thread_metrics"
     }
 }

package/android/src/test/java/com/callstack/reactnativebrownfield/PerformanceMetricsTest.kt

@@ -0,0 +1,54 @@
+package com.callstack.reactnativebrownfield
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class PerformanceMetricsTest {
+    @Test fun `pairs markers and sorts overlapping timeline`() {
+        val samples = JSBundleTimingAccumulator()
+        samples.record(BundleMarker.EVALUATION_START, 1, 20)
+        samples.record(BundleMarker.DOWNLOAD_START, 0, 10)
+        samples.record(BundleMarker.EVALUATION_END, 1, 40)
+        samples.record(BundleMarker.DOWNLOAD_END, 0, 30)
+
+        val result = samples.snapshot()
+        assertEquals(20.0, result.jsBundleLoadTime!!, 0.0)
+        assertEquals(20.0, result.jsBundleEvaluationTime!!, 0.0)
+        assertEquals(listOf("DOWNLOAD", "RUN_JS_BUNDLE"), result.timeline.map { it["tag"] })
+    }
+
+    @Test fun `keeps zero duration and rejects missing ambiguous and other instances`() {
+        val zero = JSBundleTimingAccumulator().apply {
+            record(BundleMarker.EVALUATION_START, 1, 5)
+            record(BundleMarker.EVALUATION_END, 1, 5)
+        }.snapshot()
+        assertEquals(0.0, zero.jsBundleEvaluationTime!!, 0.0)
+
+        val missing = JSBundleTimingAccumulator().apply {
+            record(BundleMarker.DOWNLOAD_END, 0, 8)
+            record(BundleMarker.EVALUATION_START, 2, 9)
+            record(BundleMarker.EVALUATION_END, 2, 10)
+        }.snapshot()
+        assertNull(missing.jsBundleLoadTime)
+        assertNull(missing.jsBundleEvaluationTime)
+
+        val ambiguous = JSBundleTimingAccumulator().apply {
+            record(BundleMarker.DOWNLOAD_START, 0, 1)
+            record(BundleMarker.DOWNLOAD_START, 0, 2)
+            record(BundleMarker.DOWNLOAD_END, 0, 3)
+        }.snapshot()
+        assertNull(ambiguous.jsBundleLoadTime)
+    }
+
+    @Test fun `frame accumulator includes unfinished deadline excess`() {
+        val samples = BrownfieldFrameSamples()
+        samples.begin(0)
+        samples.record(20_000_000, 10_000_000)
+        val result = samples.snapshot(50_000_000)
+        assertEquals(20.0, result.fps!!, 0.001)
+        assertEquals(0.6, result.busyRatio!!, 0.001)
+        assertEquals(50.0, result.sampledMs, 0.001)
+        assertEquals(1, result.frameCount)
+    }
+}

package/gradle-plugin/brownfield/src/main/kotlin/com/callstack/react/brownfield/plugin/RNSourceSets.kt

@@ -3,13 +3,16 @@ package com.callstack.react.brownfield.plugin
 import com.android.build.api.dsl.AndroidSourceSet
 import com.android.build.api.dsl.LibraryExtension
 import com.android.build.api.variant.LibraryAndroidComponentsExtension
+import com.android.build.api.variant.SourceDirectories
 import com.callstack.react.brownfield.exceptions.NameSpaceNotFound
 import com.callstack.react.brownfield.processors.VariantHelper
 import com.callstack.react.brownfield.utils.Extension
 import com.callstack.react.brownfield.utils.Utils
 import com.callstack.react.brownfield.utils.capitalized
+import org.gradle.api.GradleException
 import org.gradle.api.Project
 import org.gradle.api.Task
+import org.gradle.api.file.DirectoryProperty
 import org.gradle.api.tasks.Copy
 import java.io.File
 
@@ -63,26 +66,67 @@ object RNSourceSets {
             val capitalizedBundledAssetsVariantName = bundledAssetsVariantName.capitalized()
             val appProject = getAppProject()
 
-            val bundlePathSegments =
-                listOf(
-                    // outputs for RN <= 0.81
-                    "createBundle${capitalizedBundledAssetsVariantName}JsAndAssets",
-                    // outputs for RN >= 0.82
-                    "react/$bundledAssetsVariantName",
-                )
+            val jsBundleTaskName = "createBundle${capitalizedBundledAssetsVariantName}JsAndAssets"
 
-            val appBuildDir = getAppBuildDir()
-            bundlePathSegments.forEach { segment ->
-                variant.sources.assets?.addStaticSourceDirectory("$appBuildDir/generated/assets/$segment")
-                variant.sources.res?.addStaticSourceDirectory("$appBuildDir/generated/res/$segment")
-            }
+            /**
+             * Wire the bundle task's own `jsBundleDir`/`resourcesDir` outputs as *generated*
+             * source directories
+             */
+            wireGeneratedSourceDirectory(appProject, jsBundleTaskName, "getJsBundleDir", variant.sources.assets)
+            wireGeneratedSourceDirectory(appProject, jsBundleTaskName, "getResourcesDir", variant.sources.res)
 
             if (Utils.hasExpoUpdates(appProject, variantName)) {
-                val updateResourcesPathSegment = VariantHelper.getExpoUpdatesResourcesTaskName(variant.name)
-                variant.sources.assets?.addStaticSourceDirectory("$appBuildDir/generated/assets/$updateResourcesPathSegment")
-                variant.sources.res?.addStaticSourceDirectory("$appBuildDir/generated/res/$updateResourcesPathSegment")
+                /**
+                 * expo-updates registers `create<Variant>UpdatesResources` as
+                 * `ExpoUpdatesPlugin.CreateUpdatesResourcesTask`, with a single
+                 * `assetDir: DirectoryProperty` output (no `res` output exists for this task).
+                 */
+                val updatesResourcesTaskName = VariantHelper.getExpoUpdatesResourcesTaskName(variant.name)
+                wireGeneratedSourceDirectory(appProject, updatesResourcesTaskName, "getAssetDir", variant.sources.assets)
+            }
+        }
+    }
+
+    /**
+     * Wires `taskName`'s `getterName` output (expected to be a `DirectoryProperty`) as a
+     * generated source directory for `sources`.
+     *
+     * Resolving the task by name (rather than importing its class) keeps this plugin from
+     * depending on RNGP's/expo-updates' internal task types. If the task, or its expected output
+     * property, isn't there, this fails the build immediately with a clear message instead of
+     * silently producing an empty/stale source directory.
+     */
+    private fun wireGeneratedSourceDirectory(
+        appProject: Project,
+        taskName: String,
+        getterName: String,
+        sources: SourceDirectories?,
+    ) {
+        if (sources == null) return
+
+        val task =
+            appProject.tasks.findByName(taskName)
+                ?: throw GradleException(
+                    "brownfield: expected task '$taskName' was not found in project " +
+                        "'${appProject.path}'. Check that the plugin producing it is applied there.",
+                )
+
+        val getter =
+            runCatching { task.javaClass.getMethod(getterName) }.getOrElse {
+                throw GradleException(
+                    "brownfield: task '$taskName' (${task.javaClass.name}) does not expose " +
+                        "'$getterName()'. The plugin that registers it most likely changed its " +
+                        "API; the brownfield Gradle plugin needs updating to match.",
+                    it,
+                )
             }
+
+        check(DirectoryProperty::class.java.isAssignableFrom(getter.returnType)) {
+            "brownfield: '$taskName.$getterName()' no longer returns a DirectoryProperty."
         }
+
+        val taskProvider = appProject.tasks.named(taskName)
+        sources.addGeneratedSourceDirectory(taskProvider) { t -> getter.invoke(t) as DirectoryProperty }
     }
 
     private fun getLibraryNameSpace(): String {

package/gradle-plugin/brownfield/src/test/kotlin/com/callstack/react/brownfield/plugin/AgpCompatibilityMatrixTest.kt

@@ -102,9 +102,10 @@ class AgpCompatibilityMatrixTest {
         File(projectDir, "local.properties").writeText("sdk.dir=$androidSdk\n")
         // Stands in for the RN app project. It has to be a real `com.android.application` because
         // the brownfield plugin wires into AGP's own app-side tasks; the extra registrations cover
-        // the tasks the React Native Gradle plugin would otherwise contribute. Empty registrations
-        // are enough: this test is about AGP API compatibility, not about what those tasks produce.
-        File(projectDir, "app").mkdirs()
+        // the tasks the React Native Gradle plugin would otherwise contribute. The bundle tasks need
+        // their `jsBundleDir`/`resourcesDir` outputs, which the plugin wires as generated sources;
+        // the rest can stay empty, since this test is about AGP API compatibility.
+        writeRNBundleTaskStubs(File(projectDir, "app").apply { mkdirs() })
         File(projectDir, "app/build.gradle.kts").writeText(
             """
             plugins {
@@ -116,11 +117,8 @@ class AgpCompatibilityMatrixTest {
                 compileSdk = 34
             }
 
-            listOf(
-                "generateAutolinkingPackageList",
-                "createBundleDebugJsAndAssets",
-                "createBundleReleaseJsAndAssets",
-            ).forEach { name -> tasks.register(name) }
+            tasks.register("generateAutolinkingPackageList")
+            apply(from = "$RN_BUNDLE_TASK_STUBS_SCRIPT")
             """.trimIndent(),
         )
 

package/gradle-plugin/brownfield/src/test/kotlin/com/callstack/react/brownfield/plugin/LegacyConsumerConfigurationTest.kt

@@ -64,10 +64,12 @@ class LegacyConsumerConfigurationTest {
             """.trimIndent(),
         )
         File(projectDir, "local.properties").writeText("sdk.dir=$androidSdk\n")
-        // ArtifactsResolver looks for an `app` project; an empty stub is enough, this test is about
-        // the task container, not discovery.
-        File(projectDir, "app").mkdirs()
-        File(projectDir, "app/build.gradle.kts").writeText("")
+        // ArtifactsResolver looks for an `app` project. It only needs the RN bundle tasks whose
+        // outputs the plugin wires as generated sources; this test is about the task container,
+        // not discovery.
+        val appDir = File(projectDir, "app").apply { mkdirs() }
+        writeRNBundleTaskStubs(appDir)
+        File(appDir, "build.gradle.kts").writeText("apply(from = \"$RN_BUNDLE_TASK_STUBS_SCRIPT\")\n")
 
         // The `tasks.register("removeDependenciesFromModuleFile")` block below is verbatim from
         // the published setup docs. Do not "modernize" it — its whole purpose is to reproduce

package/gradle-plugin/brownfield/src/test/kotlin/com/callstack/react/brownfield/plugin/RNBundleTaskStubs.kt

@@ -0,0 +1,27 @@
+package com.callstack.react.brownfield.plugin
+
+import java.io.File
+
+internal const val RN_BUNDLE_TASK_STUBS_SCRIPT = "rn-bundle-task-stubs.gradle.kts"
+
+/**
+ * Writes a script plugin into [appDir] that stubs RNGP's `createBundle<Variant>JsAndAssets` tasks.
+ * The brownfield plugin wires their `jsBundleDir`/`resourcesDir` outputs as generated sources and
+ * fails fast when they are missing, so plain `tasks.register(name)` stubs are not enough.
+ * Apply it from the app build script with `apply(from = RN_BUNDLE_TASK_STUBS_SCRIPT)`.
+ */
+internal fun writeRNBundleTaskStubs(appDir: File) {
+    File(appDir, RN_BUNDLE_TASK_STUBS_SCRIPT).writeText(
+        """
+        abstract class StubBundleTask : DefaultTask() {
+            @get:OutputDirectory abstract val jsBundleDir: DirectoryProperty
+            @get:OutputDirectory abstract val resourcesDir: DirectoryProperty
+        }
+
+        listOf(
+            "createBundleDebugJsAndAssets",
+            "createBundleReleaseJsAndAssets",
+        ).forEach { name -> tasks.register<StubBundleTask>(name) }
+        """.trimIndent(),
+    )
+}

package/ios/BrownfieldDisplayMetrics.swift

@@ -0,0 +1,265 @@
+import UIKit
+
+/// Frame cadence, not CPU utilization. A missing sampler produces nil FPS/busyRatio.
+@objcMembers public final class BrownfieldThreadMetrics: NSObject {
+  public let fps: NSNumber?
+  public let busyRatio: NSNumber?
+  public let sampledMs: Double
+  public let frameCount: Int
+
+  internal init(fps: Double?, busyRatio: Double?, sampledMs: Double, frameCount: Int) {
+    self.fps = fps.map { NSNumber(value: $0) }
+    self.busyRatio = busyRatio.map { NSNumber(value: $0) }
+    self.sampledMs = sampledMs
+    self.frameCount = frameCount
+  }
+}
+
+@objcMembers public final class BrownfieldDisplayInterval: NSObject {
+  public let duration: Double
+  public let jsThread: BrownfieldThreadMetrics
+  public let uiThread: BrownfieldThreadMetrics
+
+  internal init(duration: Double, jsThread: BrownfieldThreadMetrics, uiThread: BrownfieldThreadMetrics) {
+    self.duration = duration
+    self.jsThread = jsThread
+    self.uiThread = uiThread
+  }
+}
+
+/// An immutable completed snapshot, delivered once through onMetrics.
+@objcMembers public final class BrownfieldDisplayMetrics: NSObject {
+  public let presentationID: String
+  public let moduleName: String
+  public let initialDisplay: BrownfieldDisplayInterval?
+  public let fullDisplay: BrownfieldDisplayInterval?
+  public let isFinal: Bool
+  public let isCancelled: Bool
+
+  internal init(presentationID: String, moduleName: String, initialDisplay: BrownfieldDisplayInterval?,
+                fullDisplay: BrownfieldDisplayInterval?, isFinal: Bool, isCancelled: Bool = false) {
+    self.presentationID = presentationID
+    self.moduleName = moduleName
+    self.initialDisplay = initialDisplay
+    self.fullDisplay = fullDisplay
+    self.isFinal = isFinal
+    self.isCancelled = isCancelled
+  }
+}
+
+/// Pure cadence accumulator, kept separate from run-loop and locking mechanics.
+internal struct BrownfieldFrameSamples {
+  var start: CFTimeInterval?
+  var last: CFTimeInterval = 0
+  var budget: CFTimeInterval = 1 / 60
+  var frames = 0
+  var busy: CFTimeInterval = 0
+
+  mutating func begin(at now: CFTimeInterval) {
+    start = now
+    last = now
+  }
+
+  mutating func record(at now: CFTimeInterval, frameInterval: CFTimeInterval) {
+    budget = max(frameInterval, 1 / 240)
+    busy += max(0, now - last - budget)
+    frames += 1
+    last = now
+  }
+
+  func snapshot(at now: CFTimeInterval) -> BrownfieldThreadMetrics {
+    guard let start, now > start else {
+      return BrownfieldThreadMetrics(fps: nil, busyRatio: nil, sampledMs: 0, frameCount: 0)
+    }
+    let elapsed = now - start
+    let blocked = busy + max(0, now - last - budget)
+    return BrownfieldThreadMetrics(fps: Double(frames) / elapsed,
+      busyRatio: min(1, blocked / elapsed), sampledMs: elapsed * 1000, frameCount: frames)
+  }
+}
+
+/// Lock protects the JS run-loop sampler from main-thread snapshots and cancellation.
+internal final class BrownfieldFrameSampler: NSObject {
+  private let lock = NSLock()
+  private var link: CADisplayLink?
+  private var stopped = false
+  private var samples = BrownfieldFrameSamples()
+
+  func startOnCurrentRunLoop() {
+    lock.lock()
+    defer { lock.unlock() }
+    guard !stopped, link == nil else { return }
+    samples.begin(at: CACurrentMediaTime())
+    let link = CADisplayLink(target: self, selector: #selector(tick(_:)))
+    self.link = link
+    link.add(to: .current, forMode: .common)
+  }
+
+  @objc private func tick(_ link: CADisplayLink) {
+    lock.lock()
+    defer { lock.unlock() }
+    guard !stopped else { return }
+    samples.record(at: CACurrentMediaTime(), frameInterval: link.targetTimestamp - link.timestamp)
+  }
+
+  func snapshot(at now: CFTimeInterval) -> BrownfieldThreadMetrics {
+    lock.lock()
+    defer { lock.unlock() }
+    return samples.snapshot(at: now)
+  }
+
+  func stop() {
+    lock.lock()
+    stopped = true
+    let oldLink = link
+    link = nil
+    lock.unlock()
+    oldLink?.invalidate()
+  }
+}
+
+/// All session state belongs to the main thread. The JS sampler alone crosses threads.
+internal final class BrownfieldDisplaySession {
+  let id = UUID().uuidString
+  let moduleName: String
+  private let waitForFullDisplay: Bool
+  private var callback: ((BrownfieldDisplayMetrics) -> Void)?
+  private let start = CACurrentMediaTime()
+  private let ui: BrownfieldFrameSampler?
+  private let js: BrownfieldFrameSampler?
+  private var initial: BrownfieldDisplayInterval?
+  private var fullWasMarked = false
+  private var finished = false
+  private var jsScheduled = false
+  private var tokens: [NSObjectProtocol] = []
+  /// Set once the appearance probe is inside the React Native root view.
+  var hasRootView = false
+
+  init(moduleName: String, waitForFullDisplay: Bool, collectThreadMetrics: Bool = false, callback: ((BrownfieldDisplayMetrics) -> Void)?) {
+    precondition(Thread.isMainThread)
+    self.moduleName = moduleName
+    self.waitForFullDisplay = waitForFullDisplay
+    self.callback = callback
+    let shouldSample = collectThreadMetrics && callback != nil
+    ui = shouldSample ? BrownfieldFrameSampler() : nil
+    js = shouldSample ? BrownfieldFrameSampler() : nil
+    guard callback != nil else {
+      finished = true
+      return
+    }
+    ui?.startOnCurrentRunLoop()
+    scheduleJS()
+    if js != nil {
+      tokens.append(NotificationCenter.default.addObserver(
+        forName: Notification.Name("BrownfieldPerformanceBridgeReady"), object: nil, queue: .main
+      ) { [weak self] _ in
+        guard let self else { return }
+        if self.jsScheduled { self.cancel() } else { self.scheduleJS() }
+      })
+    }
+    if waitForFullDisplay {
+      tokens.append(NotificationCenter.default.addObserver(
+        forName: Notification.Name("BrownfieldMarkFullyDisplayed"), object: nil, queue: .main
+      ) { [weak self] notification in
+        guard let self, notification.object as? String == self.id, !self.finished else { return }
+        self.fullWasMarked = true
+        if self.initial != nil { self.complete() }
+      })
+    }
+    // Cancellation releases samplers when the application stops drawing.
+    tokens.append(NotificationCenter.default.addObserver(
+      forName: UIApplication.didEnterBackgroundNotification, object: nil, queue: .main
+    ) { [weak self] _ in self?.cancel() })
+    tokens.append(NotificationCenter.default.addObserver(
+      forName: Notification.Name("RCTJavaScriptDidFailToLoadNotification"), object: nil, queue: .main
+    ) { [weak self] _ in self?.cancel() })
+    tokens.append(NotificationCenter.default.addObserver(
+      forName: Notification.Name("BrownfieldPerformanceStop"), object: nil, queue: .main
+    ) { [weak self] _ in self?.cancel() })
+  }
+
+  private func scheduleJS() {
+    guard !finished, !jsScheduled, let sampler = js else { return }
+    jsScheduled = BrownfieldPerformanceBridge.dispatch(toJavaScript: {
+      sampler.startOnCurrentRunLoop()
+    })
+  }
+
+  private func interval() -> BrownfieldDisplayInterval {
+    let now = CACurrentMediaTime()
+    return BrownfieldDisplayInterval(duration: (now - start) * 1000,
+      jsThread: js?.snapshot(at: now) ?? BrownfieldFrameSamples().snapshot(at: now),
+      uiThread: ui?.snapshot(at: now) ?? BrownfieldFrameSamples().snapshot(at: now))
+  }
+
+  func appeared() {
+    guard !finished, initial == nil else { return }
+    initial = interval()
+    if !waitForFullDisplay || fullWasMarked {
+      complete()
+    }
+  }
+
+  private func complete() {
+    guard !finished, let initial else { return }
+    let full = waitForFullDisplay ? interval() : initial
+    finished = true
+    let result = BrownfieldDisplayMetrics(presentationID: id, moduleName: moduleName,
+      initialDisplay: initial, fullDisplay: full, isFinal: true)
+    let completion = callback
+    callback = nil
+    stop()
+    completion?(result)
+  }
+
+  func cancel() {
+    guard !finished else { return }
+    finished = true
+    callback = nil
+    stop()
+  }
+
+  private func stop() {
+    ui?.stop()
+    js?.stop()
+    tokens.forEach(NotificationCenter.default.removeObserver)
+    tokens.removeAll()
+  }
+
+  deinit { stop() }
+}
+
+/// A child probe preserves the RN root view's type, layout, and touch handling.
+internal final class BrownfieldAppearanceProbe: UIView {
+  let session: BrownfieldDisplaySession
+  /// Set when a view controller hosts the root. The probe then reports appearance only while
+  /// that controller is visible, for a root that arrives after `viewDidAppear`.
+  var isHostVisible: (() -> Bool)?
+  private var hasAttached = false
+
+  init(session: BrownfieldDisplaySession) {
+    self.session = session
+    super.init(frame: .zero)
+    isUserInteractionEnabled = false
+    isHidden = true
+  }
+
+  required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+  override func didMoveToWindow() {
+    super.didMoveToWindow()
+    if window != nil {
+      hasAttached = true
+      if let isHostVisible {
+        if isHostVisible() { session.appeared() }
+      } else {
+        DispatchQueue.main.async { [weak self] in
+          guard let self, self.window != nil else { return }
+          self.session.appeared()
+        }
+      }
+    } else if hasAttached {
+      session.cancel()
+    }
+  }
+}

package/ios/BrownfieldPerformanceBridge.h

@@ -0,0 +1,8 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+@interface BrownfieldPerformanceBridge : NSObject
+// Call on main. Returns NO until the JS thread or an RN bridge/proxy is available.
++ (BOOL)dispatchToJavaScript:(dispatch_block_t)block;
+@end
+NS_ASSUME_NONNULL_END