@granite-js/micro-frontend 2.0.0

package/android/src/main/java/run/granite/microfrontend/GraniteMicroFrontendRuntimeEventRouter.kt

@@ -0,0 +1,186 @@
+package run.granite.microfrontend
+
+import com.facebook.common.logging.FLog
+
+internal interface GraniteMicroFrontendRuntimeEventTarget {
+    /**
+     * Hands [event] to the runtime. Returning `true` means the target accepted the event, not that
+     * delivery happened: the target must invoke [onDelivered] once it has handed the event to the
+     * runtime's event emitter. An accepted event that is never acknowledged stays queued and is
+     * redelivered to the next runtime.
+     *
+     * [onDelivered] does not prove that JavaScript observed the event. The emitter dispatches to
+     * whatever listeners are registered at that moment and schedules each one on a later tick, so
+     * an event acknowledged while nothing is subscribed is dropped from the queue without anyone
+     * seeing it. The queue covers the gap between runtimes, not the gap between a live runtime and
+     * a subscribed listener.
+     */
+    fun emit(event: GraniteMicroFrontendEvent, onDelivered: () -> Unit): Boolean
+}
+
+internal class GraniteMicroFrontendRuntimeEventRouter {
+    private val lock = Any()
+    private val pendingEvents = ArrayDeque<GraniteMicroFrontendEvent>()
+    private val attachedTargets = mutableSetOf<GraniteMicroFrontendRuntimeEventTarget>()
+    private var activeTarget: GraniteMicroFrontendRuntimeEventTarget? = null
+    private var isDelivering = false
+    private var inFlight: Delivery? = null
+    private var didLoseActiveTarget = false
+
+    fun attach(target: GraniteMicroFrontendRuntimeEventTarget) {
+        synchronized(lock) {
+            attachedTargets.add(target)
+        }
+    }
+
+    fun startEventDelivery(target: GraniteMicroFrontendRuntimeEventTarget) {
+        val shouldDrain = synchronized(lock) {
+            check(target in attachedTargets) { "Runtime must be attached before starting event delivery" }
+            if (activeTarget != null && activeTarget !== target) {
+                return
+            }
+            if (didLoseActiveTarget) {
+                didLoseActiveTarget = false
+                FLog.w(
+                    TAG,
+                    "Runtime replaced while %d event(s) were pending; session state is redelivered from the queue",
+                    pendingEvents.size,
+                )
+            }
+            activeTarget = target
+            startDrainIfNeeded()
+        }
+        if (shouldDrain) {
+            drain()
+        }
+    }
+
+    fun emit(event: GraniteMicroFrontendEvent) {
+        val shouldDrain = synchronized(lock) {
+            if (pendingEvents.size >= MAX_PENDING_EVENTS) {
+                FLog.w(
+                    TAG,
+                    "Dropping %s: %d event(s) already pending with no runtime consuming them",
+                    event::class.java.simpleName,
+                    pendingEvents.size,
+                )
+                return
+            }
+            pendingEvents.addLast(event)
+            activeTarget ?: return
+            if (!startDrainIfNeeded()) {
+                return
+            }
+            true
+        }
+        if (shouldDrain) {
+            drain()
+        }
+    }
+
+    fun detach(target: GraniteMicroFrontendRuntimeEventTarget) {
+        synchronized(lock) {
+            attachedTargets.remove(target)
+            if (activeTarget === target) {
+                activeTarget = null
+                didLoseActiveTarget = true
+            }
+            val delivery = inFlight
+            if (delivery != null && delivery.target === target && !delivery.isLoopOwned) {
+                inFlight = null
+                isDelivering = false
+            }
+        }
+    }
+
+    private fun startDrainIfNeeded(): Boolean {
+        if (isDelivering || pendingEvents.isEmpty()) {
+            return false
+        }
+        isDelivering = true
+        return true
+    }
+
+    private fun drain() {
+        while (true) {
+            val delivery = synchronized(lock) {
+                val target = activeTarget
+                if (target == null || pendingEvents.isEmpty()) {
+                    isDelivering = false
+                    inFlight = null
+                    return
+                }
+                Delivery(target, pendingEvents.first()).also { inFlight = it }
+            }
+            val accepted = try {
+                delivery.target.emit(delivery.event) { acknowledge(delivery) }
+            } catch (error: Throwable) {
+                val shouldResumeWithReplacement = synchronized(lock) {
+                    delivery.isLoopOwned = false
+                    inFlight = null
+                    isDelivering = false
+                    activeTarget != null && activeTarget !== delivery.target && startDrainIfNeeded()
+                }
+                if (shouldResumeWithReplacement) {
+                    try {
+                        drain()
+                    } catch (replacementError: Throwable) {
+                        error.addSuppressed(replacementError)
+                    }
+                }
+                throw error
+            }
+            synchronized(lock) {
+                delivery.isLoopOwned = false
+                if (!accepted) {
+                    inFlight = null
+                    isDelivering = false
+                    val shouldResumeWithReplacement =
+                        activeTarget != null && activeTarget !== delivery.target && startDrainIfNeeded()
+                    if (!shouldResumeWithReplacement) {
+                        return
+                    }
+                } else if (!delivery.isAcknowledged) {
+                    // Delivery is in flight. acknowledge() resumes the drain once it completes.
+                    return
+                } else {
+                    inFlight = null
+                }
+            }
+        }
+    }
+
+    private fun acknowledge(delivery: Delivery) {
+        val shouldDrain = synchronized(lock) {
+            if (delivery.isAcknowledged) {
+                return
+            }
+            delivery.isAcknowledged = true
+            if (pendingEvents.firstOrNull() === delivery.event) {
+                pendingEvents.removeFirst()
+            }
+            if (delivery.isLoopOwned) {
+                return
+            }
+            inFlight = null
+            isDelivering = false
+            activeTarget != null && startDrainIfNeeded()
+        }
+        if (shouldDrain) {
+            drain()
+        }
+    }
+
+    private class Delivery(
+        val target: GraniteMicroFrontendRuntimeEventTarget,
+        val event: GraniteMicroFrontendEvent,
+    ) {
+        var isLoopOwned = true
+        var isAcknowledged = false
+    }
+
+    internal companion object {
+        private const val TAG = "GraniteMicroFrontendRuntime"
+        internal const val MAX_PENDING_EVENTS = 64
+    }
+}

