@callstack/react-native-brownfield 5.2.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @callstack/react-native-brownfield
 
+## 6.0.0
+
+### Major Changes
+
+- [#494](https://github.com/callstack/react-native-brownfield/pull/494) [`d28810c`](https://github.com/callstack/react-native-brownfield/commit/d28810caa32f727d56915d8e8d9276a82560b231) Thanks [@hurali97](https://github.com/hurali97)! - Add Android startup, TTID/TTFD, and JS/UI responsiveness metrics. Android's
+  `OnJSBundleLoaded` callback now receives `JSBundleTimings` instead of a Boolean.
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @callstack/brownfield-cli@6.0.0
+
+## 5.3.0
+
+### Minor Changes
+
+- [#480](https://github.com/callstack/react-native-brownfield/pull/480) [`f17f556`](https://github.com/callstack/react-native-brownfield/commit/f17f55616615a2bcb82d90f358efd838f56f5e67) Thanks [@gedu](https://github.com/gedu)! - add @callstack/create-react-native-brownfield: scaffold Brownfield packaging targets in an existing React Native CLI project (`npm create @callstack/react-native-brownfield`), plus the `@callstack/react-native-brownfield/scaffold` subpath export it uses
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @callstack/brownfield-cli@5.3.0
+
 ## 5.2.0
 
 ### Minor Changes

package/android/build.gradle

@@ -128,4 +128,5 @@ dependencies {
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  testImplementation "junit:junit:4.13.2"
 }

package/android/consumer-rules.pro

@@ -1,6 +1,12 @@
 -keep class com.callstack.reactnativebrownfield.ReactNativeBrownfield { *; }
 -keep class com.callstack.reactnativebrownfield.ReactNativeBrownfield$Companion { *; }
 -keep interface com.callstack.reactnativebrownfield.OnJSBundleLoaded { *; }
+-keep interface com.callstack.reactnativebrownfield.OnDisplayMetrics { *; }
+-keep class com.callstack.reactnativebrownfield.JSBundleTimings { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldDisplayMetrics { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldDisplayInterval { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldThreadMetrics { *; }
+-keep class com.callstack.reactnativebrownfield.BrownfieldPerformanceModule { *; }
 -keep interface com.callstack.reactnativebrownfield.OnMessageListener { *; }
 -keep class com.callstack.reactnativebrownfield.ReactNativeFragment { *; }
 -keep class com.callstack.reactnativebrownfield.ReactNativeFragment$Companion { *; }

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

@@ -0,0 +1,384 @@
+package com.callstack.reactnativebrownfield
+
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.view.Choreographer
+import android.view.View
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactInstanceEventListener
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.bridge.ReactMarker
+import com.facebook.react.bridge.ReactMarkerConstants
+import java.util.Collections
+import java.util.UUID
+
+class JSBundleTimings @JvmOverloads constructor(
+    val jsBundleLoadTime: Double?,
+    val jsBundleEvaluationTime: Double?,
+    timeline: List<Map<String, Any>> = emptyList()
+) {
+    val timeline: List<Map<String, Any>> = Collections.unmodifiableList(
+        timeline.map { Collections.unmodifiableMap(HashMap(it)) }
+    )
+}
+
+fun interface OnDisplayMetrics {
+    fun onMetrics(metrics: BrownfieldDisplayMetrics)
+}
+
+data class BrownfieldThreadMetrics(
+    val fps: Double?,
+    val busyRatio: Double?,
+    val sampledMs: Double,
+    val frameCount: Int
+)
+
+data class BrownfieldDisplayInterval(
+    val duration: Double,
+    val jsThread: BrownfieldThreadMetrics,
+    val uiThread: BrownfieldThreadMetrics
+)
+
+data class BrownfieldDisplayMetrics(
+    val presentationID: String,
+    val moduleName: String,
+    val initialDisplay: BrownfieldDisplayInterval?,
+    val fullDisplay: BrownfieldDisplayInterval?,
+    val isFinal: Boolean,
+    val isCancelled: Boolean = false
+)
+
+internal class BrownfieldFrameSamples {
+    private var startNanos: Long? = null
+    private var lastNanos = 0L
+    private var budgetNanos = 1_000_000_000L / 60
+    private var frames = 0
+    private var busyNanos = 0L
+
+    @Synchronized
+    fun begin(nowNanos: Long) {
+        if (startNanos == null) {
+            startNanos = nowNanos
+            lastNanos = nowNanos
+        }
+    }
+
+    @Synchronized
+    fun record(nowNanos: Long, frameIntervalNanos: Long) {
+        if (startNanos == null) begin(nowNanos)
+        budgetNanos = frameIntervalNanos.coerceAtLeast(1_000_000_000L / 240)
+        busyNanos += (nowNanos - lastNanos - budgetNanos).coerceAtLeast(0)
+        frames += 1
+        lastNanos = nowNanos
+    }
+
+    @Synchronized
+    fun snapshot(nowNanos: Long): BrownfieldThreadMetrics {
+        val start = startNanos
+        if (start == null || nowNanos <= start) {
+            return BrownfieldThreadMetrics(null, null, 0.0, 0)
+        }
+        val elapsed = nowNanos - start
+        val unfinishedStall = (nowNanos - lastNanos - budgetNanos).coerceAtLeast(0)
+        return BrownfieldThreadMetrics(
+            fps = frames * 1_000_000_000.0 / elapsed,
+            busyRatio = ((busyNanos + unfinishedStall).toDouble() / elapsed).coerceAtMost(1.0),
+            sampledMs = elapsed / 1_000_000.0,
+            frameCount = frames
+        )
+    }
+}
+
+internal class BrownfieldFrameSampler {
+    private val samples = BrownfieldFrameSamples()
+    @Volatile private var stopped = false
+    private var choreographer: Choreographer? = null
+
+    private val callback = object : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            if (stopped) return
+            val now = SystemClock.elapsedRealtimeNanos()
+            val interval = ReactNativeBrownfield.displayFrameIntervalNanos()
+            samples.record(now, interval)
+            choreographer?.postFrameCallback(this)
+        }
+    }
+
+    fun startOnCurrentLooper() {
+        if (stopped || choreographer != null || Looper.myLooper() == null) return
+        samples.begin(SystemClock.elapsedRealtimeNanos())
+        choreographer = Choreographer.getInstance().also { it.postFrameCallback(callback) }
+    }
+
+    fun snapshot(nowNanos: Long) = samples.snapshot(nowNanos)
+
+    fun stop() {
+        stopped = true
+        choreographer?.removeFrameCallback(callback)
+        choreographer = null
+    }
+}
+
+internal object BrownfieldPresentationRegistry {
+    private val sessions = mutableMapOf<String, BrownfieldDisplaySession>()
+
+    @Synchronized fun add(session: BrownfieldDisplaySession) { sessions[session.id] = session }
+    @Synchronized fun remove(id: String) { sessions.remove(id) }
+    @Synchronized fun mark(id: String) { sessions[id]?.markFullyDisplayed() }
+    @Synchronized fun cancelAll() { sessions.values.toList().forEach { it.cancel() }; sessions.clear() }
+}
+
+internal class BrownfieldDisplaySession(
+    val moduleName: String,
+    private val waitForFullDisplay: Boolean,
+    collectThreadMetrics: Boolean,
+    callback: OnDisplayMetrics?
+) {
+    val id: String = UUID.randomUUID().toString()
+    private val main = Handler(Looper.getMainLooper())
+    private val startNanos = SystemClock.elapsedRealtimeNanos()
+    private var completion = callback
+    private val ui = if (collectThreadMetrics && callback != null) BrownfieldFrameSampler() else null
+    private val js = if (collectThreadMetrics && callback != null) BrownfieldFrameSampler() else null
+    private var initial: BrownfieldDisplayInterval? = null
+    private var marked = false
+    private var attached = false
+    private var resumed = true
+    @Volatile private var finished = callback == null
+    private var boundRoot: View? = null
+    private var attachmentListener: View.OnAttachStateChangeListener? = null
+    private var contextListener: ReactInstanceEventListener? = null
+
+    init {
+        if (!finished) {
+            BrownfieldPresentationRegistry.add(this)
+            main.post { if (!finished) ui?.startOnCurrentLooper() }
+            scheduleJS()
+        }
+    }
+
+    private fun scheduleJS() {
+        if (js == null || finished) return
+        val context = ReactNativeBrownfield.currentReactContext()
+        if (context != null) {
+            context.runOnJSQueueThread { if (!finished) js.startOnCurrentLooper() }
+            return
+        }
+        val host = ReactNativeBrownfield.shared.reactHost
+        val listener = object : ReactInstanceEventListener {
+            override fun onReactContextInitialized(context: ReactContext) {
+                host.removeReactInstanceEventListener(this)
+                contextListener = null
+                context.runOnJSQueueThread { if (!finished) js.startOnCurrentLooper() }
+            }
+        }
+        contextListener = listener
+        host.addReactInstanceEventListener(listener)
+    }
+
+    fun bind(root: View, requiresResume: Boolean) {
+        resumed = !requiresResume
+        val listener = object : View.OnAttachStateChangeListener {
+            override fun onViewAttachedToWindow(view: View) {
+                attached = true
+                main.post { maybeAppear(view) }
+            }
+            override fun onViewDetachedFromWindow(view: View) {
+                if (attached) cancel()
+                view.removeOnAttachStateChangeListener(this)
+            }
+        }
+        boundRoot = root
+        attachmentListener = listener
+        root.addOnAttachStateChangeListener(listener)
+        if (root.isAttachedToWindow) {
+            attached = true
+            main.post { maybeAppear(root) }
+        }
+    }
+
+    fun setResumed(value: Boolean) {
+        resumed = value
+        if (!value && attached && initial == null) cancel() else if (value) main.post { maybeAppear(null) }
+    }
+
+    private fun maybeAppear(root: View?) {
+        if (finished || !attached || !resumed || initial != null || (root != null && !root.isAttachedToWindow)) return
+        initial = interval()
+        if (!waitForFullDisplay || marked) complete()
+    }
+
+    fun markFullyDisplayed() {
+        main.post {
+            if (finished || marked) return@post
+            marked = true
+            if (initial != null) complete()
+        }
+    }
+
+    private fun interval(): BrownfieldDisplayInterval {
+        val now = SystemClock.elapsedRealtimeNanos()
+        val unavailable = BrownfieldThreadMetrics(null, null, 0.0, 0)
+        return BrownfieldDisplayInterval(
+            duration = (now - startNanos) / 1_000_000.0,
+            jsThread = js?.snapshot(now) ?: unavailable,
+            uiThread = ui?.snapshot(now) ?: unavailable
+        )
+    }
+
+    private fun complete() {
+        val first = initial ?: return
+        val full = if (waitForFullDisplay) interval() else first
+        finished = true
+        val callback = completion
+        completion = null
+        stop()
+        main.post { callback?.onMetrics(BrownfieldDisplayMetrics(id, moduleName, first, full, true)) }
+    }
+
+    fun cancel() {
+        main.post {
+            if (finished) return@post
+            finished = true
+            completion = null
+            stop()
+        }
+    }
+
+    private fun stop() {
+        BrownfieldPresentationRegistry.remove(id)
+        attachmentListener?.let { boundRoot?.removeOnAttachStateChangeListener(it) }
+        attachmentListener = null
+        boundRoot = null
+        contextListener?.let {
+            ReactNativeBrownfield.shared.reactHost.removeReactInstanceEventListener(it)
+        }
+        contextListener = null
+        ui?.stop()
+        js?.stop()
+    }
+}
+
+internal object AndroidJSBundleTimingObserver {
+    private val main = Handler(Looper.getMainLooper())
+    private var generation = 0
+    private var accumulator = JSBundleTimingAccumulator()
+    private var result: JSBundleTimings? = null
+    private val subscribers = mutableListOf<OnJSBundleLoaded>()
+    private var installed = false
+
+    private val markerListener = ReactMarker.MarkerListener { name, _, instanceKey ->
+        val now = SystemClock.elapsedRealtime()
+        synchronized(this) {
+            when (name) {
+                ReactMarkerConstants.DOWNLOAD_START -> accumulator.record(BundleMarker.DOWNLOAD_START, instanceKey, now)
+                ReactMarkerConstants.DOWNLOAD_END -> accumulator.record(BundleMarker.DOWNLOAD_END, instanceKey, now)
+                ReactMarkerConstants.RUN_JS_BUNDLE_START -> accumulator.record(BundleMarker.EVALUATION_START, instanceKey, now)
+                ReactMarkerConstants.RUN_JS_BUNDLE_END -> accumulator.record(BundleMarker.EVALUATION_END, instanceKey, now)
+                else -> Unit
+            }
+        }
+    }
+
+    @Synchronized fun install() {
+        if (!installed) {
+            installed = true
+            ReactMarker.addListener(markerListener)
+        }
+    }
+
+    @Synchronized fun beginGeneration(): Int {
+        generation += 1
+        accumulator = JSBundleTimingAccumulator()
+        result = null
+        subscribers.clear()
+        return generation
+    }
+
+    @Synchronized fun subscribe(callback: OnJSBundleLoaded?) {
+        if (callback == null) return
+        val cached = result
+        if (cached != null) main.post { callback(cached) } else subscribers.add(callback)
+    }
+
+    fun contextInitialized(context: ReactContext, expectedGeneration: Int) {
+        context.runOnJSQueueThread { main.post { complete(expectedGeneration) } }
+    }
+
+    @Synchronized private fun complete(expectedGeneration: Int) {
+        if (expectedGeneration != generation || result != null) return
+        val timings = accumulator.snapshot()
+        result = timings
+        val callbacks = subscribers.toList()
+        subscribers.clear()
+        callbacks.forEach { it(timings) }
+    }
+
+    @Synchronized fun reset() {
+        generation += 1
+        accumulator = JSBundleTimingAccumulator()
+        result = null
+        subscribers.clear()
+    }
+}
+
+internal enum class BundleMarker { DOWNLOAD_START, DOWNLOAD_END, EVALUATION_START, EVALUATION_END }
+
+internal class JSBundleTimingAccumulator {
+    private data class Endpoint(
+        var start: Long? = null,
+        var stop: Long? = null,
+        var ambiguous: Boolean = false
+    )
+
+    private val download = Endpoint()
+    private val evaluation = Endpoint()
+
+    fun record(marker: BundleMarker, instanceKey: Int, timestampMs: Long) {
+        val endpoint = when (marker) {
+            BundleMarker.DOWNLOAD_START, BundleMarker.DOWNLOAD_END -> download
+            BundleMarker.EVALUATION_START, BundleMarker.EVALUATION_END -> {
+                if (instanceKey != 1) return
+                evaluation
+            }
+        }
+        when (marker) {
+            BundleMarker.DOWNLOAD_START, BundleMarker.EVALUATION_START -> {
+                if (endpoint.start != null || endpoint.stop != null) endpoint.ambiguous = true
+                else endpoint.start = timestampMs
+            }
+            BundleMarker.DOWNLOAD_END, BundleMarker.EVALUATION_END -> {
+                if (endpoint.start == null || endpoint.stop != null) endpoint.ambiguous = true
+                else endpoint.stop = timestampMs
+            }
+        }
+    }
+
+    fun snapshot(): JSBundleTimings {
+        fun valid(endpoint: Endpoint): Pair<Long, Long>? {
+            val start = endpoint.start ?: return null
+            val stop = endpoint.stop ?: return null
+            return if (!endpoint.ambiguous && stop >= start) start to stop else null
+        }
+        val downloadPair = valid(download)
+        val evaluationPair = valid(evaluation)
+        val timeline = listOfNotNull(
+            downloadPair?.let { (start, stop) -> mapOf("tag" to "DOWNLOAD", "startMs" to start, "stopMs" to stop) },
+            evaluationPair?.let { (start, stop) -> mapOf("tag" to "RUN_JS_BUNDLE", "startMs" to start, "stopMs" to stop) }
+        ).sortedBy { it["startMs"] as Long }
+        return JSBundleTimings(
+            downloadPair?.let { (it.second - it.first).toDouble() },
+            evaluationPair?.let { (it.second - it.first).toDouble() },
+            timeline
+        )
+    }
+}
+
+internal fun ReactHost.installBrownfieldPerformanceStop() {
+    val stop = {
+        AndroidJSBundleTimingObserver.reset()
+        BrownfieldPresentationRegistry.cancelAll()
+    }
+    addBeforeDestroyListener(stop)
+}

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

@@ -0,0 +1,15 @@
+package com.callstack.reactnativebrownfield
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+
+class BrownfieldPerformanceModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+    override fun getName() = "BrownfieldPerformance"
+
+    @ReactMethod
+    fun markFullyDisplayed(presentationID: String) {
+        BrownfieldPresentationRegistry.mark(presentationID)
+    }
+}

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

@@ -8,14 +8,14 @@ import com.facebook.react.modules.core.DefaultHardwareBackBtnHandler
 
 class ReactDelegateWrapper(
     private val activity: ComponentActivity?,
-    resolvedReactHost: ReactHost?,
-    moduleName: String,
-    launchOptions: Bundle?
+    private val resolvedReactHost: ReactHost?,
+    private val moduleName: String,
+    internal val brownfieldLaunchOptions: Bundle?
 ) : ReactDelegate(
     activity = activity!!,
     resolvedReactHost,
     appKey = moduleName,
-    launchOptions = launchOptions,
+    launchOptions = brownfieldLaunchOptions,
 ) {
     private lateinit var hardwareBackHandler: () -> Unit
     private val backBtnHandler = DefaultHardwareBackBtnHandler {
@@ -33,4 +33,7 @@ class ReactDelegateWrapper(
     fun onReactHostResume() {
         super.reactHost?.onHostResume(activity, backBtnHandler)
     }
-}
+
+    internal fun withLaunchOptions(launchOptions: Bundle?): ReactDelegateWrapper =
+        ReactDelegateWrapper(activity, resolvedReactHost, moduleName, launchOptions)
+}

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

@@ -2,6 +2,7 @@ package com.callstack.reactnativebrownfield
 
 import android.app.Application
 import android.os.Bundle
+import android.view.WindowManager
 import android.widget.FrameLayout
 import androidx.activity.OnBackPressedCallback
 import androidx.fragment.app.FragmentActivity
@@ -20,7 +21,7 @@ import java.util.concurrent.CopyOnWriteArrayList
 import java.util.concurrent.atomic.AtomicBoolean
 
 fun interface OnJSBundleLoaded {
-    operator fun invoke(initialized: Boolean)
+    operator fun invoke(timings: JSBundleTimings)
 }
 
 fun interface OnMessageListener {
@@ -34,6 +35,7 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
         private lateinit var instance: ReactNativeBrownfield
         private val initialized = AtomicBoolean()
         private val nativeLibsLoaded = AtomicBoolean()
+        private lateinit var applicationContext: Application
 
         @JvmStatic
         val shared: ReactNativeBrownfield get() = instance
@@ -62,7 +64,9 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
             reactHost: ReactHost,
             onJSBundleLoaded: OnJSBundleLoaded? = null
         ) {
+            applicationContext = application
             if (!initialized.getAndSet(true)) {
+                AndroidJSBundleTimingObserver.install()
                 loadNativeLibs(application)
                 installAndPreload(reactHost, onJSBundleLoaded)
             } else {
@@ -76,14 +80,16 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
             onJSBundleLoaded: OnJSBundleLoaded? = null,
             reactHostFactory: () -> ReactHost
         ) {
+            applicationContext = application
             if (!initialized.getAndSet(true)) {
+                AndroidJSBundleTimingObserver.install()
                 loadNativeLibs(application)
                 installAndPreload(reactHostFactory(), onJSBundleLoaded)
             } else {
                 invokeWhenJSBundleLoaded(onJSBundleLoaded)
             }
         }
-        
+
         @JvmStatic
         @JvmOverloads
         fun initialize(
@@ -91,7 +97,9 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
             options: HashMap<String, Any>,
             onJSBundleLoaded: OnJSBundleLoaded? = null
         ) {
+            applicationContext = application
             if (!initialized.getAndSet(true)) {
+                AndroidJSBundleTimingObserver.install()
                 loadNativeLibs(application)
                 val reactHost = getDefaultReactHost(
                     context = application,
@@ -123,11 +131,11 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
             initialize(application, options, onJSBundleLoaded)
         }
 
-        private fun preloadReactNative(callback: ((Boolean) -> Unit)) {
+        private fun preloadReactNative(generation: Int) {
             shared.reactHost.addReactInstanceEventListener(object :
                 ReactInstanceEventListener {
                 override fun onReactContextInitialized(context: ReactContext) {
-                    callback(true)
+                    AndroidJSBundleTimingObserver.contextInitialized(context, generation)
                     shared.reactHost.removeReactInstanceEventListener(this)
                 }
             })
@@ -135,10 +143,12 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
         }
 
         private fun installAndPreload(reactHost: ReactHost, onJSBundleLoaded: OnJSBundleLoaded?) {
+            AndroidJSBundleTimingObserver.install()
+            val generation = AndroidJSBundleTimingObserver.beginGeneration()
             instance = ReactNativeBrownfield(reactHost)
-            preloadReactNative {
-                onJSBundleLoaded?.invoke(true)
-            }
+            reactHost.installBrownfieldPerformanceStop()
+            AndroidJSBundleTimingObserver.subscribe(onJSBundleLoaded)
+            preloadReactNative(generation)
         }
 
         private fun invokeWhenJSBundleLoaded(onJSBundleLoaded: OnJSBundleLoaded?) {
@@ -146,18 +156,21 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
                 return
             }
 
-            val reactHost = instance.reactHost
-            reactHost.currentReactContext?.let {
-                onJSBundleLoaded.invoke(true)
-                return
-            }
+            AndroidJSBundleTimingObserver.subscribe(onJSBundleLoaded)
+        }
 
-            reactHost.addReactInstanceEventListener(object : ReactInstanceEventListener {
-                override fun onReactContextInitialized(context: ReactContext) {
-                    onJSBundleLoaded.invoke(true)
-                    reactHost.removeReactInstanceEventListener(this)
-                }
-            })
+        internal fun currentReactContext(): ReactContext? =
+            if (::instance.isInitialized) instance.reactHost.currentReactContext else null
+
+        internal fun displayFrameIntervalNanos(): Long {
+            if (!::applicationContext.isInitialized) return 1_000_000_000L / 60
+            @Suppress("DEPRECATION")
+            val refreshRate = applicationContext
+                .getSystemService(WindowManager::class.java)
+                ?.defaultDisplay
+                ?.refreshRate
+                ?.takeIf { it > 0f } ?: 60f
+            return (1_000_000_000.0 / refreshRate).toLong()
         }
     }
 
@@ -215,10 +228,47 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
         reactDelegate: ReactDelegateWrapper?,
         launchOptions: Bundle?,
         lifecycleOwner: LifecycleOwner?,
+    ): FrameLayout {
+        return createViewInternal(
+            activity, moduleName, reactDelegate, launchOptions, lifecycleOwner, null, false
+        )
+    }
+
+    @JvmOverloads
+    fun createView(
+        activity: FragmentActivity?,
+        moduleName: String,
+        reactDelegate: ReactDelegateWrapper? = null,
+        launchOptions: Bundle? = null,
+        waitForFullDisplay: Boolean,
+        collectThreadMetrics: Boolean = false,
+        onMetrics: OnDisplayMetrics? = null,
+    ): FrameLayout {
+        val session = BrownfieldDisplaySession(
+            moduleName, waitForFullDisplay, collectThreadMetrics, onMetrics
+        )
+        val props = Bundle(launchOptions ?: Bundle()).apply {
+            putString("brownfieldPresentationID", session.id)
+        }
+        return createViewInternal(activity, moduleName, reactDelegate, props, activity, session, false)
+    }
+
+    internal fun createViewInternal(
+        activity: FragmentActivity?,
+        moduleName: String,
+        reactDelegate: ReactDelegateWrapper?,
+        launchOptions: Bundle?,
+        lifecycleOwner: LifecycleOwner?,
+        session: BrownfieldDisplaySession?,
+        requiresResume: Boolean,
     ): FrameLayout {
         val reactHost = shared.reactHost
-        val resolvedDelegate =
-            reactDelegate ?: ReactDelegateWrapper(activity, reactHost, moduleName, launchOptions)
+        val resolvedDelegate = when {
+            reactDelegate == null -> ReactDelegateWrapper(activity, reactHost, moduleName, launchOptions)
+            session != null && reactDelegate.brownfieldLaunchOptions !== launchOptions ->
+                reactDelegate.withLaunchOptions(launchOptions)
+            else -> reactDelegate
+        }
 
         val backPressedCallback: OnBackPressedCallback = object : OnBackPressedCallback(true) {
             override fun handleOnBackPressed() {
@@ -248,24 +298,29 @@ class ReactNativeBrownfield private constructor(val reactHost: ReactHost) {
          * In such a case, we set the lifeCycle observer.
          */
         if (reactDelegate == null) {
-            lifecycleOwner?.lifecycle?.addObserver(getLifeCycleObserver(resolvedDelegate))
+            lifecycleOwner?.lifecycle?.addObserver(getLifeCycleObserver(resolvedDelegate, session))
         }
 
         resolvedDelegate.loadApp()
-        return resolvedDelegate.reactRootView!!
+        return resolvedDelegate.reactRootView!!.also { session?.bind(it, requiresResume) }
     }
 
-    private fun getLifeCycleObserver(reactDelegate: ReactDelegateWrapper): DefaultLifecycleObserver {
+    private fun getLifeCycleObserver(
+        reactDelegate: ReactDelegateWrapper,
+        session: BrownfieldDisplaySession?
+    ): DefaultLifecycleObserver {
         return object : DefaultLifecycleObserver {
             override fun onResume(owner: LifecycleOwner) {
                 reactDelegate.onReactHostResume()
             }
 
             override fun onPause(owner: LifecycleOwner) {
+                session?.cancel()
                 reactDelegate.onHostPause()
             }
 
             override fun onDestroy(owner: LifecycleOwner) {
+                session?.cancel()
                 reactDelegate.onHostDestroy()
                 owner.lifecycle.removeObserver(this) // Cleanup to avoid leaks
             }