@granite-js/micro-frontend 2.0.0

package/android/src/main/java/com/teleport/portal/PortalView.kt

@@ -0,0 +1,309 @@
+package com.teleport.portal
+
+import android.content.Context
+import android.view.View
+import android.view.ViewGroup
+import com.facebook.common.logging.FLog
+import com.facebook.react.uimanager.StateWrapper
+import com.facebook.react.views.view.ReactViewGroup
+import com.teleport.global.PortalRegistry
+import com.teleport.host.PortalHostView
+import java.util.ArrayList
+
+/**
+ * React/Fabric-owned source that moves its Android child views into a named [PortalHostView].
+ *
+ * Children remain logically owned by this view. They stay attached here while no destination is
+ * available, move to the matching attached host when it appears, and return here when it detaches.
+ */
+class PortalView(
+  context: Context,
+) : ReactViewGroup(context) {
+  private var hostName: String? = null
+  private val layoutStateController = PortalLayoutStateController(this)
+  private val ownChildren: MutableList<View> = ArrayList()
+
+  private val resolvedHost: PortalHostView?
+    get() = PortalRegistry.resolveHost(hostName, this)
+
+  private val isTeleported: Boolean
+    get() = hostName != null && resolvedHost != null
+
+  // region ViewManager methods
+  fun setStateWrapper(wrapper: StateWrapper?) {
+    layoutStateController.setStateWrapper(wrapper)
+    layoutStateController.updateIfNeeded(hostName, resolvedHost)
+  }
+
+  fun setHostName(name: String?) {
+    if (name == hostName) return
+
+    val children = extractChildren()
+
+    hostName?.let { PortalRegistry.unregisterPendingPortal(it, this) }
+
+    hostName = name
+
+    val resolved = name?.let { PortalRegistry.resolveHost(it, this) }
+    if (name != null && resolved == null) {
+      // Rendering in place is a legitimate state — the host may simply not have mounted yet — but
+      // it looks identical to a typo in hostName, and nothing else in this module says which one
+      // happened. Logged here rather than in resolveHost because that runs on every layout pass.
+      FLog.w(
+        TAG,
+        "Portal \"%s\" resolved no attached host; its children stay in the source tree until one registers",
+        name,
+      )
+    }
+    val target: ViewGroup = resolved ?: this
+
+    if (target is PortalHostView) {
+      for (i in children.indices) {
+        val idx = target.nextInsertionIndexForChildAt(i)
+        target.addView(children[i], idx)
+      }
+      ownChildren.addAll(children)
+    } else {
+      for (i in children.indices) {
+        target.addView(children[i], i)
+      }
+    }
+
+    name?.let { PortalRegistry.registerPendingPortal(it, this) }
+    layoutStateController.updateIfNeeded(hostName, resolvedHost)
+  }
+
+  fun cleanup() {
+    hostName?.let { PortalRegistry.unregisterPendingPortal(it, this) }
+    detachOwnChildren()
+    hostName = null
+    layoutStateController.resetIfNeeded()
+    layoutStateController.setStateWrapper(null)
+  }
+  // endregion
+
+  // region Host lifecycle callbacks
+  internal fun onHostChanged() {
+    val host = resolvedHost
+    if (host != null) {
+      // Host appeared (or was replaced). Move children into it, detaching
+      // from their current parent first — that may be `this` (initial mount
+      // or after host loss) or a stale, detached host view.
+      val children: List<View> =
+        if (ownChildren.isEmpty()) extractPhysicalChildren() else detachOwnChildren()
+
+      for (i in children.indices) {
+        val idx = host.nextInsertionIndexForChildAt(i)
+        host.addView(children[i], idx)
+      }
+      ownChildren.addAll(children)
+    } else {
+      // Host went away. Pull children back to ourselves so they remain
+      // attached to a live view tree and React-driven mutations keep working.
+      if (ownChildren.isEmpty()) {
+        layoutStateController.resetIfNeeded()
+        return
+      }
+      val list = detachOwnChildren()
+      FLog.w(
+        TAG,
+        "Portal \"%s\" lost its host; %d child view(s) returned to the source tree",
+        hostName,
+        list.size,
+      )
+      // isTeleported is now false, so super.addView and addView are equivalent;
+      // use super to be explicit that this is a physical re-attach.
+      for (i in list.indices) {
+        super.addView(list[i], i)
+      }
+      layoutStateController.resetIfNeeded()
+    }
+  }
+
+  internal fun onHostLayoutChanged() {
+    layoutStateController.updateIfNeeded(hostName, resolvedHost)
+  }
+  // endregion
+
+  // region Child relocation helpers
+  private fun extractPhysicalChildren(): List<View> {
+    // Collect children first, then remove via super.removeView(child).
+    // Using super.removeViewAt(i) may call our overridden getChildAt(),
+    // which can return null during onHostAvailable (isTeleported flips
+    // before ownChildren is populated), leading to an NPE in
+    // removeViewInternal. super.removeView(View) avoids this by using
+    // indexOfChild without re-fetching the view.
+    val count = super.getChildCount()
+    val children = ArrayList<View>(count)
+    for (i in 0 until count) {
+      super.getChildAt(i)?.let { children.add(it) }
+    }
+    for (child in children) {
+      detachFromParent(child)
+    }
+    return children
+  }
+
+  private fun detachFromParent(child: View) {
+    val parent = child.parent as? ViewGroup ?: return
+    if (parent === this) {
+      super.removeView(child)
+    } else {
+      parent.removeView(child)
+    }
+    if (child.parent === parent) {
+      parent.endViewTransition(child)
+    }
+  }
+
+  /**
+   * Detaches every view in [ownChildren] from its current parent (which may be
+   * `this`, the active host, or a stale/detached host) and clears the list.
+   * Returns the detached views in their original order so the caller can
+   * re-attach them somewhere else.
+   */
+  private fun detachOwnChildren(): List<View> {
+    val list = ArrayList<View>(ownChildren.size)
+    for (child in ownChildren) {
+      if (!list.contains(child)) {
+        list.add(child)
+      }
+    }
+    ownChildren.clear()
+    for (child in list) {
+      detachFromParent(child)
+    }
+    return list
+  }
+
+  private fun extractChildren(): List<View> {
+    // Gather current children (logical if teleported, physical otherwise)
+    return if (isTeleported) detachOwnChildren() else extractPhysicalChildren()
+  }
+
+  /**
+   * Finds the host index of the first next sibling (in [ownChildren]) that is
+   * already present in the host.  Returns -1 when none is found (caller should append).
+   */
+  private fun findNextSiblingHostIndex(
+    host: ViewGroup,
+    ownIndex: Int,
+  ): Int {
+    for (i in (ownIndex + 1) until ownChildren.size) {
+      val sibling = ownChildren[i]
+      val siblingIndex = host.indexOfChild(sibling)
+      if (siblingIndex >= 0) return siblingIndex
+    }
+    return -1
+  }
+  // endregion
+
+  // region Children management
+  override fun getChildCount(): Int =
+    if (isTeleported) {
+      ownChildren.size
+    } else {
+      super.getChildCount()
+    }
+
+  override fun getChildAt(index: Int): View? =
+    if (isTeleported) {
+      ownChildren.getOrNull(index)
+    } else {
+      super.getChildAt(index)
+    }
+
+  override fun addView(
+    child: View,
+    index: Int,
+  ) {
+    if (isTeleported) {
+      val host = resolvedHost
+      ownChildren.add(index, child)
+      if (host != null) {
+        val hostIndex = findNextSiblingHostIndex(host, index)
+        if (hostIndex >= 0) {
+          host.addView(child, hostIndex)
+        } else {
+          host.addView(child)
+        }
+      }
+    } else {
+      super.addView(child, index)
+    }
+  }
+
+  override fun addView(
+    child: View,
+    index: Int,
+    params: LayoutParams,
+  ) {
+    if (isTeleported) {
+      val host = resolvedHost
+      ownChildren.add(index, child)
+      if (host != null) {
+        val hostIndex = findNextSiblingHostIndex(host, index)
+        if (hostIndex >= 0) {
+          host.addView(child, hostIndex)
+        } else {
+          host.addView(child, params)
+        }
+      }
+    } else {
+      super.addView(child, index, params)
+    }
+  }
+
+  override fun removeView(view: View?) {
+    if (view == null) return
+    if (isTeleported) {
+      val host = resolvedHost
+      host?.removeView(view)
+      ownChildren.remove(view)
+    } else {
+      super.removeView(view)
+    }
+  }
+
+  override fun removeViewAt(index: Int) {
+    if (isTeleported) {
+      val host = resolvedHost
+      val view = ownChildren.getOrNull(index)
+      if (view != null) {
+        host?.removeView(view)
+        ownChildren.removeAt(index)
+      }
+    } else {
+      super.removeViewAt(index)
+    }
+  }
+  // endregion
+
+  // region Lifecycle
+  override fun onLayout(
+    changed: Boolean,
+    left: Int,
+    top: Int,
+    right: Int,
+    bottom: Int,
+  ) {
+    super.onLayout(changed, left, top, right, bottom)
+    layoutStateController.updateIfNeeded(hostName, resolvedHost)
+  }
+
+  // endregion
+
+  // region Accessibility
+  // Override to prevent accessibility from trying to include non-descendant children
+  override fun addChildrenForAccessibility(outChildren: ArrayList<View>) {
+    if (!isTeleported) {
+      super.addChildrenForAccessibility(outChildren)
+    }
+    // When teleported, do nothing—children are handled by the host's accessibility tree
+  }
+  // endregion
+
+  private companion object {
+    private const val TAG = "GraniteMicroFrontendPortal"
+  }
+}