package/android/src/main/java/run/granite/microfrontend/GraniteMicroFrontendRuntimeHost.kt

@@ -0,0 +1,42 @@
+package run.granite.microfrontend
+
+object GraniteMicroFrontendRuntimeHost {
+    private val eventRouter = GraniteMicroFrontendRuntimeEventRouter()
+    private val sessionStore = GraniteMicroFrontendSessionStore(eventRouter::emit)
+
+    @JvmStatic
+    fun registerSession(sessionId: String): GraniteMicroFrontendSessionRegistration =
+        sessionStore.registerSession(sessionId)
+
+    @JvmSynthetic
+    internal fun emit(event: GraniteMicroFrontendEvent) = eventRouter.emit(event)
+
+    @JvmStatic
+    fun emitPreloadApp(appName: String) = emit(GraniteMicroFrontendEvent.PreloadApp(appName))
+
+    @JvmSynthetic
+    internal fun emitOpenApp(sessionId: String, appName: String, scheme: String) =
+        emit(GraniteMicroFrontendEvent.OpenApp(sessionId, appName, scheme))
+
+    @JvmSynthetic
+    internal fun emitCloseApp(sessionId: String) = emit(GraniteMicroFrontendEvent.CloseApp(sessionId))
+
+    @JvmSynthetic
+    internal fun emitSessionVisibilityChanged(sessionId: String, isVisible: Boolean) =
+        emit(GraniteMicroFrontendEvent.SessionVisibilityChanged(sessionId, isVisible))
+
+    @JvmSynthetic
+    internal fun attach(module: GraniteMicroFrontendRuntimeModule) = eventRouter.attach(module)
+
+    @JvmSynthetic
+    internal fun startEventDelivery(module: GraniteMicroFrontendRuntimeModule) =
+        eventRouter.startEventDelivery(module)
+
+    @JvmSynthetic
+    internal fun detach(module: GraniteMicroFrontendRuntimeModule) = eventRouter.detach(module)
+
+    @JvmSynthetic
+    internal fun unregisterSession(sessionId: String, token: String) {
+        sessionStore.unregisterSession(sessionId, token)
+    }
+}

package/android/src/main/java/run/granite/microfrontend/GraniteMicroFrontendRuntimeModule.kt

