@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/mapkit-location/references/mapkit-patterns.md

@@ -1,793 +1,691 @@
-# MapKit Patterns Reference
+# MapKit Patterns for SwiftUI
 
-Extended patterns for MapKit on iOS 17+ with SwiftUI. Import `MapKit` and
-`SwiftUI` in every file that uses these APIs.
-
-```swift
-import MapKit
-import SwiftUI
-```
-
----
+Everything here targets iOS 17 and SwiftUI unless a heading names a later
+release. Each file that uses these types imports both `MapKit` and `SwiftUI`.
 
 ## Contents
 
-- [Complete Map View Setup](#complete-map-view-setup)
-- [Custom Annotation Views](#custom-annotation-views)
-- [Camera Control (MapCameraPosition)](#camera-control-mapcameraposition)
-- [Map Selection Handling](#map-selection-handling)
-- [Search with Autocomplete](#search-with-autocomplete)
+- [A Full Map Screen](#a-full-map-screen)
+- [Custom Annotations](#custom-annotations)
+- [Camera Control](#camera-control)
+- [Selection](#selection)
+- [Autocomplete Search](#autocomplete-search)
 - [Route Display](#route-display)
-- [Look Around Preview](#look-around-preview)
-- [Map Snapshots (MKMapSnapshotter)](#map-snapshots-mkmapsnapshotter)
-- [Clustering Annotations](#clustering-annotations)
-- [MapKit with MKMapItem Utilities](#mapkit-with-mkmapitem-utilities)
-- [iOS 26 New APIs](#ios-26-new-apis)
-- [User Location Display](#user-location-display)
-- [Map in a List or ScrollView](#map-in-a-list-or-scrollview)
-- [Coordinate Utilities](#coordinate-utilities)
+- [Cycling Directions (iOS 14+)](#cycling-directions-ios-14)
+- [Street-Level Look Around](#street-level-look-around)
+- [Still Images with MKMapSnapshotter](#still-images-with-mkmapsnapshotter)
+- [Dense Annotations and Clustering](#dense-annotations-and-clustering)
+- [MKMapItem Helpers](#mkmapitem-helpers)
+- [Geocoding and Places on iOS 26](#geocoding-and-places-on-ios-26)
+- [Showing the User](#showing-the-user)
+- [Maps Inside Scrolling Content](#maps-inside-scrolling-content)
+- [Coordinate Math](#coordinate-math)
 - [Accessibility](#accessibility)
-- [References](#references)
+- [Apple Documentation](#apple-documentation)
 
-## Complete Map View Setup
+## A Full Map Screen
 
-A production-ready map view with markers, user location, and controls.
+A bike-dock finder: user location, one marker per dock coloured by
+availability, built-in points of interest hidden, a detail card for the
+selected dock.
 
 ```swift
-struct StoreLocatorMap: View {
-    let stores: [Store]
-    @State private var position: MapCameraPosition = .automatic
-    @State private var selectedStore: Store?
+import SwiftUI
+import MapKit
+
+struct BikeDock: Identifiable, Hashable {
+    let id: UUID
+    let name: String
+    let latitude: Double
+    let longitude: Double
+    let freeBikes: Int
+
+    var coordinate: CLLocationCoordinate2D {
+        CLLocationCoordinate2D(latitude: latitude, longitude: longitude)
+    }
+}
+
+struct DockFinderView: View {
+    let docks: [BikeDock]
+    @State private var camera: MapCameraPosition = .userLocation(fallback: .automatic)
+    @State private var picked: BikeDock?
 
     var body: some View {
-        Map(position: $position, selection: $selectedStore) {
+        Map(position: $camera, selection: $picked) {
             UserAnnotation()
-
-            ForEach(stores) { store in
-                Marker(store.name, systemImage: "storefront",
-                       coordinate: store.coordinate)
-                    .tint(store.isOpen ? .green : .gray)
-                    .tag(store)
+            ForEach(docks) { dock in
+                Marker(dock.name, systemImage: "bicycle", coordinate: dock.coordinate)
+                    .tint(dock.freeBikes > 0 ? .green : .gray)
+                    .tag(dock)
             }
         }
-        .mapStyle(.standard(pointsOfInterest: .excludingAll))
         .mapControls {
-            MapUserLocationButton()
             MapCompass()
-            MapScaleView()
             MapPitchToggle()
+            MapScaleView()
+            MapUserLocationButton()
         }
+        .mapStyle(.standard(pointsOfInterest: .excludingAll))
         .safeAreaInset(edge: .bottom) {
-            if let store = selectedStore {
-                StoreDetailCard(store: store)
+            if let picked {
+                Text("\(picked.name): \(picked.freeBikes) bikes")
                     .padding()
+                    .frame(maxWidth: .infinity)
+                    .background(.regularMaterial)
             }
         }
     }
 }
 ```
 
-Conform the data model to `Hashable` for use with map selection:
-
-```swift
-struct Store: Identifiable, Hashable {
-    let id: UUID
-    let name: String
-    let coordinate: CLLocationCoordinate2D
-    let isOpen: Bool
-
-    static func == (lhs: Store, rhs: Store) -> Bool { lhs.id == rhs.id }
-    func hash(into hasher: inout Hasher) { hasher.combine(id) }
-}
-```
-
----
+Whatever you tag and select must be `Hashable`. `CLLocationCoordinate2D` is
+neither `Hashable` nor `Equatable`, so a model that stores one cannot get the
+synthesised conformance. Either keep plain `Double` latitude and longitude, as
+above, and build the coordinate on demand, or write `==` and `hash(into:)`
+yourself using only `id`.
 
-## Custom Annotation Views
+## Custom Annotations
 
-Use `Annotation` for fully custom SwiftUI content at a coordinate. Prefer
-`Marker` for standard pins because it provides the platform marker appearance
-and a title that VoiceOver can announce.
+`Annotation` takes arbitrary SwiftUI content. For an ordinary pin, prefer
+`Marker`: it looks like the platform marker and VoiceOver reads its title
+without extra work.
 
 ```swift
-Map {
-    ForEach(friends) { friend in
-        Annotation(friend.name, coordinate: friend.coordinate, anchor: .bottom) {
+struct FriendPin: MapContent {
+    let name: String
+    let photo: URL
+    let spot: CLLocationCoordinate2D
+
+    var body: some MapContent {
+        Annotation(name, coordinate: spot, anchor: .bottom) {
             VStack(spacing: 0) {
-                AsyncImage(url: friend.avatarURL) { image in
-                    image.resizable().scaledToFill()
+                AsyncImage(url: photo) { loaded in
+                    loaded.resizable().aspectRatio(contentMode: .fill)
                 } placeholder: {
-                    Color.gray
+                    ProgressView()
                 }
                 .frame(width: 40, height: 40)
-                .clipShape(.circle)
-                .overlay(Circle().stroke(.white, lineWidth: 2))
+                .clipShape(Circle())
+                .overlay { Circle().strokeBorder(.white, lineWidth: 2) }
 
-                Image(systemName: "triangle.fill")
-                    .font(.caption2)
+                Image(systemName: "arrowtriangle.down.fill")
+                    .imageScale(.small)
                     .foregroundStyle(.white)
-                    .rotationEffect(.degrees(180))
-                    .offset(y: -3)
             }
         }
     }
 }
 ```
 
-### Annotation with anchorOffset for callout-style layout
+### Callout-style annotation anchored at the bottom
+
+SwiftUI's `Annotation` positions content with `anchor`, a `UnitPoint`; it has
+no point-offset parameter. For a label floating above a pin, stack the label
+over the symbol and anchor at `.bottom`, so the tip of the symbol sits on the
+coordinate.
 
 ```swift
-Annotation(place.name, coordinate: place.coordinate, anchor: .bottom) {
-    VStack(spacing: 2) {
-        Text(place.name)
-            .font(.caption)
-            .fontWeight(.semibold)
-            .padding(.horizontal)
-            .padding(.vertical)
-            .background(.ultraThinMaterial, in: .capsule)
-
-        Image(systemName: "mappin.circle.fill")
-            .font(.title)
-            .foregroundStyle(.red)
+struct LabeledPin: MapContent {
+    let title: String
+    let spot: CLLocationCoordinate2D
+
+    var body: some MapContent {
+        Annotation(title, coordinate: spot, anchor: .bottom) {
+            VStack(spacing: 3) {
+                Text(title)
+                    .font(.caption.weight(.semibold))
+                    .padding(.horizontal, 8)
+                    .padding(.vertical, 4)
+                    .background(.ultraThinMaterial, in: Capsule())
+                Image(systemName: "mappin.circle.fill")
+                    .font(.title2)
+                    .foregroundStyle(.white, .pink)
+            }
+        }
     }
 }
 ```
 
----
-
-## Camera Control (MapCameraPosition)
+## Camera Control
 
 ### Setting an initial position
 
-`MapCameraPosition` controls what the map displays. Bind it to let the user
-interact and to move the camera programmatically.
-
-```swift
-// Center on a region
-@State private var position: MapCameraPosition = .region(
-    MKCoordinateRegion(
-        center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
-        span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
-    )
-)
-
-// Follow user location
-@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
-
-// Specific camera angle (3D perspective)
-@State private var position: MapCameraPosition = .camera(
-    MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
-)
-
-// Frame specific items
-position = .item(MKMapItem.forCurrentLocation())
-position = .rect(MKMapRect(...))
-```
+| Position | Shows |
+|----------|-------|
+| `.region(MKCoordinateRegion(center: c, span: nearbySpan))` | a region around a centre (`nearbySpan` here is about 0.05 degrees each way) |
+| `.userLocation(fallback: .automatic)` | follows the user |
+| `.camera(MapCamera(centerCoordinate: c, distance: 1200, heading: 120, pitch: 55))` | a tilted 3D viewpoint, 1.2 km out, facing south-east |
+| `.item(MKMapItem.forCurrentLocation())` | frames a map item |
+| `.rect(someMapRect)` | frames an `MKMapRect` |
 
 ### Animate camera changes
 
-Wrap position updates in `withAnimation` for smooth transitions:
+Assign inside `withAnimation` (any curve, for example `.easeInOut`) for a fly-to:
 
 ```swift
-func flyTo(_ coordinate: CLLocationCoordinate2D) {
-    withAnimation(.easeInOut(duration: 1.0)) {
-        position = .camera(
-            MapCamera(centerCoordinate: coordinate, distance: 2000,
-                      heading: 0, pitch: 45)
-        )
+func fly(to target: CLLocationCoordinate2D) {
+    withAnimation(.smooth(duration: 1)) {
+        let overhead = MapCamera(centerCoordinate: target, distance: 1800, heading: 30, pitch: 50)
+        camera = .camera(overhead)
     }
 }
 ```
 
 ### Frame multiple annotations
 
-```swift
-func frameAllStores() {
-    withAnimation {
-        position = .automatic  // Frames all map content
-    }
-}
-
-// Or frame a specific rect
-func frameRegion(_ region: MKCoordinateRegion) {
-    withAnimation {
-        position = .region(region)
-    }
-}
-```
+`camera = .automatic` (inside `withAnimation`) frames all map content.
+`camera = .region(someRegion)` frames a region you computed, for example with
+the helper in [Coordinate Math](#coordinate-math).
 
 ### Read current camera position
 
-Use `onMapCameraChange` to observe what the user is looking at:
-
 ```swift
-@State private var visibleRegion: MKCoordinateRegion?
-
-Map(position: $position) { ... }
-    .onMapCameraChange(frequency: .onEnd) { context in
-        visibleRegion = context.region
+Map(position: $camera) { /* content */ }
+    .onMapCameraChange(frequency: .onEnd) { ctx in
+        visibleRegion = ctx.region
     }
 ```
 
-`frequency: .onEnd` fires after the user finishes scrolling. Use
-`.continuous` only when you need live tracking (costs more CPU).
-
----
+`.onEnd` fires once the user stops moving the map. `.continuous` fires during
+the gesture and costs more CPU; use it only for live tracking.
 
-## Map Selection Handling
+## Selection
 
-### Select markers by MKMapItem
+### Selecting an MKMapItem
 
-Use `MKMapItem` as the selection type when you want to look up place details:
+Bind selection to `MKMapItem?` when a pick should lead to place details.
 
 ```swift
-@State private var selectedItem: MKMapItem?
+struct MuseumMap: View {
+    let museums: [MKMapItem]
+    @State private var chosen: MKMapItem?
+    @State private var streetScene: MKLookAroundScene?
 
-Map(selection: $selectedItem) {
-    ForEach(searchResults) { result in
-        Marker(item: result)
+    var body: some View {
+        Map(selection: $chosen) {
+            ForEach(museums, id: \.self) { museum in
+                Marker(item: museum)
+            }
+        }
+        .onChange(of: chosen) { _, museum in
+            guard let museum else { return }
+            Task { streetScene = try? await MKLookAroundSceneRequest(mapItem: museum).scene }
+        }
     }
 }
-.onChange(of: selectedItem) { _, newItem in
-    guard let item = newItem else { return }
-    Task { await fetchLookAround(for: item) }
-}
 ```
 
-### Select by custom Identifiable tag
-
-```swift
-@State private var selectedPlaceID: Place.ID?
-
-Map(selection: $selectedPlaceID) {
-    ForEach(places) { place in
-        Marker(place.name, coordinate: place.coordinate)
-            .tag(place.id)
-    }
-}
-```
+### Selecting by your own ID
 
----
+Bind to `Place.ID?` and tag each marker with `.tag(place.id)`. The tag type and
+the binding type must match.
 
-## Search with Autocomplete
+## Autocomplete Search
 
-Full pattern: completer feeds suggestions, selecting a suggestion triggers a
-full search that returns `MKMapItem` results.
+Suggestions come from `MKLocalSearchCompleter`; picking one runs a full
+`MKLocalSearch` that returns `MKMapItem`s.
 
 ```swift
-@Observable
-final class MapSearchService: NSObject, MKLocalSearchCompleterDelegate {
-    var completions: [MKLocalSearchCompletion] = []
-    var searchResults: [MKMapItem] = []
-    var queryFragment: String = "" {
-        didSet { completer.queryFragment = queryFragment }
-    }
+import MapKit
+import Observation
 
+@MainActor
+@Observable
+final class PlaceFinder: NSObject, MKLocalSearchCompleterDelegate {
+    private(set) var suggestions: [MKLocalSearchCompletion] = []
+    private(set) var matches: [MKMapItem] = []
     private let completer: MKLocalSearchCompleter
 
+    var fragment = "" {
+        didSet { completer.queryFragment = fragment }
+    }
+
     override init() {
-        completer = MKLocalSearchCompleter()
+        let engine = MKLocalSearchCompleter()
+        engine.resultTypes = [.address, .pointOfInterest]
+        completer = engine
         super.init()
         completer.delegate = self
-        completer.resultTypes = [.address, .pointOfInterest]
     }
 
-    // Restrict suggestions to the visible map region
-    func updateRegion(_ region: MKCoordinateRegion) {
+    func focus(on region: MKCoordinateRegion) {
         completer.region = region
     }
 
-    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
-        completions = completer.results
+    nonisolated func completerDidUpdateResults(_ source: MKLocalSearchCompleter) {
+        MainActor.assumeIsolated { suggestions = completer.results }
     }
 
-    func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
-        completions = []
+    nonisolated func completer(_ source: MKLocalSearchCompleter, didFailWithError failure: any Error) {
+        MainActor.assumeIsolated { suggestions = [] }
     }
 
-    func select(_ completion: MKLocalSearchCompletion) async {
-        let request = MKLocalSearch.Request(completion: completion)
+    func choose(_ suggestion: MKLocalSearchCompletion) async {
+        let request = MKLocalSearch.Request(completion: suggestion)
         request.resultTypes = [.pointOfInterest, .address]
+        let search = MKLocalSearch(request: request)
         do {
-            let response = try await MKLocalSearch(request: request).start()
-            searchResults = response.mapItems
+            let reply = try await search.start()
+            matches = reply.mapItems
         } catch {
-            searchResults = []
+            matches = []
         }
     }
 }
 ```
 
-### Search View Integration
+`focus(on:)` narrows suggestions to the visible region. The delegate copies
+`results` on update and clears the list on failure. It reads the model's own
+`completer` inside `assumeIsolated`, not the callback parameter: the parameter
+is a non-`Sendable` value from a nonisolated context, and Swift 6 will not
+send it into the main-actor closure.
+
+### Wiring it into a screen
 
 ```swift
-struct MapSearchView: View {
-    @State private var searchService = MapSearchService()
-    @State private var searchText = ""
-    @State private var position: MapCameraPosition = .automatic
+struct PlaceSearchScreen: View {
+    @State private var finder = PlaceFinder()
+    @State private var typed = ""
+    @State private var camera: MapCameraPosition = .automatic
 
     var body: some View {
-        Map(position: $position) {
-            ForEach(searchService.searchResults, id: \.self) { item in
-                Marker(item: item)
-            }
+        Map(position: $camera) {
+            ForEach(finder.matches, id: \.self) { Marker(item: $0) }
         }
-        .searchable(text: $searchText, prompt: "Search places")
+        .searchable(text: $typed, prompt: "Search places")
         .searchSuggestions {
-            ForEach(searchService.completions, id: \.self) { completion in
+            ForEach(finder.suggestions, id: \.self) { suggestion in
                 Button {
-                    Task { await searchService.select(completion) }
+                    Task { await finder.choose(suggestion) }
                 } label: {
                     VStack(alignment: .leading) {
-                        Text(completion.title)
-                        Text(completion.subtitle)
-                            .font(.caption)
-                            .foregroundStyle(.secondary)
+                        Text(suggestion.title)
+                        Text(suggestion.subtitle).font(.caption).foregroundStyle(.secondary)
                     }
                 }
             }
         }
-        .task(id: searchText) {
-            try? await Task.sleep(for: .milliseconds(300))
+        .task(id: typed) {
+            let quietPeriod = Duration.milliseconds(300)
+            try? await Task.sleep(for: quietPeriod)
             guard !Task.isCancelled else { return }
-            searchService.queryFragment = searchText
+            finder.fragment = typed
         }
         .onMapCameraChange(frequency: .onEnd) { context in
-            searchService.updateRegion(context.region)
+            finder.focus(on: context.region)
         }
     }
 }
 ```
 
----
+`.task(id:)` restarts on each keystroke and cancels the previous sleep, which
+is the debounce.
 
 ## Route Display
 
-Calculate directions and draw the route polyline on the map.
-
 ```swift
-struct DirectionsMapView: View {
-    let source: MKMapItem
-    let destination: MKMapItem
+struct CommuteView: View {
+    let home: MKMapItem
+    let office: MKMapItem
     @State private var route: MKRoute?
-    @State private var position: MapCameraPosition = .automatic
-    @State private var travelTime: String = ""
+    @State private var camera: MapCameraPosition = .automatic
+    @State private var failed = false
 
     var body: some View {
-        Map(position: $position) {
+        Map(position: $camera) {
             if let route {
-                MapPolyline(route.polyline)
-                    .stroke(.blue, lineWidth: 6)
+                MapPolyline(route.polyline).stroke(.indigo, lineWidth: 6)
             }
-            Marker(item: source)
-                .tint(.green)
-            Marker(item: destination)
-                .tint(.red)
+            Marker(item: home).tint(.green)
+            Marker(item: office).tint(.red)
         }
         .overlay(alignment: .top) {
-            if !travelTime.isEmpty {
-                Text(travelTime)
-                    .font(.caption)
-                    .padding()
-                    .background(.ultraThinMaterial, in: .capsule)
-                    .padding(.top)
+            if let route {
+                Text(Duration.seconds(route.expectedTravelTime)
+                        .formatted(.units(allowed: [.hours, .minutes], width: .abbreviated)))
+                    .padding(8)
+                    .background(.ultraThinMaterial, in: Capsule())
+            } else if failed {
+                Text("No route found").padding(8).background(.ultraThinMaterial, in: Capsule())
             }
         }
-        .task { await calculateRoute() }
+        .task { await load() }
     }
 
-    private func calculateRoute() async {
+    private func load() async {
         let request = MKDirections.Request()
-        request.source = source
-        request.destination = destination
+        request.source = home
+        request.destination = office
         request.transportType = .automobile
-
+        let directions = MKDirections(request: request)
         do {
-            let response = try await MKDirections(request: request).calculate()
-            route = response.routes.first
-            if let route {
-                let formatter = DateComponentsFormatter()
-                formatter.unitsStyle = .abbreviated
-                formatter.allowedUnits = [.hour, .minute]
-                travelTime = formatter.string(from: route.expectedTravelTime) ?? ""
-
-                withAnimation {
-                    position = .rect(route.polyline.boundingMapRect)
-                }
+            let reply = try await directions.calculate()
+            guard let best = reply.routes.first else {
+                failed = true
+                return
             }
+            route = best
+            withAnimation { camera = .rect(best.polyline.boundingMapRect) }
         } catch {
-            print("Directions error: \(error.localizedDescription)")
+            failed = true
         }
     }
 }
 ```
 
-### Multiple Route Options
+The travel time is formatted as hours and minutes in abbreviated units
+(`DateComponentsFormatter` with `.abbreviated` and `[.hour, .minute]` does
+the same on older code). After the route arrives the camera animates to the
+polyline's `boundingMapRect`. Failures set visible state rather than being swallowed.
+
+### Alternate routes
+
+Set `request.requestsAlternateRoutes = true` and `response.routes` holds
+several. Emphasise the first, mute the rest:
 
 ```swift
-request.requestsAlternateRoutes = true
-let response = try await MKDirections(request: request).calculate()
-
-// response.routes contains multiple route options
-// Display all routes, highlight the selected one:
-ForEach(Array(response.routes.enumerated()), id: \.offset) { index, route in
-    MapPolyline(route.polyline)
-        .stroke(index == 0 ? .blue : .gray.opacity(0.5), lineWidth: index == 0 ? 6 : 3)
+ForEach(Array(routes.enumerated()), id: \.offset) { position, option in
+    let isBest = position == 0
+    MapPolyline(option.polyline)
+        .stroke(isBest ? Color.blue : Color.secondary.opacity(0.5), lineWidth: isBest ? 6 : 3)
 }
 ```
 
 ### ETA Calculation
 
-Use `calculateETA()` when you only need travel time, not the full route geometry.
+When only the duration matters, skip the geometry:
 
 ```swift
-func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> TimeInterval {
+func minutesAway(_ request: MKDirections.Request) async throws -> TimeInterval {
+    try await MKDirections(request: request).calculateETA().expectedTravelTime
+}
+```
+
+## Cycling Directions (iOS 14+)
+
+`MKDirectionsTransportType.cycling` has existed since iOS 14; it is not an
+iOS 26 addition.
+
+```swift
+func bikeRoute(toward stop: MKMapItem) async throws -> MKRoute? {
     let request = MKDirections.Request()
-    request.source = source
-    request.destination = destination
+    request.source = .forCurrentLocation()
+    request.destination = stop
+    request.transportType = .cycling
     let directions = MKDirections(request: request)
-    let response = try await directions.calculateETA()
-    return response.expectedTravelTime
+    let reply = try await directions.calculate()
+    return reply.routes.first
 }
 ```
 
----
+## Street-Level Look Around
 
-## Look Around Preview
-
-Show Apple's street-level imagery for a selected location. Availability
-depends on region coverage.
+Look Around is Apple's street-level imagery. Coverage is regional, so always
+plan for "no scene".
 
 ```swift
-struct LookAroundView: View {
-    let mapItem: MKMapItem
+struct StreetPreview: View {
+    let place: MKMapItem
     @State private var scene: MKLookAroundScene?
 
     var body: some View {
-        Group {
+        ZStack {
             if let scene {
                 LookAroundPreview(scene: .constant(scene))
-                    .frame(height: 200)
-                    .clipShape(.rect(cornerRadius: 12))
             } else {
-                ContentUnavailableView("No Look Around",
-                    systemImage: "eye.slash",
-                    description: Text("Look Around is not available here."))
+                ContentUnavailableView("No street view here", systemImage: "eye.slash")
             }
         }
-        .task(id: mapItem) {
+        .frame(height: 200)
+        .clipShape(RoundedRectangle(cornerRadius: 12))
+        .task(id: place) {
             scene = nil
-            let request = MKLookAroundSceneRequest(mapItem: mapItem)
-            scene = try? await request.scene
+            scene = try? await MKLookAroundSceneRequest(mapItem: place).scene
         }
     }
 }
 ```
 
-### Look Around overlay on a Map
+### Street view floating over the map
 
 ```swift
-Map(selection: $selectedItem) { ... }
+Map(selection: $chosen) { /* markers */ }
     .overlay(alignment: .bottomTrailing) {
-        if lookAroundScene != nil {
-            LookAroundPreview(scene: $lookAroundScene)
-                .frame(width: 200, height: 130)
-                .clipShape(.rect(cornerRadius: 10))
+        if streetScene != nil {
+            LookAroundPreview(scene: $streetScene)
+                .frame(width: 200, height: 130, alignment: .center)
+                .clipShape(RoundedRectangle(cornerRadius: 10))
                 .padding()
         }
     }
-    .onChange(of: selectedItem) { _, newItem in
-        guard let item = newItem else {
-            lookAroundScene = nil
-            return
-        }
-        Task {
-            let request = MKLookAroundSceneRequest(mapItem: item)
-            lookAroundScene = try? await request.scene
-        }
+    .onChange(of: chosen) { _, item in
+        guard let item else { streetScene = nil; return }
+        Task { streetScene = try? await MKLookAroundSceneRequest(mapItem: item).scene }
     }
 ```
 
----
-
-## Map Snapshots (MKMapSnapshotter)
+## Still Images with MKMapSnapshotter
 
-Generate a static image of a map region. Useful for share sheets, widgets,
-notifications, or thumbnails.
+A snapshot is a still image of a map: share sheets, widgets, notification
+attachments, list thumbnails.
 
 ```swift
-func generateMapSnapshot(center: CLLocationCoordinate2D,
-                         size: CGSize = CGSize(width: 300, height: 200)) async throws -> UIImage {
+import MapKit
+import UIKit
+
+let cardSize = CGSize(width: 300, height: 200)
+
+func thumbnail(of spot: CLLocationCoordinate2D, fitting frame: CGSize = cardSize) async throws -> UIImage {
+    let size = frame
     let options = MKMapSnapshotter.Options()
-    options.region = MKCoordinateRegion(
-        center: center,
-        span: MKCoordinateSpan(latitudeDelta: 0.01, longitudeDelta: 0.01)
-    )
-    options.size = size
     options.mapType = .standard
     options.showsBuildings = true
+    options.size = size
+    options.region = MKCoordinateRegion(center: spot, latitudinalMeters: 1100, longitudinalMeters: 1100)
+
+    let shot = try await MKMapSnapshotter(options: options).start()
+    let pinPoint = shot.point(for: spot)
+    let symbol = UIImage(systemName: "mappin.circle.fill")
+    let pin = symbol?.withTintColor(.systemRed)
 
-    let snapshotter = MKMapSnapshotter(options: options)
-    let snapshot = try await snapshotter.start()
-
-    // Draw a pin at the center
-    let image = UIGraphicsImageRenderer(size: size).image { context in
-        snapshot.image.draw(at: .zero)
-        let point = snapshot.point(for: center)
-        let pin = UIImage(systemName: "mappin.circle.fill")?
-            .withTintColor(.red, renderingMode: .alwaysOriginal)
-        pin?.draw(at: CGPoint(x: point.x - 15, y: point.y - 30),
-                  blendMode: .normal, alpha: 1.0)
+    return UIGraphicsImageRenderer(size: size).image { _ in
+        shot.image.draw(at: .zero)
+        pin?.draw(at: CGPoint(x: pinPoint.x - 12, y: pinPoint.y - 24))
     }
-    return image
 }
 ```
 
----
+A square of 1100 m is roughly 0.01 degrees of latitude: street level.
+`point(for:)` converts a coordinate into the image's coordinate space.
 
 ## Dense Annotations and Clustering
 
-For dense SwiftUI maps, hide titles at low zoom or reduce visible items based
-on the current camera region. Use `MKMapView` when you need explicit cluster
-configuration.
-
-```swift
-Map {
-    ForEach(allStores) { store in
-        Marker(store.name, systemImage: "cart", coordinate: store.coordinate)
-            .annotationTitles(.hidden)  // Hide titles at low zoom
-    }
-}
-.mapStyle(.standard(pointsOfInterest: .excludingAll))
-```
+SwiftUI `Map` has no cluster configuration. With many markers:
 
-For custom clustering behavior with `MKMapView` (UIKit interop), set
-`clusteringIdentifier` on `MKMarkerAnnotationView`.
+- hide titles at low zoom with `.annotationTitles(.hidden)` on each `Marker`;
+- show only what falls inside the current camera region;
+- drop built-in points of interest with
+  `.mapStyle(.standard(pointsOfInterest: .excludingAll))`.
 
----
+Real clustering needs `MKMapView` through UIKit interop: give each
+`MKMarkerAnnotationView` the same `clusteringIdentifier`.
 
-## MapKit with MKMapItem Utilities
+## MKMapItem Helpers
 
 ### Open in Apple Maps
 
+On iOS 26 build the item from a location; `MKMapItem(placemark:)` is
+deprecated there.
+
 ```swift
-let item = MKMapItem(placemark: MKPlacemark(coordinate: coordinate))
-item.name = "Destination"
-item.openInMaps(launchOptions: [
-    MKLaunchOptionsDirectionsModeKey: MKLaunchOptionsDirectionsModeDriving
-])
+@available(iOS 26, *)
+func openDrivingDirections(to spot: CLLocationCoordinate2D, name: String) {
+    let item = MKMapItem(location: CLLocation(latitude: spot.latitude, longitude: spot.longitude),
+                         address: nil)
+    item.name = name
+    item.openInMaps(launchOptions: [MKLaunchOptionsDirectionsModeKey: MKLaunchOptionsDirectionsModeDriving])
+}
 ```
 
-### Distance Calculation
+Below iOS 26 the same call starts from
+`MKMapItem(placemark: MKPlacemark(coordinate: spot))`.
+
+### Distance
 
 ```swift
-func distanceBetween(_ a: CLLocationCoordinate2D,
-                     _ b: CLLocationCoordinate2D) -> CLLocationDistance {
-    let locA = CLLocation(latitude: a.latitude, longitude: a.longitude)
-    let locB = CLLocation(latitude: b.latitude, longitude: b.longitude)
-    return locA.distance(from: locB) // meters
+func metres(from origin: CLLocationCoordinate2D, to target: CLLocationCoordinate2D) -> CLLocationDistance {
+    let here = CLLocation(latitude: origin.latitude, longitude: origin.longitude)
+    let there = CLLocation(latitude: target.latitude, longitude: target.longitude)
+    return here.distance(from: there)
 }
 ```
 
-### Format Distance for Display
+### Formatting distance
+
+`MKDistanceFormatter` respects the user's locale and units:
 
 ```swift
-let formatter = MKDistanceFormatter()
-formatter.unitStyle = .abbreviated
-let text = formatter.string(fromDistance: 1500) // "0.9 mi" or "1.5 km"
+let distanceText = MKDistanceFormatter()
+distanceText.unitStyle = .abbreviated
+let shown = distanceText.string(fromDistance: 1500)
 ```
 
----
+`shown` is "0.9 mi" for a US-English user and "1.5 km" for most others.
 
-## iOS 26 New APIs
+## Geocoding and Places on iOS 26
 
 ### MKGeocodingRequest
 
-Convert an address string to map items with richer data than `CLGeocoder`:
+Address text in, `MKMapItem`s out, with more detail than `CLGeocoder` gave.
+The initializer is failable.
 
 ```swift
 @available(iOS 26, *)
-func geocodeAddresses(_ addresses: [String]) async -> [MKMapItem] {
-    var items: [MKMapItem] = []
-    for address in addresses {
-        guard let request = MKGeocodingRequest(addressString: address) else { continue }
-        if let mapItems = try? await request.mapItems {
-            items.append(contentsOf: mapItems)
+func resolveAll(_ lines: [String]) async -> [MKMapItem] {
+    var found: [MKMapItem] = []
+    for line in lines {
+        guard let request = MKGeocodingRequest(addressString: line) else { continue }
+        if let items = try? await request.mapItems {
+            found.append(contentsOf: items)
         }
     }
-    return items
+    return found
 }
 ```
 
 ### MKReverseGeocodingRequest
 
-Convert coordinates to map items with `MKAddress`:
-
 ```swift
 @available(iOS 26, *)
-func reverseGeocode(_ coordinate: CLLocationCoordinate2D) async -> MKAddress? {
-    let location = CLLocation(latitude: coordinate.latitude,
-                              longitude: coordinate.longitude)
-    guard let request = MKReverseGeocodingRequest(location: location) else {
-        return nil
-    }
-    let mapItems = try? await request.mapItems
-    return mapItems?.first?.address
+func address(at spot: CLLocation) async throws -> MKAddress? {
+    guard let request = MKReverseGeocodingRequest(location: spot) else { return nil }
+    return try await request.mapItems.first?.address
 }
 ```
 
 ### MKAddress and MKAddressRepresentations
 
-`MKAddress` provides full and short address strings. Use an `MKMapItem`'s
-`MKAddressRepresentations` to format addresses for different contexts:
-
-```swift
-@available(iOS 26, *)
-func formatAddress(for item: MKMapItem) -> String {
-    // Use address representations for locale-aware formatting
-    item.addressRepresentations?.fullAddress(includingRegion: true, singleLine: true)
-        ?? item.address?.fullAddress
-        ?? ""
-}
-```
-
-### PlaceDescriptor (via GeoToolbox)
-
-Create place references from coordinates when you do not have a Place ID:
+`MKAddress` has `fullAddress` and an optional `shortAddress`.
+`MKMapItem.addressRepresentations` formats for a context:
 
 ```swift
-import GeoToolbox
-
 @available(iOS 26, *)
-func mapItem(for myCoordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
-    let descriptor = PlaceDescriptor(
-        representations: [.coordinate(myCoordinate)],
-        commonName: "My Favorite Cafe"
-    )
-
-    let request = MKMapItemRequest(placeDescriptor: descriptor)
-    return try await request.mapItem
+func oneLine(_ item: MKMapItem) -> String {
+    let formats = item.addressRepresentations
+    if let line = formats?.fullAddress(includingRegion: true, singleLine: true) { return line }
+    return item.address?.fullAddress ?? ""
 }
-
-// Use mapItem with any MapKit API: Marker(item:), directions, place cards
 ```
 
-### Cycling Directions (iOS 14+)
-
-```swift
-func cyclingRoute(to destination: MKMapItem) async throws -> MKRoute? {
-    let request = MKDirections.Request()
-    request.source = .forCurrentLocation()
-    request.destination = destination
-    request.transportType = .cycling
-    let response = try await MKDirections(request: request).calculate()
-    return response.routes.first
-}
-```
-
----
-
-## User Location Display
+`addressRepresentations` also offers `cityName`, `cityWithContext` and
+`regionName`.
 
-Show the user's position with the built-in blue dot:
+### PlaceDescriptor (via GeoToolbox)
 
-```swift
-Map(position: $position) {
-    UserAnnotation()       // Blue dot with accuracy ring
-    // ... other content
-}
-.mapControls {
-    MapUserLocationButton()  // Button to re-center on user
-}
-```
+`import GeoToolbox`. A `PlaceDescriptor` names a place by coordinate or
+address when no place ID exists; resolve it with
+`MKMapItemRequest(placeDescriptor:)` and `try await request.mapItem`. The
+result is an ordinary `MKMapItem`, usable with `Marker(item:)`, directions and
+place cards. Example in [SKILL.md](../SKILL.md#placedescriptor-ios-26).
 
-`UserAnnotation()` requires location authorization. If authorization is
-denied, the annotation does not appear and no error is thrown.
+## Showing the User
 
----
+- `UserAnnotation()` in the map content draws the blue dot and accuracy ring.
+- `MapUserLocationButton()` in `.mapControls` recentres on the user.
+- Without authorization the dot simply is not drawn and no error is raised,
+  so a missing dot is a permission question, not a rendering bug.
 
-## Map in a List or ScrollView
+## Maps Inside Scrolling Content
 
-When embedding a `Map` inside a `ScrollView`, disable map gestures that
-conflict with scrolling:
+Map gestures fight with scrolling. Turn them off for a thumbnail, or allow
+only pinch zoom:
 
 ```swift
-ScrollView {
-    Map(position: $position, interactionModes: []) {
-        Marker("Location", coordinate: coord)
-    }
-    .frame(height: 200)
-    .clipShape(.rect(cornerRadius: 12))
-
-    Text("Details below the map...")
+Map(position: $camera, interactionModes: []) {
+    Marker("Venue", coordinate: venue)
 }
+.frame(height: 200)
+.clipShape(RoundedRectangle(cornerRadius: 12))
 ```
 
-Use `interactionModes: []` for a fully static map thumbnail or
-`interactionModes: [.zoom]` to allow pinch-to-zoom without pan conflicts.
-
----
+`interactionModes: [.zoom]` keeps pinch without competing with the scroll.
 
-## Coordinate Utilities
+## Coordinate Math
 
-### Region from an array of coordinates
+### Bounding region for a set of points
 
 ```swift
-func regionForCoordinates(_ coords: [CLLocationCoordinate2D]) -> MKCoordinateRegion {
-    guard !coords.isEmpty else {
-        return MKCoordinateRegion()
-    }
-    var minLat = coords[0].latitude
-    var maxLat = coords[0].latitude
-    var minLon = coords[0].longitude
-    var maxLon = coords[0].longitude
-
-    for coord in coords {
-        minLat = min(minLat, coord.latitude)
-        maxLat = max(maxLat, coord.latitude)
-        minLon = min(minLon, coord.longitude)
-        maxLon = max(maxLon, coord.longitude)
-    }
-
-    let center = CLLocationCoordinate2D(
-        latitude: (minLat + maxLat) / 2,
-        longitude: (minLon + maxLon) / 2
-    )
-    let span = MKCoordinateSpan(
-        latitudeDelta: (maxLat - minLat) * 1.3,  // 30% padding
-        longitudeDelta: (maxLon - minLon) * 1.3
+func enclosingRegion(_ points: [CLLocationCoordinate2D]) -> MKCoordinateRegion {
+    let lats = points.map(\.latitude)
+    let lons = points.map(\.longitude)
+    guard let south = lats.min(), let north = lats.max(),
+          let west = lons.min(), let east = lons.max() else { return MKCoordinateRegion() }
+    return MKCoordinateRegion(
+        center: CLLocationCoordinate2D(latitude: (south + north) / 2, longitude: (west + east) / 2),
+        span: MKCoordinateSpan(latitudeDelta: (north - south) * 1.3,
+                               longitudeDelta: (east - west) * 1.3)
     )
-    return MKCoordinateRegion(center: center, span: span)
 }
 ```
 
+The factor 1.3 leaves 30 percent padding around the points.
+
 ### CLLocationCoordinate2D Equatable conformance
 
-`CLLocationCoordinate2D` does not conform to `Equatable` by default.
-Extend it when needed for comparisons:
+The type is not `Equatable`. Add it with `@retroactive`, which (Swift 5.10
+and later) acknowledges conforming another module's type to another module's
+protocol and silences the warning:
 
 ```swift
 extension CLLocationCoordinate2D: @retroactive Equatable {
-    public static func == (lhs: Self, rhs: Self) -> Bool {
-        lhs.latitude == rhs.latitude && lhs.longitude == rhs.longitude
+    public static func == (a: CLLocationCoordinate2D, b: CLLocationCoordinate2D) -> Bool {
+        a.latitude == b.latitude && a.longitude == b.longitude
     }
 }
 ```
 
-Note: Use `@retroactive` (Swift 5.10+) to silence the warning about
-conforming types from other modules.
-
----
-
 ## Accessibility
 
 ### Marker accessibility
 
-`Marker` views include built-in VoiceOver support using the title string.
-Add `.accessibilityLabel` for richer descriptions:
-
-```swift
-Marker(store.name, coordinate: store.coordinate)
-    .accessibilityLabel("\(store.name), \(store.distanceText) away")
-```
+VoiceOver reads a `Marker`'s title. Add detail when it helps:
+`.accessibilityLabel("\(dock.name), \(distanceText) away")`.
 
 ### Map accessibility
 
-Add a concise description of the map purpose:
+Summarise the map itself:
 
 ```swift
-Map { ... }
+Map(position: $camera) { /* markers */ }
     .accessibilityElement()
-    .accessibilityLabel("Store locations map showing \(stores.count) stores")
+    .accessibilityLabel("Map of \(docks.count) bike docks nearby")
 ```
 
----
-
-## References
+## Apple Documentation
 
-- Apple docs: [MapKit for SwiftUI](https://sosumi.ai/documentation/MapKit/MapKit-for-SwiftUI)
-- Apple docs: [Map](https://sosumi.ai/documentation/MapKit/Map)
-- Apple docs: [MapCameraPosition](https://sosumi.ai/documentation/MapKit/MapCameraPosition)
-- Apple docs: [MKLocalSearch](https://sosumi.ai/documentation/MapKit/MKLocalSearch)
-- Apple docs: [MKDirections](https://sosumi.ai/documentation/MapKit/MKDirections)
-- Apple docs: [MKLookAroundScene](https://sosumi.ai/documentation/MapKit/MKLookAroundScene)
+- [MapKit for SwiftUI](https://developer.apple.com/documentation/mapkit/mapkit-for-swiftui)
+- [Map](https://developer.apple.com/documentation/mapkit/map)
+- [MapCameraPosition](https://developer.apple.com/documentation/mapkit/mapcameraposition)
+- [MKLocalSearch](https://developer.apple.com/documentation/mapkit/mklocalsearch)
+- [MKDirections](https://developer.apple.com/documentation/mapkit/mkdirections)
+- [MKLookAroundScene](https://developer.apple.com/documentation/mapkit/mklookaroundscene)