package/android/src/main/java/com/teleport/portal/PortalViewManager.kt

@@ -0,0 +1,51 @@
+package com.teleport.portal
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ReactStylesDiffMap
+import com.facebook.react.uimanager.StateWrapper
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.viewmanagers.PortalViewManagerDelegate
+import com.facebook.react.viewmanagers.PortalViewManagerInterface
+import com.facebook.react.views.view.ReactViewGroup
+import com.teleport.managers.TeleportViewManager
+
+@ReactModule(name = PortalViewManager.NAME)
+class PortalViewManager :
+  TeleportViewManager(),
+  PortalViewManagerInterface<ReactViewGroup> {
+  private val delegate = PortalViewManagerDelegate(this)
+
+  override fun getName(): String = NAME
+
+  override fun getDelegate(): ViewManagerDelegate<ReactViewGroup> = delegate
+
+  override fun createTeleportView(context: ThemedReactContext): ReactViewGroup = PortalView(context)
+
+  override fun onDropViewInstance(view: ReactViewGroup) {
+    (view as? PortalView)?.cleanup()
+    super.onDropViewInstance(view)
+  }
+
+  override fun updateState(
+    view: ReactViewGroup,
+    props: ReactStylesDiffMap?,
+    stateWrapper: StateWrapper?,
+  ): Any? {
+    (view as? PortalView)?.setStateWrapper(stateWrapper)
+    return super.updateState(view, props, stateWrapper)
+  }
+
+  @ReactProp(name = "hostName")
+  override fun setHostName(
+    view: ReactViewGroup?,
+    name: String?,
+  ) {
+    (view as? PortalView)?.setHostName(name)
+  }
+
+  companion object {
+    const val NAME = "PortalView"
+  }
+}

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

