From 171dc28bd65a9e240bfd5d2b1646d498bc2d9e20 Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Fri, 15 May 2026 13:31:15 +0500 Subject: [PATCH 1/2] feat: add method to clear navigation delegate --- .../brownfield/android/example/MainActivity.kt | 13 ++++++++++++- .../BrownfieldAppleApp.swift | 17 +++++++++++++---- .../BrownfieldNavigationManager.kt | 4 ++++ .../ios/BrownfieldNavigationManager.swift | 4 ++++ 4 files changed, 33 insertions(+), 5 deletions(-) diff --git a/apps/AndroidApp/app/src/main/java/com/callstack/brownfield/android/example/MainActivity.kt b/apps/AndroidApp/app/src/main/java/com/callstack/brownfield/android/example/MainActivity.kt index 0f8fa79c..b99731b6 100644 --- a/apps/AndroidApp/app/src/main/java/com/callstack/brownfield/android/example/MainActivity.kt +++ b/apps/AndroidApp/app/src/main/java/com/callstack/brownfield/android/example/MainActivity.kt @@ -41,10 +41,21 @@ class MainActivity : AppCompatActivity(), BrownfieldNavigationDelegate { ReactNativeHostManager.onConfigurationChanged(application, newConfig) } + override fun onResume() { + super.onResume() + // Own Brownfield navigation only while this activity is foregrounded. + BrownfieldNavigationManager.setDelegate(this) + } + + override fun onPause() { + // Release ownership before another host can become the active delegate. + BrownfieldNavigationManager.clearDelegate() + super.onPause() + } + override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(null) enableEdgeToEdge() - BrownfieldNavigationManager.setDelegate(this) if (savedInstanceState == null) { ReactNativeHostManager.initialize(application) { diff --git a/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift b/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift index 09295b42..d24a0082 100644 --- a/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift +++ b/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift @@ -7,6 +7,7 @@ import BrownfieldNavigation class AppDelegate: NSObject, UIApplicationDelegate { var window: UIWindow? + private let navigationDelegate = RNNavigationDelegate() func application( _ application: UIApplication, @@ -22,6 +23,18 @@ class AppDelegate: NSObject, UIApplicationDelegate { func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { return ReactNativeBrownfield.shared.application(application, willFinishLaunchingWithOptions: launchOptions) } + + func applicationDidBecomeActive(_ application: UIApplication) { + // Reclaim delegate ownership before RN can issue navigation requests. + BrownfieldNavigationManager.shared.setDelegate( + navigationDelegate: navigationDelegate + ) + } + + func applicationWillResignActive(_ application: UIApplication) { + // Release the delegate so another native host can register cleanly. + BrownfieldNavigationManager.shared.clearDelegate() + } } public class RNNavigationDelegate: BrownfieldNavigationDelegate { @@ -83,10 +96,6 @@ struct BrownfieldAppleApp: App { print("React Native has been loaded") } - BrownfieldNavigationManager.shared.setDelegate( - navigationDelegate: RNNavigationDelegate() - ) - #if USE_EXPO_HOST ReactNativeBrownfield.shared.ensureExpoModulesProvider() #endif diff --git a/packages/brownfield-navigation/android/src/main/java/com/callstack/nativebrownfieldnavigation/BrownfieldNavigationManager.kt b/packages/brownfield-navigation/android/src/main/java/com/callstack/nativebrownfieldnavigation/BrownfieldNavigationManager.kt index da85becb..f710cc56 100644 --- a/packages/brownfield-navigation/android/src/main/java/com/callstack/nativebrownfieldnavigation/BrownfieldNavigationManager.kt +++ b/packages/brownfield-navigation/android/src/main/java/com/callstack/nativebrownfieldnavigation/BrownfieldNavigationManager.kt @@ -7,6 +7,10 @@ object BrownfieldNavigationManager { this.navigationDelegate = navigationDelegate } + fun clearDelegate() { + navigationDelegate = null + } + fun getDelegate(): BrownfieldNavigationDelegate { return navigationDelegate ?: throw IllegalStateException("BrownfieldNavigation delegate is not set.") diff --git a/packages/brownfield-navigation/ios/BrownfieldNavigationManager.swift b/packages/brownfield-navigation/ios/BrownfieldNavigationManager.swift index 33e82419..c97ba009 100644 --- a/packages/brownfield-navigation/ios/BrownfieldNavigationManager.swift +++ b/packages/brownfield-navigation/ios/BrownfieldNavigationManager.swift @@ -11,6 +11,10 @@ public class BrownfieldNavigationManager: NSObject { public func setDelegate(navigationDelegate: BrownfieldNavigationDelegate) { self.navigationDelegate = navigationDelegate } + + @objc public func clearDelegate() { + navigationDelegate = nil + } @objc public func getDelegate() -> BrownfieldNavigationDelegate { guard let delegate = navigationDelegate else { From 721df6e7c65c880146fbe2a56d9ff5380da87352 Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Fri, 15 May 2026 15:40:56 +0500 Subject: [PATCH 2/2] docs: update --- .../BrownfieldAppleApp.swift | 52 ++++++++--- .../components/ContentView.swift | 2 +- .../native-integration.mdx | 90 ++++++++++++++++--- .../references/native-android-integration.md | 17 +++- .../references/native-ios-integration.md | 53 ++++++++++- 5 files changed, 177 insertions(+), 37 deletions(-) diff --git a/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift b/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift index d24a0082..3e994626 100644 --- a/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift +++ b/apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift @@ -7,7 +7,6 @@ import BrownfieldNavigation class AppDelegate: NSObject, UIApplicationDelegate { var window: UIWindow? - private let navigationDelegate = RNNavigationDelegate() func application( _ application: UIApplication, @@ -23,18 +22,6 @@ class AppDelegate: NSObject, UIApplicationDelegate { func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { return ReactNativeBrownfield.shared.application(application, willFinishLaunchingWithOptions: launchOptions) } - - func applicationDidBecomeActive(_ application: UIApplication) { - // Reclaim delegate ownership before RN can issue navigation requests. - BrownfieldNavigationManager.shared.setDelegate( - navigationDelegate: navigationDelegate - ) - } - - func applicationWillResignActive(_ application: UIApplication) { - // Release the delegate so another native host can register cleanly. - BrownfieldNavigationManager.shared.clearDelegate() - } } public class RNNavigationDelegate: BrownfieldNavigationDelegate { @@ -105,7 +92,44 @@ struct BrownfieldAppleApp: App { var body: some Scene { WindowGroup { - ContentView() + RootContentView(appDelegate: appDelegate) + } + } +} + +private struct RootContentView: View { + @Environment(\.scenePhase) private var scenePhase + + let appDelegate: AppDelegate + + var body: some View { + ContentView() + .onAppear { + syncNavigationDelegate(for: scenePhase) + } + .onChange(of: scenePhase) { newPhase in + syncNavigationDelegate(for: newPhase) + } + } + + private func registerNavigationDelegate() { + BrownfieldNavigationManager.shared.setDelegate( + navigationDelegate: RNNavigationDelegate() + ) + } + + private func clearNavigationDelegate() { + BrownfieldNavigationManager.shared.clearDelegate() + } + + private func syncNavigationDelegate(for phase: ScenePhase) { + switch phase { + case .active: + registerNavigationDelegate() + case .inactive, .background: + clearNavigationDelegate() + @unknown default: + clearNavigationDelegate() } } } diff --git a/apps/AppleApp/Brownfield Apple App/components/ContentView.swift b/apps/AppleApp/Brownfield Apple App/components/ContentView.swift index 05f0766b..99ee167e 100644 --- a/apps/AppleApp/Brownfield Apple App/components/ContentView.swift +++ b/apps/AppleApp/Brownfield Apple App/components/ContentView.swift @@ -24,7 +24,7 @@ struct ContentView: View { MessagesView() ReactNativeView( - moduleName: "main", + moduleName: "RNApp", initialProperties: [ "nativeOsVersionLabel": "\(UIDevice.current.systemName) \(UIDevice.current.systemVersion)" diff --git a/docs/docs/docs/api-reference/brownfield-navigation/native-integration.mdx b/docs/docs/docs/api-reference/brownfield-navigation/native-integration.mdx index 01f374ca..72965160 100644 --- a/docs/docs/docs/api-reference/brownfield-navigation/native-integration.mdx +++ b/docs/docs/docs/api-reference/brownfield-navigation/native-integration.mdx @@ -1,6 +1,10 @@ # Native Integration -After codegen, implement the generated delegate interface in your host app and register it before JavaScript uses the module. +After codegen, implement the generated delegate interface in your host app and register it before JavaScript uses the module. Clear that delegate when the host stops owning Brownfield navigation so another native owner can safely register. + +On both platforms, the native manager API is intentionally explicit: use `setDelegate(...)` to claim ownership, `clearDelegate()` to release it, and rely on `getDelegate()` failing fast if no active host has registered yet. + +Do not treat the delegate as an app-lifetime singleton unless your app truly has only one native owner for Brownfield navigation. The intended contract is ownership-based: register when a host becomes responsible for Brownfield navigation, then clear when that responsibility moves elsewhere or the host becomes inactive. ## Pre-Requisite: @@ -31,21 +35,26 @@ class MainActivity : AppCompatActivity(), BrownfieldNavigationDelegate { } ``` -### 2) Register the delegate during startup +### 2) Register and clear the delegate with host lifecycle -Register before any React Native screen can call `BrownfieldNavigation.*`: +Register before any React Native screen can call `BrownfieldNavigation.*`, and clear the delegate when this host is no longer the active navigation owner: ```kotlin -import android.os.Bundle import com.callstack.nativebrownfieldnavigation.BrownfieldNavigationManager -override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) +override fun onResume() { + super.onResume() BrownfieldNavigationManager.setDelegate(this) - // Initialize React Native host +} + +override fun onPause() { + BrownfieldNavigationManager.clearDelegate() + super.onPause() } ``` +`BrownfieldNavigationManager.getDelegate()` still fails fast when no delegate is registered, so missing registration remains a host lifecycle bug rather than a silent no-op. + ## iOS ### 1) Implement `BrownfieldNavigationDelegate` @@ -74,30 +83,83 @@ public final class RNNavigationDelegate: BrownfieldNavigationDelegate { } ``` -### 2) Register the delegate at app startup +### 2) Register and clear the delegate with host lifecycle + +If your app can hand Brownfield navigation between multiple native owners, register in the object that currently owns navigation and clear it during the matching teardown phase. + +In SwiftUI apps, prefer scene-driven lifecycle hooks such as `scenePhase`. In UIKit scene-based apps, use the matching `UISceneDelegate` callbacks. `UIApplicationDelegate` launch setup is still useful, but it is not always the right place to track foreground navigation ownership. ```swift import BrownfieldNavigation +import SwiftUI -@main -struct BrownfieldAppleApp: App { - init() { +final class AppDelegate: NSObject, UIApplicationDelegate { + private let navigationDelegate = RNNavigationDelegate() + + func registerNavigationDelegate() { BrownfieldNavigationManager.shared.setDelegate( - navigationDelegate: RNNavigationDelegate() + navigationDelegate: navigationDelegate ) } + + func clearNavigationDelegate() { + BrownfieldNavigationManager.shared.clearDelegate() + } +} + +@main +struct BrownfieldAppleApp: App { + @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate + + var body: some Scene { + WindowGroup { + RootContentView(appDelegate: appDelegate) + } + } +} + +private struct RootContentView: View { + @Environment(\.scenePhase) private var scenePhase + + let appDelegate: AppDelegate + + var body: some View { + ContentView() + .onAppear { + syncNavigationDelegate(for: scenePhase) + } + .onChange(of: scenePhase) { newPhase in + syncNavigationDelegate(for: newPhase) + } + } + + private func syncNavigationDelegate(for phase: ScenePhase) { + switch phase { + case .active: + appDelegate.registerNavigationDelegate() + case .inactive, .background: + appDelegate.clearNavigationDelegate() + @unknown default: + appDelegate.clearNavigationDelegate() + } + } } ``` +`BrownfieldNavigationManager.shared.getDelegate()` still fails fast when no delegate is registered, so lifecycle ownership bugs surface immediately during native integration. + ## Lifecycle Requirements - Register delegate before rendering JS that might call the module. +- Clear delegate when that host stops owning Brownfield navigation; do not keep stale delegates registered for the full app lifetime by default. - Keep navigation on main/UI thread. -- Re-register delegate if your host object is recreated. -- Treat missing delegate as a startup bug: runtime calls require a registered delegate. +- Re-register delegate if your host object is recreated or regains focus. +- Treat missing delegate as a lifecycle bug: runtime calls require a registered delegate. ## Troubleshooting - **Method added in TS but not visible natively**: rerun codegen and rebuild. - **Calls crash on app launch**: verify delegate registration happens before RN route rendering. +- **Calls crash after switching hosts**: confirm the previous host clears the delegate and the active host re-registers it before RN can navigate. +- **SwiftUI app never re-registers the delegate**: move ownership to `scenePhase` or `UISceneDelegate` instead of relying on `UIApplicationDelegate` active/resign callbacks. - **Wrong screen opens**: check native delegate method wiring and params mapping. diff --git a/skills/brownfield-navigation/references/native-android-integration.md b/skills/brownfield-navigation/references/native-android-integration.md index ab41ad4c..36fb397d 100644 --- a/skills/brownfield-navigation/references/native-android-integration.md +++ b/skills/brownfield-navigation/references/native-android-integration.md @@ -6,22 +6,31 @@ - Route each generated method to intended native destination - Map params directly (for example through `Intent` extras) -## Register delegate at startup +## Register delegate with lifecycle ownership - Call: - `BrownfieldNavigationManager.setDelegate(...)` -- Register in startup flow (for example `onCreate`) +- `BrownfieldNavigationManager.clearDelegate()` is part of the public API and should be called when this host stops owning navigation +- Register in the lifecycle phase where this host becomes active (for example `onResume`) +- Clear in the matching release phase (for example `onPause`) - Ensure registration happens before RN calls +- Do not keep a backgrounded or inactive `Activity` registered for the full app lifetime unless it is truly the only Brownfield navigation owner +- `BrownfieldNavigationManager.getDelegate()` still throws if no delegate is registered ## Minimal pattern ```kotlin class MainActivity : AppCompatActivity(), BrownfieldNavigationDelegate { - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) + override fun onResume() { + super.onResume() BrownfieldNavigationManager.setDelegate(this) } + override fun onPause() { + BrownfieldNavigationManager.clearDelegate() + super.onPause() + } + override fun openNativeProfile(userId: String) { val intent = Intent(this, ProfileActivity::class.java).apply { putExtra("userId", userId) diff --git a/skills/brownfield-navigation/references/native-ios-integration.md b/skills/brownfield-navigation/references/native-ios-integration.md index 0949dcae..37fe1735 100644 --- a/skills/brownfield-navigation/references/native-ios-integration.md +++ b/skills/brownfield-navigation/references/native-ios-integration.md @@ -6,16 +6,63 @@ - Route each generated method to intended UIKit/SwiftUI destination - Execute presentation on main thread -## Register delegate at startup +## Register delegate with lifecycle ownership - Call: - `BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: ...)` + - `BrownfieldNavigationManager.shared.clearDelegate()` - Register before RN screens that call Brownfield navigation are shown -- Keep a strong delegate reference for app lifetime +- Keep a strong delegate reference while this host owns Brownfield navigation +- Clear the delegate when this host stops owning navigation +- Do not keep the delegate registered for the full app lifetime by default; reassign ownership when another native host takes over +- In SwiftUI apps, prefer `scenePhase` for foreground ownership; in UIKit scene-based apps, prefer `UISceneDelegate` +- Do not rely on `UIApplicationDelegate` active/resign callbacks as the only ownership signal in SwiftUI +- `BrownfieldNavigationManager.shared.getDelegate()` still traps if no delegate is registered ## Minimal pattern ```swift +final class AppDelegate: NSObject, UIApplicationDelegate { + private let navigationDelegate = AppNavigationDelegate() + + func registerNavigationDelegate() { + BrownfieldNavigationManager.shared.setDelegate( + navigationDelegate: navigationDelegate + ) + } + + func clearNavigationDelegate() { + BrownfieldNavigationManager.shared.clearDelegate() + } +} + +struct RootContentView: View { + @Environment(\.scenePhase) private var scenePhase + + let appDelegate: AppDelegate + + var body: some View { + ContentView() + .onAppear { + syncNavigationDelegate(for: scenePhase) + } + .onChange(of: scenePhase) { newPhase in + syncNavigationDelegate(for: newPhase) + } + } + + private func syncNavigationDelegate(for phase: ScenePhase) { + switch phase { + case .active: + appDelegate.registerNavigationDelegate() + case .inactive, .background: + appDelegate.clearNavigationDelegate() + @unknown default: + appDelegate.clearNavigationDelegate() + } + } +} + final class AppNavigationDelegate: BrownfieldNavigationDelegate { func openNativeProfile(userId: String) { DispatchQueue.main.async { @@ -23,6 +70,4 @@ final class AppNavigationDelegate: BrownfieldNavigationDelegate { } } } - -BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: navigationDelegate) ```