@@ -0,0 +1,56 @@
+package run.granite.microfrontend
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+
+@ReactModule(name = NativeGraniteMicroFrontendRuntimeSpec.NAME)
+class GraniteMicroFrontendRuntimeModule(
+    reactContext: ReactApplicationContext,
+) : NativeGraniteMicroFrontendRuntimeSpec(reactContext), GraniteMicroFrontendRuntimeEventTarget {
+    override fun initialize() {
+        super.initialize()
+        GraniteMicroFrontendRuntimeHost.attach(this)
+    }
+
+    override fun invalidate() {
+        GraniteMicroFrontendRuntimeHost.detach(this)
+        super.invalidate()
+    }
+
+    override fun evaluateScript(request: ReadableMap, promise: Promise) {
+        val filePath = request.getString("filePath")
+        if (filePath == null) {
+            promise.reject(ERROR_INVALID_REQUEST, "evaluateScript requires request.filePath")
+            return
+        }
+
+        val enqueued = reactApplicationContext.runOnJSQueueThread {
+            try {
+                BundleEvaluator(reactApplicationContext).evaluateFile(filePath)
+                promise.resolve(null)
+            } catch (error: Exception) {
+                promise.reject(ERROR_EVALUATE_SCRIPT, error.message, error)
+            }
+        }
+        if (!enqueued) {
+            promise.reject(ERROR_EVALUATE_SCRIPT, "Failed to enqueue script evaluation on the JS queue")
+        }
+    }
+
+    override fun startEventDelivery() {
+        GraniteMicroFrontendRuntimeHost.startEventDelivery(this)
+    }
+
+    override fun emit(event: GraniteMicroFrontendEvent, onDelivered: () -> Unit): Boolean =
+        reactApplicationContext.runOnJSQueueThread {
+            emitOnEvent(event.toWritableMap())
+            onDelivered()
+        }
+
+    private companion object {
+        const val ERROR_INVALID_REQUEST = "INVALID_REQUEST"
+        const val ERROR_EVALUATE_SCRIPT = "EVALUATE_SCRIPT_FAILED"
+    }
+}

package/android/src/main/java/run/granite/microfrontend/GraniteMicroFrontendRuntimePackage.kt

@@ -0,0 +1,35 @@
+package run.granite.microfrontend
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+import com.teleport.host.PortalHostViewManager
+import com.teleport.portal.PortalViewManager
+
+class GraniteMicroFrontendRuntimePackage : BaseReactPackage() {
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+        listOf(PortalHostViewManager(), PortalViewManager())
+
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+        if (name == NativeGraniteMicroFrontendRuntimeSpec.NAME) {
+            GraniteMicroFrontendRuntimeModule(reactContext)
+        } else {
+            null
+        }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider {
+        mapOf(
+            NativeGraniteMicroFrontendRuntimeSpec.NAME to ReactModuleInfo(
+                name = NativeGraniteMicroFrontendRuntimeSpec.NAME,
+                className = GraniteMicroFrontendRuntimeModule::class.java.name,
+                canOverrideExistingModule = false,
+                needsEagerInit = false,
+                isCxxModule = false,
+                isTurboModule = true,
+            ),
+        )
+    }
+}

package/android/src/main/java/run/granite/microfrontend/GraniteMicroFrontendSessionStore.kt

