MapKit for SwiftUI

Embedding maps, annotations, overlays, search, directions, Look Around, and geocoding on Apple platforms. The deep API reference — every map style and control, the full search/directions/Look Around flows, the iOS 26 geocoding APIs, GeoToolbox PlaceDescriptor, performance tuning, and known SwiftUI limitations — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. CAMERA — static (one-shot Map(initialPosition:), map owns the camera after; default for display-only maps) · bound (Map(position: $position) two-way binding when you drive the camera programmatically — "go to result", "recenter on user"). Don't use a binding you never write to.
2. LOCATION — none (no user location) · display (UserAnnotation() + .userLocation(fallback:) camera, needs Core Location auth + Info.plist string) · tracking (continuous CLLocationManager updates feeding annotations). Anything past none is a corelocation concern.
3. SEARCH — none · local (MKLocalSearch for one-shot queries) · completer (MKLocalSearchCompleter for as-you-type autocomplete, resolve to a MKMapItem on selection). geocode (MKGeocodingRequest/MKReverseGeocodingRequest) is a separate axis — address↔coordinate, not POI search.

When to use

Building or reviewing any SwiftUI map: placing markers/annotations, drawing overlays, controlling the camera, searching for places, drawing routes, Look Around, or geocoding. If the task is "where is the user / ask for location permission," that's corelocation — this skill consumes the resulting coordinate. If the task is purely address↔coordinate with no map, you still want the geocoding section here.

Core rules