Merge pull request #6 from DKVekariya/divyesh/feature/add-stack-persistence

Supported Persistence Route

Author: DKVekariya

Examples/NavPilotDemo/NavPilotDemo/ContentView.swift

@@ -24,6 +24,8 @@ struct ContentView: View {
                 E4SplitScreen()
             case .deepLinking:
                 E5DeepLinking()
+            case .statePersistence:
+                E6StatePersistence()
             }
         }
         .sheet(isPresented: $showSheet) {
@@ -33,16 +35,14 @@ struct ContentView: View {
                         self.navType = nav
                         self.showSheet.toggle()
                     }) {
-                        HStack {
-                            Text(nav.title)
-                        }
+                        Text(nav.title)
                         .frame(maxWidth: .infinity)
                         .padding(10)
                     }
                 }
             }
             .frame(maxWidth: .infinity, alignment: .center)
-            .presentationDetents([.height(250)])
+            .presentationDetents([.height(300)])
         }
     }
 }
@@ -58,6 +58,7 @@ enum NavigationType:String, Hashable, CaseIterable {
     case closerPass
     case splitScreen
     case deepLinking
+    case statePersistence
 
     var title: String {
         switch self {
@@ -66,6 +67,7 @@ enum NavigationType:String, Hashable, CaseIterable {
         case .closerPass: return "Closure Pass"
         case .splitScreen: return "Split Screen"
         case .deepLinking: return "Deep Linking"
+        case .statePersistence: return "State Persistence"
         }
     }
 }

Examples/NavPilotDemo/NavPilotDemo/E6StatePersistence.swift

@@ -0,0 +1,167 @@
+//
+//  E6StatePersistence.swift
+//  NavPilotDemo
+//
+//  Created by DK on 14/05/26.
+//
+
+import Foundation
+import SwiftUI
+import NavPilot
+
+struct E6Product: Codable, Hashable, Equatable {
+    let id: Int
+    let name: String
+}
+
+enum E6Route: Codable, Hashable {
+    case home
+    case product(E6Product)
+    case checkout(items: [String])
+}
+
+struct E6StatePersistence: View {
+    @StateObject private var pilot = NavPilot(
+        initial: E6Route.home,
+        debug: true,
+        // Set `persistState` to false to disable stack restoration.
+        // Enable it only when the route carries enough Codable data to recreate the screen
+        // and its view model after relaunch.
+        persistState: true,
+        persistenceKey: "NavPilotDemo.E6StatePersistence"
+    )
+
+    var body: some View {
+        NavPilotHost(pilot) { route in
+            switch route {
+            case .home:
+                E6HomeView()
+            case .product(let product):
+                E6ProductView(product: product)
+            case .checkout(let items):
+                E6CheckoutView(items: items)
+            }
+        }
+    }
+}
+
+struct E6HomeView: View {
+    @EnvironmentObject var pilot: NavPilot<E6Route>
+
+    let products = [
+        E6Product(id: 1, name: "Keyboard"),
+        E6Product(id: 2, name: "Monitor"),
+        E6Product(id: 3, name: "Mouse")
+    ]
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 16) {
+                Text("State Persistence")
+                    .font(.largeTitle.bold())
+
+                Text("This demo saves the stack automatically. Push a few screens, quit the app, then reopen it to see the stack restored.")
+                    .foregroundStyle(.secondary)
+
+                Text("Use persistence only when the route contains enough Codable data to rebuild the screen. View models and injected services are created again when the app restores the route stack.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+
+                VStack(alignment: .leading, spacing: 12) {
+                    ForEach(products, id: \.id) { product in
+                        Button {
+                            pilot.push(.product(product))
+                        } label: {
+                            Label(product.name, systemImage: "chevron.right")
+                        }
+                    }
+                }
+                .padding()
+                .background(.thinMaterial, in: RoundedRectangle(cornerRadius: 16))
+
+                Button("Add Checkout") {
+                    pilot.push(.checkout(items: ["Keyboard", "Mouse"]))
+                }
+
+                Button("Pop To Root") {
+                    pilot.popToRoot()
+                }
+
+                Button(role: .destructive) {
+                    UserDefaults.standard.removeObject(forKey: "NavPilotDemo.E6StatePersistence")
+                    pilot.popToRoot()
+                } label: {
+                    Text("Clear Saved Stack")
+                }
+
+                Text("If your screen depends on a view model, recreate that view model from the route data or from your app container. The persisted stack only stores navigation state, not live objects.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+
+                VStack(alignment: .leading, spacing: 8) {
+                    Text("Current stack")
+                        .font(.headline)
+                    Text(String(describing: pilot.stack))
+                        .font(.footnote.monospaced())
+                        .foregroundStyle(.secondary)
+                }
+                .padding()
+                .background(.secondary.opacity(0.1), in: RoundedRectangle(cornerRadius: 12))
+            }
+            .padding()
+        }
+        .navigationTitle("Home")
+    }
+}
+
+struct E6ProductView: View {
+    @EnvironmentObject var pilot: NavPilot<E6Route>
+    let product: E6Product
+
+    var body: some View {
+        VStack(spacing: 20) {
+            Text(product.name).font(.title2.bold())
+            Text("This screen will be restored after relaunch if persistence is enabled.")
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+
+            Button("Add Checkout") {
+                pilot.push(.checkout(items: [product.name]))
+            }
+
+            Button("Back") {
+                pilot.pop()
+            }
+        }
+        .padding()
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .navigationTitle(product.name)
+    }
+}
+
+struct E6CheckoutView: View {
+    @EnvironmentObject var pilot: NavPilot<E6Route>
+    let items: [String]
+
+    var body: some View {
+        VStack(spacing: 20) {
+            Text("Checkout").font(.title2.bold())
+            Text(items.joined(separator: ", "))
+                .foregroundStyle(.secondary)
+            Text("After you relaunch the app, this screen should still be on the stack.")
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+
+            Button("Pop To Root") {
+                pilot.popToRoot()
+            }
+
+            Button("Back") {
+                pilot.pop()
+            }
+        }
+        .padding()
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .navigationTitle("Checkout")
+    }
+}

