Navigator: Instructions file for Claude Code

CLAUDE.md

Navigator is a SwiftUI navigation framework built on NavigationStack. It eliminates manual navigationDestination registrations and supports deep linking, checkpoints, and modular app patterns.

Platforms: iOS 17+, macOS 14+, tvOS 17+, watchOS 10+, visionOS 1+ Swift: 6.2, strict concurrency, @MainActor isolation throughout

Core pattern

Navigation is driven by enums conforming to NavigationDestination (Hashable + View). Each enum case is a screen; associated values pass parameters. The enum's body returns the view for each case — no per-destination registration needed.

ManagedNavigationStack replaces NavigationStack. It creates a Navigator, injects it into the SwiftUI environment, and registers a single AnyNavigationDestination handler so any destination type can be pushed without extra setup. Access the navigator with @Environment(\.navigator) var navigator.

Navigator (@Observable, @MainActor) manages the navigation path, sheet/cover presentations, checkpoints, locks, and the parent–child hierarchy that mirrors the presentation tree.

Key patterns

• NavigationMethod — how a destination is presented: .push, .sheet, .managedSheet, .cover, .managedCover, .send
• Checkpoints — named return points; any view can return to a named place without knowing the stack structure; support typed value returns
• Deep linking via send/receive — navigator.send(values:) broadcasts Hashable values; views subscribe with .onNavigationReceive; routes abstract multi-step sequences behind a single perform(route:) call
• Modular destinations — NavigationProvidedDestination lets a module declare destinations without knowing the view implementations; the app root registers providers via .onNavigationProvidedView
• Dismissible tree — ManagedPresentationView / .managedPresentationView() registers custom sheets with Navigator so dismissAny() and checkpoints can traverse the full presentation tree