@@ -0,0 +1,116 @@
+package run.granite.microfrontend
+
+import com.facebook.common.logging.FLog
+
+internal class GraniteMicroFrontendSessionStore(
+    private val emit: (GraniteMicroFrontendEvent) -> Unit,
+) {
+    private val lock = Any()
+    private val sessions = mutableMapOf<String, SessionEntry>()
+
+    fun registerSession(sessionId: String): GraniteMicroFrontendSessionRegistration {
+        require(sessionId.isNotBlank()) { "sessionId must not be blank" }
+        val token = java.util.UUID.randomUUID().toString()
+        val liveSessions = synchronized(lock) {
+            check(sessions[sessionId] == null) { "Session '$sessionId' is already registered" }
+            sessions[sessionId] = SessionEntry(token)
+            sessions.size
+        }
+        FLog.d(TAG, "Registered session '%s' (%d live)", sessionId, liveSessions)
+        return GraniteMicroFrontendSessionRegistration(this, sessionId, token)
+    }
+
+    fun openApp(sessionId: String, token: String, appName: String, scheme: String): Boolean {
+        require(appName.isNotBlank()) { "appName must not be blank" }
+        require(scheme.isNotBlank()) { "scheme must not be blank" }
+        return synchronized(lock) {
+            val session = sessions[sessionId] ?: return false
+            if (session.token != token || session.opened || session.closed) {
+                return false
+            }
+            session.opened = true
+            emit(GraniteMicroFrontendEvent.OpenApp(sessionId, appName, scheme))
+            true
+        }
+    }
+
+    fun setVisible(sessionId: String, token: String, isVisible: Boolean): Boolean {
+        return synchronized(lock) {
+            val session = sessions[sessionId] ?: return false
+            if (session.token != token || !session.opened || session.closed || session.isVisible == isVisible) {
+                return false
+            }
+            session.isVisible = isVisible
+            emit(GraniteMicroFrontendEvent.SessionVisibilityChanged(sessionId, isVisible))
+            true
+        }
+    }
+
+    fun closeApp(sessionId: String, token: String): Boolean {
+        return synchronized(lock) {
+            val session = sessions[sessionId] ?: return false
+            if (session.token != token || !session.opened || session.closed) {
+                return false
+            }
+            session.closed = true
+            emit(GraniteMicroFrontendEvent.CloseApp(sessionId))
+            true
+        }
+    }
+
+    fun unregisterSession(sessionId: String, token: String) {
+        val removed = synchronized(lock) {
+            val entry = sessions[sessionId]
+            when {
+                entry == null -> Outcome.UNKNOWN
+                entry.token != token -> Outcome.STALE_TOKEN
+                else -> {
+                    sessions.remove(sessionId)
+                    Outcome.REMOVED
+                }
+            }
+        }
+        // Both misses are silent no-ops today. They are worth a warning because each points at a
+        // different lifecycle bug and neither leaves any other trace.
+        when (removed) {
+            Outcome.REMOVED -> FLog.d(TAG, "Unregistered session '%s'", sessionId)
+            // Nothing to remove: this registration was already released, or was never made here.
+            Outcome.UNKNOWN ->
+                FLog.w(TAG, "Ignoring unregister for unknown session '%s'", sessionId)
+            // An entry under this id exists but belongs to a different registration, so whoever
+            // owns it never released it. The id stays occupied and registerSession() will keep
+            // throwing for it.
+            Outcome.STALE_TOKEN ->
+                FLog.w(TAG, "Ignoring unregister for session '%s': token belongs to another registration", sessionId)
+        }
+    }
+
+    private enum class Outcome { REMOVED, UNKNOWN, STALE_TOKEN }
+
+    private data class SessionEntry(
+        val token: String,
+        var opened: Boolean = false,
+        var isVisible: Boolean = false,
+        var closed: Boolean = false,
+    )
+
+    private companion object {
+        private const val TAG = "GraniteMicroFrontendRuntime"
+    }
+}
+
+class GraniteMicroFrontendSessionRegistration internal constructor(
+    private val store: GraniteMicroFrontendSessionStore,
+    private val sessionId: String,
+    private val token: String,
+) : AutoCloseable {
+    fun openApp(appName: String, scheme: String): Boolean = store.openApp(sessionId, token, appName, scheme)
+
+    fun setVisible(isVisible: Boolean): Boolean = store.setVisible(sessionId, token, isVisible)
+
+    fun closeApp(): Boolean = store.closeApp(sessionId, token)
+
+    override fun close() {
+        store.unregisterSession(sessionId, token)
+    }
+}

package/android/src/main/jni/CMakeLists.txt