README.md

@@ -37,6 +37,9 @@ A modern, type-safe navigation library built entirely on SwiftUI's `NavigationSt
 ### 🔗 Deep Linking
 - **URL round-trip** — generate and restore stack state for `Codable` routes using a lightweight URL format
 
+### 💾 State Persistence
+- **Opt-in restore** — pass `persistState: true` for `Codable` routes to save and reload the stack automatically
+
 ### 🌿 Environment Injection
 - **`@EnvironmentObject`** — every child view receives the pilot automatically
 - **No prop drilling** — navigate from anywhere in the view hierarchy
@@ -134,7 +137,7 @@ enum AppRoute: Hashable {
 ```swift
 @main
 struct MyApp: App {
-    @StateObject var pilot = NavPilot(initial: AppRoute.home)
+    @StateObject var pilot = NavPilot(initial: AppRoute.home, persistState: true)
 
     var body: some Scene {
         WindowGroup {
@@ -214,6 +217,14 @@ let url = pilot.deepLinkURL()
 pilot.handleDeepLink(url)
 ```
 
+### State Persistence
+
+When you want the stack to survive app relaunches, opt in with `persistState: true`:
+
+```swift
+@StateObject var pilot = NavPilot(initial: AppRoute.home, persistState: true)
+```
+
 ## 🏗️ Architecture Highlights
 
 ### State Management
@@ -248,6 +259,7 @@ pilot.handleDeepLink(url)
 | `replaceCurrent(with:)` | Swap only the top-most route |
 | `deepLinkURL()` | Generate a URL that represents the current stack |
 | `handleDeepLink(_:)` | Restore the stack from a deep-link URL |
+| `persistState` | Opt-in initializer behavior for Codable routes that stores the stack |
 
 ### Properties
 
@@ -273,6 +285,7 @@ private let activeExample: Int = 1
 | 3 | Callback Route | Closure passed as a route parameter |
 | 4 | Split Screen | Two independent pilots in a vertical split layout |
 | 5 | Deep Linking | Generate and restore a stack from a URL |
+| 6 | State Persistence | Save and restore stack across app relaunch |
 
 ## 🐛 Known Limitations