@nebula-rn/host 0.0.1

package/android/src/main/java/com/hectorzhuang/nebula/NebulaRouter.kt

@@ -0,0 +1,300 @@
+package com.hectorzhuang.nebula
+
+import android.app.Activity
+import android.content.Intent
+import android.os.Bundle
+import android.widget.FrameLayout
+import com.facebook.react.interfaces.fabric.ReactSurface
+import java.lang.ref.WeakReference
+import java.util.concurrent.CopyOnWriteArrayList
+
+object NebulaRouter {
+    private const val MINIAPP_LOADING_MODULE = "NebulaInternalMiniappLoading"
+    const val LOADING_EXIT_ANIMATION_MS = 240L
+
+    @Volatile
+    private var intentionalLoadingDelayMs = 0L
+    @Volatile
+    private var enterContentDelayMs = 0L
+
+    fun setMiniappLoadingDelay(delayMs: Long) {
+        intentionalLoadingDelayMs = delayMs.coerceAtLeast(0L)
+    }
+
+    fun setMiniappLoadingEnterContentDelay(delayMs: Long) {
+        enterContentDelayMs = delayMs.coerceAtLeast(0L)
+    }
+
+    private val activityRefs = CopyOnWriteArrayList<WeakReference<NebulaActivity>>()
+
+    // Tracks loading overlays attached to caller activities, keyed by appId.
+    // The overlay lives in the caller's window while NebulaActivity is starting.
+    private data class PendingOverlay(
+        val callerActivity: WeakReference<Activity>,
+        val overlayHost: FrameLayout,
+        val reactSurface: ReactSurface,
+    )
+
+    private val pendingOverlays = CopyOnWriteArrayList<Pair<String, PendingOverlay>>()
+
+    fun register(activity: NebulaActivity) {
+        cleanup()
+        activityRefs.add(WeakReference(activity))
+    }
+
+    fun unregister(activity: NebulaActivity) {
+        activityRefs.removeAll { it.get() == null || it.get() === activity }
+    }
+
+    fun openApp(
+        activity: Activity,
+        appId: String,
+        routePath: String,
+        initialProps: Map<String, Any?>
+    ) {
+        val installedApp = NebulaConfig.getInstalledApp(appId)
+        val isProduction = installedApp?.mode?.equals("production", ignoreCase = true) == true
+        val enterDelay = enterContentDelayMs
+
+        val launchActivity = {
+            activity.startActivity(
+                NebulaActivity.createIntent(
+                    activity = activity,
+                    appId = appId,
+                    routePath = routePath,
+                    routeUrl = buildRouteUrl(appId, routePath),
+                    initialProps = initialProps,
+                ),
+            )
+        }
+
+        if (isProduction && enterDelay > 0L) {
+            // 1. Attach loading overlay to caller's window decor view BEFORE starting NebulaActivity.
+            val overlay = attachLoadingOverlayToCallerWindow(activity, appId, installedApp!!)
+            if (overlay != null) {
+                // 2. Wait enterContentDelayMs, then launch NebulaActivity.
+                activity.window.decorView.postDelayed({
+                    NebulaAppManager.startHost(appId) {
+                        launchActivity()
+                    }
+                }, enterDelay)
+                return
+            }
+        }
+
+        // Pre-warm the ReactHostImpl so the ReactInstance is ready before NebulaActivity is created.
+        // onReactContextInitialized is always called on the UI thread.
+        NebulaAppManager.startHost(appId) {
+            launchActivity()
+        }
+    }
+
+    /**
+     * Called by NebulaActivity once its first frame is drawn and ready.
+     * Dismisses the loading overlay that was attached to the caller's window.
+     */
+    fun onMiniappContentReady(appId: String) {
+        val iterator = pendingOverlays.iterator()
+        while (iterator.hasNext()) {
+            val (id, overlay) = iterator.next()
+            if (id == appId) {
+                pendingOverlays.remove(id to overlay)
+                dismissOverlay(overlay)
+                break
+            }
+        }
+    }
+
+    private fun attachLoadingOverlayToCallerWindow(
+        callerActivity: Activity,
+        appId: String,
+        installedApp: NebulaInstalledApp,
+    ): PendingOverlay? {
+        val decorView = callerActivity.window.decorView as? FrameLayout ?: return null
+        val hostReactHost =
+            runCatching { NebulaHost.resolveHostReactHost(callerActivity.application) }
+                .getOrNull() ?: return null
+
+        val overlayHost = FrameLayout(callerActivity).apply {
+            layoutParams = FrameLayout.LayoutParams(
+                FrameLayout.LayoutParams.MATCH_PARENT,
+                FrameLayout.LayoutParams.MATCH_PARENT,
+            )
+            isClickable = true
+            isFocusable = true
+        }
+
+        val surface = hostReactHost.createSurface(
+            callerActivity,
+            MINIAPP_LOADING_MODULE,
+            Bundle().apply {
+                putString("appId", appId)
+                putString("mode", installedApp.mode)
+            },
+        )
+        surface.start()
+        surface.view?.let { view ->
+            overlayHost.addView(
+                view,
+                FrameLayout.LayoutParams(
+                    FrameLayout.LayoutParams.MATCH_PARENT,
+                    FrameLayout.LayoutParams.MATCH_PARENT,
+                ),
+            )
+        }
+
+        decorView.addView(overlayHost)
+        decorView.bringChildToFront(overlayHost)
+
+        val pending = PendingOverlay(
+            callerActivity = WeakReference(callerActivity),
+            overlayHost = overlayHost,
+            reactSurface = surface,
+        )
+        pendingOverlays.add(appId to pending)
+        return pending
+    }
+
+    private fun dismissOverlay(overlay: PendingOverlay) {
+        val totalDelay = intentionalLoadingDelayMs + LOADING_EXIT_ANIMATION_MS
+        val caller = overlay.callerActivity.get() ?: run {
+            overlay.reactSurface.stop()
+            overlay.reactSurface.clear()
+            return
+        }
+        caller.runOnUiThread {
+            caller.window.decorView.postDelayed({
+                overlay.reactSurface.stop()
+                overlay.reactSurface.clear()
+                (overlay.overlayHost.parent as? FrameLayout)?.removeView(overlay.overlayHost)
+            }, totalDelay)
+        }
+    }
+
+    fun navigateToURL(url: String, fromAppId: String): Result<Unit> {
+        val source = currentActivity(fromAppId)
+            ?: return Result.failure(IllegalStateException("No active page"))
+        val parsed = parseUrl(url, fromAppId)
+        NebulaManifestManager.getComponentName(parsed.appId, parsed.routePath)
+            ?: return Result.failure(IllegalArgumentException(
+                "No component registered for route '${parsed.routePath}' in app '${parsed.appId}'"
+            ))
+        source.startActivity(
+            NebulaActivity.createIntent(
+                activity = source,
+                appId = parsed.appId,
+                routePath = parsed.routePath,
+                routeUrl = parsed.routeUrl,
+                initialProps = parsed.params,
+            ),
+        )
+        return Result.success(Unit)
+    }
+
+    fun redirectToURL(url: String, fromAppId: String): Result<Unit> {
+        val source = currentActivity(fromAppId)
+            ?: return Result.failure(IllegalStateException("No active page"))
+        val parsed = parseUrl(url, fromAppId)
+        NebulaManifestManager.getComponentName(parsed.appId, parsed.routePath)
+            ?: return Result.failure(IllegalArgumentException(
+                "No component registered for route '${parsed.routePath}' in app '${parsed.appId}'"
+            ))
+        source.startActivity(
+            NebulaActivity.createIntent(
+                activity = source,
+                appId = parsed.appId,
+                routePath = parsed.routePath,
+                routeUrl = parsed.routeUrl,
+                initialProps = parsed.params,
+            ),
+        )
+        source.finish()
+        return Result.success(Unit)
+    }
+
+    fun reLaunchURL(url: String, fromAppId: String): Result<Unit> {
+        val source = currentActivity(fromAppId)
+            ?: return Result.failure(IllegalStateException("No active page"))
+        val parsed = parseUrl(url, fromAppId)
+        NebulaManifestManager.getComponentName(parsed.appId, parsed.routePath)
+            ?: return Result.failure(IllegalArgumentException(
+                "No component registered for route '${parsed.routePath}' in app '${parsed.appId}'"
+            ))
+        val intent =
+            NebulaActivity.createIntent(
+                activity = source,
+                appId = parsed.appId,
+                routePath = parsed.routePath,
+                routeUrl = parsed.routeUrl,
+                initialProps = parsed.params,
+            ).apply {
+                addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+            }
+        source.startActivity(intent)
+        activitiesForApp(parsed.appId).forEach { existing ->
+            if (existing !== source) {
+                existing.finish()
+            }
+        }
+        source.finish()
+        return Result.success(Unit)
+    }
+
+    fun navigateBack(fromAppId: String, delta: Int): Result<Unit> {
+        val activities = activitiesForApp(fromAppId)
+        if (activities.isEmpty()) {
+            return Result.failure(IllegalStateException("No active page"))
+        }
+        activities.takeLast(delta.coerceAtLeast(1)).forEach { it.finish() }
+        return Result.success(Unit)
+    }
+
+    fun closeApp(appId: String): Result<Unit> {
+        val target =
+            currentActivity(appId) ?: return Result.failure(IllegalStateException("No active page"))
+        target.finish()
+        return Result.success(Unit)
+    }
+
+    fun updatePageStyle(appId: String, style: Map<String, Any?>): Result<Unit> {
+        val target =
+            currentActivity(appId) ?: return Result.failure(IllegalStateException("No active page"))
+        target.updatePageStyle(style)
+        return Result.success(Unit)
+    }
+
+    private fun currentActivity(appId: String): NebulaActivity? =
+        activitiesForApp(appId).lastOrNull()
+
+    private fun activitiesForApp(appId: String): List<NebulaActivity> {
+        cleanup()
+        return activityRefs.mapNotNull { it.get() }.filter { it.appId == appId && !it.isFinishing }
+    }
+
+    private fun cleanup() {
+        activityRefs.removeAll { it.get() == null }
+    }
+
+    private fun buildRouteUrl(appId: String, routePath: String): String {
+        val normalizedRoute = NebulaManifestManager.normalizeRoute(routePath)
+        return "nebula://$appId${if (normalizedRoute == "/") "" else normalizedRoute}"
+    }
+
+    private fun parseUrl(url: String, fallbackAppId: String): ParsedNebulaUrl {
+        val uri = android.net.Uri.parse(url)
+        val appId = uri.host?.takeIf { it.isNotBlank() } ?: fallbackAppId
+        val routePath = NebulaManifestManager.normalizeRoute(uri.path)
+        val params = linkedMapOf<String, Any?>()
+        uri.queryParameterNames.forEach { key ->
+            params[key] = uri.getQueryParameter(key)
+        }
+        return ParsedNebulaUrl(appId, routePath, url, params)
+    }
+}
+
+private data class ParsedNebulaUrl(
+    val appId: String,
+    val routePath: String,
+    val routeUrl: String,
+    val params: Map<String, Any?>,
+)