@@ -0,0 +1,64 @@
+cmake_minimum_required(VERSION 3.13)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+
+# Autolinking owns this file. React Native's application CMake add_subdirectory()s it, so the
+# consuming app builds the codegen target exactly once. It must stay separate from the module's
+# own externalNativeBuild entry point (../../../CMakeLists.txt): pointing both at the same file
+# builds every target in it twice and lets mergeNativeLibs pick between two copies of each .so.
+#
+# This file is included from an app project, so it must not call project() and does not need
+# find_package(): ReactNative-application.cmake resolves ReactAndroid and fbjni before including
+# the autolinking file.
+
+set(CODEGEN_LIBRARY_NAME GraniteMicroFrontendRuntimeSpec)
+set(CODEGEN_TARGET_NAME react_codegen_${CODEGEN_LIBRARY_NAME})
+
+set(LIB_ANDROID_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../..)
+set(COMMON_DIR ${LIB_ANDROID_DIR}/../common/cpp)
+set(COMMON_COMPONENTS_DIR ${COMMON_DIR}/react/renderer/components/${CODEGEN_LIBRARY_NAME})
+set(GENERATED_JNI_DIR ${LIB_ANDROID_DIR}/build/generated/source/codegen/jni)
+set(GENERATED_COMPONENTS_DIR ${GENERATED_JNI_DIR}/react/renderer/components/${CODEGEN_LIBRARY_NAME})
+
+file(GLOB CODEGEN_CUSTOM_SOURCES CONFIGURE_DEPENDS ${COMMON_COMPONENTS_DIR}/*.cpp)
+file(GLOB CODEGEN_GENERATED_SOURCES CONFIGURE_DEPENDS
+  ${GENERATED_JNI_DIR}/*.cpp
+  ${GENERATED_COMPONENTS_DIR}/*.cpp
+)
+
+add_library(
+  ${CODEGEN_TARGET_NAME}
+  SHARED
+  ${CODEGEN_CUSTOM_SOURCES}
+  ${CODEGEN_GENERATED_SOURCES}
+)
+
+target_include_directories(
+  ${CODEGEN_TARGET_NAME}
+  PUBLIC
+  ${COMMON_DIR}
+  ${GENERATED_JNI_DIR}
+  ${GENERATED_COMPONENTS_DIR}
+)
+
+target_link_libraries(
+  ${CODEGEN_TARGET_NAME}
+  ReactAndroid::reactnative
+  ReactAndroid::jsi
+  fbjni::fbjni
+)
+
+if(COMMAND target_compile_reactnative_options)
+  target_compile_reactnative_options(${CODEGEN_TARGET_NAME} PRIVATE)
+else()
+  target_compile_options(
+    ${CODEGEN_TARGET_NAME}
+    PRIVATE
+    -DLOG_TAG=\"ReactNative\"
+    -DFOLLY_NO_CONFIG=1
+    -fexceptions
+    -frtti
+    -std=c++20
+    -Wall
+  )
+  target_compile_definitions(${CODEGEN_TARGET_NAME} PRIVATE RN_SERIALIZABLE_STATE)
+endif()

package/android/src/test/cpp/CMakeLists.txt

@@ -0,0 +1,35 @@
+cmake_minimum_required(VERSION 3.14)
+project(granite-micro-frontend-tests LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  GIT_REPOSITORY https://github.com/google/googletest.git
+  GIT_TAG v1.14.0
+)
+FetchContent_MakeAvailable(googletest)
+
+enable_testing()
+
+set(MAIN_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../main/cpp")
+
+add_executable(
+  FileReaderTest
+  FileReaderTest.cpp
+  ${MAIN_CPP_DIR}/FileReader.cpp
+)
+
+target_include_directories(
+  FileReaderTest
+  PRIVATE
+  "${MAIN_CPP_DIR}"
+)
+
+target_link_libraries(FileReaderTest GTest::gtest_main)
+
+include(GoogleTest)
+gtest_discover_tests(FileReaderTest)

package/android/src/test/cpp/FileReaderTest.cpp

@@ -0,0 +1,44 @@
+#include "FileReader.h"
+
+#include <filesystem>
+#include <fstream>
+
+#include <gtest/gtest.h>
+
+namespace fs = std::filesystem;
+
+namespace granite::microfrontend::io {
+
+class FileReaderTest : public ::testing::Test {
+protected:
+  void SetUp() override {
+    tempDirectory =
+        fs::temp_directory_path() / "granite_micro_frontend_file_reader_test";
+    fs::create_directories(tempDirectory);
+  }
+
+  void TearDown() override { fs::remove_all(tempDirectory); }
+
+  fs::path createBundle(const std::string &content) const {
+    const auto path = tempDirectory / "remote.hbc";
+    std::ofstream output(path, std::ios::binary);
+    output.write(content.data(), static_cast<std::streamsize>(content.size()));
+    output.close();
+    return path;
+  }
+
+  fs::path tempDirectory;
+};
+
+TEST_F(FileReaderTest, KeepsBundleBytesAfterSourceFileIsDeleted) {
+  const std::string bytecode{"\xc6\x1f\xbc\x03\x00\x01\x00\x02", 8};
+  const auto path = createBundle(bytecode);
+
+  const std::string loadedBytecode = readFileToMemory(path.string());
+  ASSERT_TRUE(fs::remove(path));
+  ASSERT_FALSE(fs::exists(path));
+
+  EXPECT_EQ(loadedBytecode, bytecode);
+}
+
+}

package/android/src/test/java/com/teleport/host/PortalReactRootViewContractTest.kt

@@ -0,0 +1,76 @@
+package com.teleport.host
+
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactRootView
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.common.UIManagerType
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.mockito.Mockito.mock
+import org.mockito.Mockito.verifyNoInteractions
+
+/**
+ * Pins what host apps rely on when they attach their own Fabric root: it renders through Fabric, it
+ * carries the surface id the host allocated, and it reports the JS module name the host selected.
+ * That it stays a [ReactRootView] needs no assertion of its own — `rootViewTag` is the one property
+ * read below that `PortalReactRootView` does not declare, so that read does not compile otherwise.
+ *
+ * The example app used to assert these by matching substrings in `PortalReactRootView.kt`, which
+ * proved nothing about whether the code compiled or behaved. Here the symbols resolve at compile
+ * time and the values come off a constructed instance.
+ *
+ * Three preconditions live outside this file, and all three can break without anyone touching it.
+ *
+ * 1. `testOptions.unitTests.returnDefaultValues = true` in `android/build.gradle`. The superclass
+ *    constructor calls `View.MeasureSpec.makeMeasureSpec` and `setClipChildren`; without the flag the
+ *    first one throws `Method makeMeasureSpec in android.view.View$MeasureSpec not mocked.`
+ *    `GraniteMicroFrontendRuntimeEventRouterTest` needs the flag too, for `android.util.Log`.
+ * 2. The React Native version, which this module does not pin: `build.gradle` declares
+ *    `com.facebook.react:react-android` without one, so today's 0.81.0 comes from the consuming app
+ *    (`examples/portal/package.json`). On 0.81 `ReactRootView.init()` is pure JVM; from 0.82 it also
+ *    reads `enableFontScaleChangesUpdatingLayout`, whose default accessor reaches
+ *    `ReactNativeFeatureFlagsCxxInterop`, whose `<clinit>` loads `react_featureflagsjni` through
+ *    SoLoader. Stubbing that accessor and leaving the flag at its default only moves the failure —
+ *    `init()` then dereferences `getContext()`, which the mockable `android.jar` returns null for.
+ *    This lands in consumer builds as well: the library is autolinked as a Gradle subproject, so a
+ *    host app running `./gradlew test` runs these tests against its own React Native.
+ * 3. Mockito's inline mock maker, the default in mockito-core 5.x. `ThemedReactContext` is `final`,
+ *    so the subclass mock maker cannot stand in for it.
+ */
+class PortalReactRootViewContractTest {
+    private val context = mock(ThemedReactContext::class.java)
+    private val reactHost = mock(ReactHost::class.java)
+
+    private fun createRootView(moduleName: String) =
+        PortalReactRootView(context, reactHost, SURFACE_ID, moduleName)
+
+    @Test
+    fun `renders through Fabric`() {
+        assertEquals(UIManagerType.FABRIC, createRootView("example-controller").uiManagerType)
+    }
+
+    @Test
+    fun `carries the surface id the host allocated`() {
+        assertEquals(SURFACE_ID, createRootView("example-controller").rootViewTag)
+    }
+
+    @Test
+    fun `reports each host's own JS module name rather than one baked-in name`() {
+        assertEquals("example-controller", createRootView("example-controller").jsModuleName)
+        assertEquals("another-controller", createRootView("another-controller").jsModuleName)
+    }
+
+    @Test
+    fun `builds without calling into the context or the host`() {
+        createRootView("example-controller")
+
+        verifyNoInteractions(context, reactHost)
+    }
+
+    private companion object {
+        // Deliberately not 1, 11, 21, ... — ReactRootViewTagGenerator hands those out from the
+        // superclass constructor, so the surface-id assertion would still pass if
+        // PortalReactRootView stopped setting the tag itself.
+        const val SURFACE_ID = 42
+    }
+}