fix: allow unregistering the navigation delegate

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) {

apps/AppleApp/Brownfield Apple App/BrownfieldAppleApp.swift

@@ -83,10 +83,6 @@ struct BrownfieldAppleApp: App {
             print("React Native has been loaded")
         }
 
-        BrownfieldNavigationManager.shared.setDelegate(
-            navigationDelegate: RNNavigationDelegate()
-        )
-
         #if USE_EXPO_HOST
             ReactNativeBrownfield.shared.ensureExpoModulesProvider()
         #endif
@@ -96,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()
         }
     }
 }

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)"

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.

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.")

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 {

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)

skills/brownfield-navigation/references/native-ios-integration.md

@@ -6,23 +6,68 @@
 - 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 {
       // present native screen
     }
   }
 }
-
-BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: navigationDelegate)
 ```