package/ios/Nebula/NebulaAppManager.swift

@@ -0,0 +1,355 @@
+//
+//  NebulaAppManager.swift
+//  SuperApp - Nebula Mini-App Container
+//
+//  Mini-app preload manager with lifecycle control
+//
+
+import Foundation
+import UIKit
+import React
+import React_RCTAppDelegate
+import ReactAppDependencyProvider
+
+private final class NebulaPreloadReactDelegate: RCTDefaultReactNativeFactoryDelegate {
+    private let miniBundleURL: URL
+
+    init(bundleURL: URL) {
+        self.miniBundleURL = bundleURL
+        super.init()
+    }
+
+    override func bundleURL() -> URL? {
+        return miniBundleURL
+    }
+}
+
+/// Thread-safe manager for a single preloaded mini-app root view
+@objc public final class NebulaAppManager: NSObject {
+    
+    // MARK: - Singleton
+    
+    @objc public static let shared = NebulaAppManager()
+    
+    // MARK: - Properties
+    
+    private let queue = DispatchQueue(label: "com.nebula.appmanager", attributes: .concurrent)
+    private var preloadedAppId: String?
+    private var preloadedView: UIView?
+    private var preloadedFactory: RCTReactNativeFactory?
+    private var preloadedDelegate: NebulaPreloadReactDelegate?
+    private var preloadContainer: UIView?
+    private var activeFactories: [String: RCTReactNativeFactory] = [:]
+    private var activeFactoryDelegates: [String: NebulaPreloadReactDelegate] = [:]
+    private var activeFactoryRefCounts: [String: Int] = [:]
+    private var pendingPreloadAppId: String?
+    private var preloadGeneration: UInt64 = 0
+    private let semaphore = DispatchSemaphore(value: 1)
+
+    private func removeViewOnMain(_ view: UIView?) {
+        guard let view = view else { return }
+        if Thread.isMainThread {
+            view.removeFromSuperview()
+        } else {
+            DispatchQueue.main.async {
+                view.removeFromSuperview()
+            }
+        }
+    }
+
+    // MARK: - Initialization
+    
+    private override init() {
+        super.init()
+        setupPreloadContainer()
+    }
+    
+    private func setupPreloadContainer() {
+        DispatchQueue.main.async {
+            guard let window = UIApplication.shared.keyWindow else {
+                print("[Nebula] Warning: Cannot setup preload container - no key window")
+                return
+            }
+            
+            let container = UIView()
+            container.backgroundColor = .clear
+            container.isUserInteractionEnabled = false
+            container.frame = window.bounds
+            container.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+            
+            // Insert at the very bottom layer of the key window
+            window.insertSubview(container, at: 0)
+            
+            self.semaphore.wait()
+            self.preloadContainer = container
+            self.semaphore.signal()
+            
+            print("[Nebula] Preload container initialized at bottom layer")
+        }
+    }
+    
+    // MARK: - Public API
+    
+    /// Warm-up: preload a mini-app root view for faster startup
+    @objc public func warmUp(appId: String) {
+        preloadRootView(for: appId, moduleName: "NebulaApp", initialProps: nil)
+    }
+
+    /// Preload root view with custom module name and initial props
+    @objc public func preloadRootView(for appId: String,
+                                      moduleName: String = "NebulaApp",
+                                      initialProps: [String: Any]? = nil) {
+        let bundleURL: URL
+        if let devURL = NebulaConfig.shared.devURL(for: appId) {
+            bundleURL = devURL
+        } else if let bundlePath = NebulaConfig.shared.bundlePath(for: appId) {
+            bundleURL = URL(fileURLWithPath: bundlePath)
+        } else {
+            print("[Nebula] Warm-up skipped for \(appId): bundle not found")
+            return
+        }
+
+        // Clear any existing preload cache before creating new one (single-slot cache)
+        let generation: UInt64
+        var staleViewToRemove: UIView?
+        semaphore.wait()
+        preloadGeneration &+= 1
+        generation = preloadGeneration
+        pendingPreloadAppId = appId
+        if preloadedAppId != nil {
+            staleViewToRemove = preloadedView
+            preloadedAppId = nil
+            preloadedView = nil
+            preloadedFactory = nil
+            print("[Nebula] Cleared existing preload cache before preloading \(appId)")
+        }
+        semaphore.signal()
+        removeViewOnMain(staleViewToRemove)
+
+        DispatchQueue.main.async {
+            self.semaphore.wait()
+            let isCanceledBeforeCreate = (self.preloadGeneration != generation) || (self.pendingPreloadAppId != appId)
+            self.semaphore.signal()
+            if isCanceledBeforeCreate {
+                print("[Nebula] Skipped stale preload task for \(appId)")
+                return
+            }
+
+            let delegate = NebulaPreloadReactDelegate(bundleURL: bundleURL)
+            delegate.dependencyProvider = RCTAppDependencyProvider()
+            let factory = RCTReactNativeFactory(delegate: delegate)
+
+            var props: [String: Any] = [
+                "appId": appId,
+                "sandboxPath": NebulaConfig.shared.sandboxPath(for: appId)
+            ]
+            if let initialProps = initialProps {
+                props.merge(initialProps) { _, new in new }
+            }
+
+            let rootView = factory.rootViewFactory.view(
+                withModuleName: moduleName,
+                initialProperties: props
+            )
+            
+            rootView.backgroundColor = .systemBackground
+
+            self.semaphore.wait()
+            let container = self.preloadContainer
+            self.semaphore.signal()
+
+            // Mount preloaded view to global bottom-layer container
+            guard let container = container else {
+                print("[Nebula] Warning: Preload container not ready, view not mounted")
+                self.semaphore.wait()
+                if self.preloadGeneration != generation || self.pendingPreloadAppId != appId {
+                    self.semaphore.signal()
+                    print("[Nebula] Dropped stale preload cache for \(appId) before store")
+                    return
+                }
+                self.preloadedAppId = appId
+                self.preloadedFactory = factory
+                self.preloadedDelegate = delegate
+                self.preloadedView = rootView
+                self.pendingPreloadAppId = nil
+                self.semaphore.signal()
+                print("[Nebula] Preloaded root view for \(appId), module=\(moduleName) (not mounted)")
+                return
+            }
+
+            self.semaphore.wait()
+            let isStaleBeforeMount = (self.preloadGeneration != generation) || (self.pendingPreloadAppId != appId)
+            self.semaphore.signal()
+            if isStaleBeforeMount {
+                print("[Nebula] Skipped mounting stale preload view for \(appId)")
+                return
+            }
+
+            rootView.frame = container.bounds
+            rootView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+            
+            // Ensure preload container is clean before adding new view
+            for subview in container.subviews {
+                subview.removeFromSuperview()
+            }
+            
+            container.addSubview(rootView)
+            
+            // Force layout pass to ensure RN rendering pipeline is triggered
+            rootView.setNeedsLayout()
+            rootView.layoutIfNeeded()
+
+            self.semaphore.wait()
+            if self.preloadGeneration != generation || self.pendingPreloadAppId != appId {
+                self.semaphore.signal()
+                print("[Nebula] Dropped stale preloaded root view for \(appId) before cache commit")
+                return
+            }
+            self.preloadedAppId = appId
+            self.preloadedFactory = factory
+            self.preloadedDelegate = delegate
+            self.preloadedView = rootView
+            self.pendingPreloadAppId = nil
+            self.semaphore.signal()
+
+            print("[Nebula] Preloaded root view for \(appId), module=\(moduleName) (mounted at bottom layer)")
+        }
+    }
+
+    /// Consume and remove the preloaded root view from bottom layer (single-use)
+    @objc public func consumePreloadedRootView(for appId: String) -> UIView? {
+        semaphore.wait()
+        guard preloadedAppId == appId else {
+            // If preload is still pending for this app, cancel it to avoid stale bottom-layer mount.
+            if pendingPreloadAppId == appId {
+                preloadGeneration &+= 1
+                pendingPreloadAppId = nil
+                print("[Nebula] Canceled pending preload for \(appId) while opening app")
+            }
+            semaphore.signal()
+            return nil
+        }
+
+        let view = preloadedView
+
+        if let factory = preloadedFactory {
+            // Keep factory alive while container is using the consumed rootView.
+            activeFactories[appId] = factory
+            if let delegate = preloadedDelegate {
+                activeFactoryDelegates[appId] = delegate
+            }
+            activeFactoryRefCounts[appId, default: 0] += 1
+        }
+        preloadedAppId = nil
+        preloadedView = nil
+        preloadedFactory = nil
+        preloadedDelegate = nil
+        pendingPreloadAppId = nil
+        semaphore.signal()
+        // Remove from bottom-layer preload container on main thread.
+        removeViewOnMain(view)
+        return view
+    }
+
+    @objc public func acquireFactory(for appId: String,
+                                     bundleURL: URL) -> RCTReactNativeFactory {
+        semaphore.wait()
+        if let existingFactory = activeFactories[appId] {
+            activeFactoryRefCounts[appId, default: 0] += 1
+            semaphore.signal()
+            return existingFactory
+        }
+        semaphore.signal()
+
+        let delegate = NebulaPreloadReactDelegate(bundleURL: bundleURL)
+        delegate.dependencyProvider = RCTAppDependencyProvider()
+        let factory = RCTReactNativeFactory(delegate: delegate)
+
+        semaphore.wait()
+        if let existingFactory = activeFactories[appId] {
+            activeFactoryRefCounts[appId, default: 0] += 1
+            semaphore.signal()
+            return existingFactory
+        }
+
+        activeFactories[appId] = factory
+        activeFactoryDelegates[appId] = delegate
+        activeFactoryRefCounts[appId] = 1
+        semaphore.signal()
+        return factory
+    }
+
+    /// Release runtime resources held for a consumed preloaded view.
+    @objc public func releaseConsumedResources(appId: String) {
+        semaphore.wait()
+        let nextCount = max(0, (activeFactoryRefCounts[appId] ?? 0) - 1)
+        if nextCount == 0 {
+            activeFactoryRefCounts.removeValue(forKey: appId)
+            activeFactories.removeValue(forKey: appId)
+            activeFactoryDelegates.removeValue(forKey: appId)
+        } else {
+            activeFactoryRefCounts[appId] = nextCount
+        }
+        semaphore.signal()
+    }
+    
+    /// Invalidate and remove preload cache for one mini-app
+    @objc public func invalidate(appId: String) {
+        queue.async(flags: .barrier) { [weak self] in
+            guard let self = self else { return }
+
+            var staleViewToRemove: UIView?
+            self.semaphore.wait()
+            if self.preloadedAppId == appId {
+                staleViewToRemove = self.preloadedView
+                self.preloadedAppId = nil
+                self.preloadedView = nil
+                self.preloadedFactory = nil
+                self.preloadedDelegate = nil
+            }
+            if self.pendingPreloadAppId == appId {
+                self.pendingPreloadAppId = nil
+                self.preloadGeneration &+= 1
+            }
+            self.activeFactoryRefCounts.removeValue(forKey: appId)
+            self.activeFactories.removeValue(forKey: appId)
+            self.activeFactoryDelegates.removeValue(forKey: appId)
+            self.semaphore.signal()
+
+            self.removeViewOnMain(staleViewToRemove)
+            print("[Nebula] Invalidated preload cache for \(appId)")
+        }
+    }
+    
+    /// Invalidate all preload caches
+    @objc public func invalidateAll() {
+        queue.async(flags: .barrier) { [weak self] in
+            guard let self = self else { return }
+
+            var staleViewToRemove: UIView?
+            self.semaphore.wait()
+            staleViewToRemove = self.preloadedView
+            self.preloadedAppId = nil
+            self.preloadedView = nil
+            self.preloadedFactory = nil
+            self.preloadedDelegate = nil
+            self.pendingPreloadAppId = nil
+            self.preloadGeneration &+= 1
+            self.activeFactoryRefCounts.removeAll()
+            self.activeFactories.removeAll()
+            self.activeFactoryDelegates.removeAll()
+            self.semaphore.signal()
+
+            self.removeViewOnMain(staleViewToRemove)
+            print("[Nebula] Invalidated all preload caches")
+        }
+    }
+
+    /// Check whether a preloaded root view is available
+    @objc public func hasPreloadedRootView(appId: String) -> Bool {
+        semaphore.wait()
+        let result = (preloadedAppId == appId) && (preloadedView != nil)
+        semaphore.signal()
+        return result
+    }
+}