SwiftUI Navigation skill for Codex

Done well means: navigation state is data (an array of Hashable routes per stack plus optional presented items), any screen can be reached by setting that data, deep links and notification taps reuse the same path, and back, pop-to-root and dismiss all behave on iPhone and iPad.

Inspect first

cat AGENTS.md 2>/dev/null
grep -rnE 'NavigationView|NavigationStack|NavigationSplitView|navigationDestination|NavigationLink\(destination' \
  --include='*.swift' . | head -40
grep -rnE 'onOpenURL|userActivity|UNUserNotificationCenter' --include='*.swift' . | head

NavigationView is deprecated. NavigationLink(destination:) builds destinations eagerly and cannot be driven by state; replace both when touching a flow.

Choose the container

App shape	Container
Single drill-down flow	NavigationStack(path:)
Top-level sections	TabView with one NavigationStack per tab
List-detail on iPad / Mac	NavigationSplitView (collapses to a stack on iPhone)
Task that interrupts the flow (compose, edit, sign in)	sheet / fullScreenCover, with its own NavigationStack inside if it has steps

Routes as data

enum Route: Hashable, Codable {
    case order(id: String)
    case orderItem(orderID: String, itemID: String)
    case settings
}

enum Sheet: Identifiable, Hashable {
    case compose(draftID: UUID?)
    case paywall
    var id: Self { self }
}

@MainActor @Observable
final class Router {
    var path: [Route] = []
    var sheet: Sheet?

    func push(_ route: Route) { path.append(route) }
    func popToRoot() { path.removeAll() }
    func present(_ sheet: Sheet) { self.sheet = sheet }
}

Carry IDs in routes, not model objects: routes stay Codable for restoration, and the destination screen loads fresh data.

struct OrdersRoot: View {
    @State private var router = Router()

    var body: some View {
        NavigationStack(path: $router.path) {
            OrderListView()
                .navigationDestination(for: Route.self) { route in
                    switch route {
                    case .order(let id): OrderDetailView(orderID: id)
                    case .orderItem(let orderID, let itemID): ItemView(orderID: orderID, itemID: itemID)
                    case .settings: SettingsView()
                    }
                }
        }
        .sheet(item: $router.sheet) { sheet in
            switch sheet {
            case .compose(let draftID): ComposeView(draftID: draftID)
            case .paywall: PaywallView().presentationDetents([.medium, .large])
            }
        }
        .environment(router)
    }
}

In child views: NavigationLink(value: Route.order(id: order.id)) { OrderRow(order) } or router.push(...) from an action. Dismiss a presented view with @Environment(\.dismiss) private var dismiss.

Use NavigationPath instead of [Route] only when one stack must hold unrelated route types from separate modules; a typed array is easier to inspect, test and restore.

Tabs

enum AppTab: Hashable { case orders, inbox, account }

struct RootView: View {
    @State private var tab: AppTab = .orders
    @State private var ordersRouter = Router()
    @State private var inboxRouter = Router()

    var body: some View {
        TabView(selection: $tab) {
            Tab("Orders", systemImage: "bag", value: .orders) {
                OrdersStack().environment(ordersRouter)
            }
            Tab("Inbox", systemImage: "tray", value: .inbox) {
                InboxStack().environment(inboxRouter)
            }
        }
    }
}

The Tab type needs iOS 18; on iOS 17 use .tabItem and .tag. One router per tab keeps each tab’s back stack when switching. Re-tapping the selected tab to pop to root is not automatic with custom routers: detect the repeated selection and call popToRoot().

Deep links and notification taps

Translate the URL into routes in one place, then set state:

extension Route {
    static func path(for url: URL) -> (AppTab, [Route])? {
        let parts = url.pathComponents.filter { $0 != "/" }
        switch (url.host(), parts.first) {
        case ("orders", let id?):
            return (.orders, [.order(id: id)])
        case ("orders", nil):
            return (.orders, [])
        default:
            return nil
        }
    }
}

// in RootView
.onOpenURL { url in
    guard let (tab, path) = Route.path(for: url) else { return }
    self.tab = tab
    ordersRouter.sheet = nil          // dismiss modals first
    ordersRouter.path = path
}

• Universal links arrive through the same onOpenURL in SwiftUI apps. Domain setup (apple-app-site-association, entitlements) belongs to $mobile-deep-links.
• Notification taps: in the UNUserNotificationCenterDelegate, convert the payload to a URL or route and hand it to the same function.
• Replace the whole path for a deep link rather than appending; otherwise links stack on top of whatever the user was viewing.
• Validate IDs from URLs; unknown IDs should land on a not-found state, not crash.

Test:

xcrun simctl openurl booted "acme://orders/1234"

State restoration

@SceneStorage("orders.path") private var savedPath: Data?

.task {
    if let data = savedPath, let path = try? JSONDecoder().decode([Route].self, from: data) {
        router.path = path
    }
}
.onChange(of: router.path) { _, newPath in
    savedPath = try? JSONEncoder().encode(newPath)
}

Decoding must tolerate removed cases (try?); never crash on stale restoration data.

Gotchas

• navigationDestination placed inside a lazy container (List, LazyVStack) or on a view that is conditionally shown is ignored or warns. Attach it to the stack’s root content.
• Registering two navigationDestination(for: Route.self) in the same stack: only one wins. One per type per stack.
• Nesting a NavigationStack inside another stack’s destination produces double navigation bars and broken back behaviour. Only sheets get a new stack.
• Setting path and presenting a sheet in the same transaction can drop one animation; dismiss first, then update path (or apply changes in one withTransaction if needed).
• sheet(isPresented:) with data captured from state shows stale content; prefer sheet(item:).
• NavigationSplitView selection should be optional IDs (selection: $selectedID), not model objects, or selection breaks after a refresh.

Verification

• Unit test the router and URL parsing without UI: given a URL, assert the tab and path.
• UI test or manual check per flow: push, back, swipe back, pop to root, open and dismiss each sheet, deep link from cold launch and while the app is in the background with a sheet open.
• Run on an iPhone and an iPad simulator (split view collapse behaves differently).

xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 17' \
  -derivedDataPath build/DerivedData -only-testing:AppTests/RouterTests

Output: navigation map

| Entry | Tab | Path | Presented |
|---|---|---|---|
| acme://orders/1234 | orders | [.order(1234)] | none |
| notification "new_message" | inbox | [.thread(id)] | none |
| Compose button | current | unchanged | .compose(nil) |
Tested: iPhone 17 + iPad simulators, cold and warm deep links, restoration after relaunch