@@ -0,0 +1,87 @@
+package run.granite.microfrontend
+
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
+import android.os.Looper
+
+class ActivitySessionBinding private constructor(
+    private val sessionId: String,
+    private val application: Application,
+    private var activity: Activity?,
+    private val registration: GraniteMicroFrontendSessionRegistration,
+) : AutoCloseable {
+    private val callbacks = object : Application.ActivityLifecycleCallbacks {
+        override fun onActivityStarted(target: Activity) {
+            if (target === activity) {
+                registration.setVisible(true)
+            }
+        }
+
+        override fun onActivityStopped(target: Activity) {
+            if (target === activity) {
+                registration.setVisible(false)
+            }
+        }
+
+        override fun onActivityDestroyed(target: Activity) {
+            if (target !== activity) {
+                return
+            }
+            // A configuration change destroys the Activity instance but not the destination. Keep
+            // the session registered and drop the instance so the recreated one can rebind to it.
+            if (target.isChangingConfigurations) {
+                activity = null
+                return
+            }
+            close()
+        }
+
+        override fun onActivityCreated(target: Activity, savedInstanceState: Bundle?) = Unit
+        override fun onActivityResumed(target: Activity) = Unit
+        override fun onActivityPaused(target: Activity) = Unit
+        override fun onActivitySaveInstanceState(target: Activity, outState: Bundle) = Unit
+    }
+
+    init {
+        application.registerActivityLifecycleCallbacks(callbacks)
+    }
+
+    override fun close() {
+        synchronized(boundBindings) {
+            if (boundBindings[sessionId] !== this) {
+                return
+            }
+            boundBindings.remove(sessionId)
+        }
+        activity = null
+        application.unregisterActivityLifecycleCallbacks(callbacks)
+        registration.closeApp()
+        registration.close()
+    }
+
+    companion object {
+        private val boundBindings = mutableMapOf<String, ActivitySessionBinding>()
+
+        @JvmStatic
+        fun bind(
+            activity: Activity,
+            sessionId: String,
+            appName: String,
+            scheme: String,
+        ): ActivitySessionBinding = synchronized(boundBindings) {
+            check(Looper.myLooper() == Looper.getMainLooper()) {
+                "ActivitySessionBinding.bind must be called on the main thread"
+            }
+            boundBindings[sessionId]?.also { binding ->
+                binding.activity = activity
+                return@synchronized binding
+            }
+            val registration = GraniteMicroFrontendRuntimeHost.registerSession(sessionId)
+            ActivitySessionBinding(sessionId, activity.application, activity, registration).also { binding ->
+                boundBindings[sessionId] = binding
+                registration.openApp(appName, scheme)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,46 @@
+package run.granite.microfrontend
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.common.annotations.FrameworkAPI
+import java.io.File
+import java.io.FileNotFoundException
+import java.io.IOException
+
+@OptIn(FrameworkAPI::class)
+internal class BundleEvaluator(
+    private val reactContext: ReactApplicationContext,
+) {
+    /**
+     * Evaluates a bundle on the JSI runtime reached through `javaScriptContextHolder`. That holder
+     * is a framework-internal API, so this path is only verified against the React Native version
+     * this package is developed against (`catalog:react-native`, currently 0.84.0).
+     * `peerDependencies` declares `*`; a host on another version should re-verify it.
+     */
+    private external fun evaluateFileSync(
+        runtimePointer: Long,
+        filePath: String,
+        sourceUrl: String,
+    )
+
+    @Throws(FileNotFoundException::class, IOException::class)
+    fun evaluateFile(filePath: String) {
+        val file = File(filePath)
+        require(file.isAbsolute) { "Bundle path must be absolute: $filePath" }
+        if (!file.exists()) {
+            throw FileNotFoundException("Bundle file does not exist: $filePath")
+        }
+        if (!file.canRead()) {
+            throw IOException("Bundle file is not readable: $filePath")
+        }
+
+        val runtimePointer = reactContext.javaScriptContextHolder?.get()
+            ?: throw IllegalStateException("JavaScript runtime is unavailable")
+        evaluateFileSync(runtimePointer, filePath, file.toURI().toString())
+    }
+
+    private companion object {
+        init {
+            System.loadLibrary("granite-micro-frontend")
+        }
+    }
+}

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

@@ -0,0 +1,62 @@
+package run.granite.microfrontend
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+
+sealed interface GraniteMicroFrontendEvent {
+    fun toWritableMap(): WritableMap
+
+    data class PreloadApp(
+        val appName: String,
+    ) : GraniteMicroFrontendEvent {
+        override fun toWritableMap(): WritableMap = eventMap(
+            name = "preloadApp",
+            params = Arguments.createMap().apply {
+                putString("appName", appName)
+            },
+        )
+    }
+
+    data class OpenApp(
+        val sessionId: String,
+        val appName: String,
+        val scheme: String,
+    ) : GraniteMicroFrontendEvent {
+        override fun toWritableMap(): WritableMap = eventMap(
+            name = "openApp",
+            params = Arguments.createMap().apply {
+                putString("sessionId", sessionId)
+                putString("appName", appName)
+                putString("scheme", scheme)
+            },
+        )
+    }
+
+    data class CloseApp(
+        val sessionId: String,
+    ) : GraniteMicroFrontendEvent {
+        override fun toWritableMap(): WritableMap = eventMap(
+            name = "closeApp",
+            params = Arguments.createMap().apply { putString("sessionId", sessionId) },
+        )
+    }
+
+    data class SessionVisibilityChanged(
+        val sessionId: String,
+        val isVisible: Boolean,
+    ) : GraniteMicroFrontendEvent {
+        override fun toWritableMap(): WritableMap = eventMap(
+            name = "sessionVisibilityChanged",
+            params = Arguments.createMap().apply {
+                putString("sessionId", sessionId)
+                putBoolean("isVisible", isVisible)
+            },
+        )
+    }
+}
+
+private fun eventMap(name: String, params: WritableMap): WritableMap =
+    Arguments.createMap().apply {
+        putString("name", name)
+        putMap("params", params)
+    }