Update to Mapbox

{
  "name": "mapbox-ios-patterns",
  "description": "Official integration patterns for Mapbox Maps SDK on iOS. Covers installation, adding markers, user location, custom data, styles, camera control, and featureset interactions. Based on official Mapbox documentation.",
  "included_files": [
    {
      "relative_path": "AGENTS.md",
      "size_in_bytes": 6287
    },
    {
      "relative_path": "evals/evals.json",
      "size_in_bytes": 2557
    },
    {
      "relative_path": "references/annotations.md",
      "size_in_bytes": 3160
    },
    {
      "relative_path": "references/camera-styles.md",
      "size_in_bytes": 2001
    },
    {
      "relative_path": "references/custom-data.md",
      "size_in_bytes": 2653
    },
    {
      "relative_path": "references/interactions.md",
      "size_in_bytes": 3708
    },
    {
      "relative_path": "references/location-tracking.md",
      "size_in_bytes": 1700
    }
  ],
  "skill_md_contents": "---\nname: mapbox-ios-patterns\ndescription: Official integration patterns for Mapbox Maps SDK on iOS. Covers installation, adding markers, user location, custom data, styles, camera control, and featureset interactions. Based on official Mapbox documentation.\n---\n\n# Mapbox iOS Integration Patterns\n\nOfficial patterns for integrating Mapbox Maps SDK v11 on iOS with Swift, SwiftUI, and UIKit.\n\n**Use this skill when:**\n\n- Installing and configuring Mapbox Maps SDK for iOS\n- Adding markers and annotations to maps\n- Showing user location and tracking with camera\n- Adding custom data (GeoJSON) to maps\n- Working with map styles, camera, or user interaction\n- Handling feature interactions and taps\n\n**Official Resources:**\n\n- [iOS Maps Guides](https://docs.mapbox.com/ios/maps/guides/)\n- [API Reference](https://docs.mapbox.com/ios/maps/api-reference/)\n- [Example Apps](https://github.com/mapbox/mapbox-maps-ios/tree/main/Sources/Examples)\n\n---\n\n## Installation & Setup\n\n### Requirements\n\n- iOS 14+\n- Xcode 15+\n- Swift 5.9+\n- Free Mapbox account\n\n### Step 1: Configure Access Token\n\nAdd your public token to `Info.plist`:\n\n```xml\n<key>MBXAccessToken</key>\n<string>pk.your_mapbox_token_here</string>\n```\n\n**Get your token:** Sign in at [mapbox.com](https://account.mapbox.com/access-tokens/)\n\n### Step 2: Add Swift Package Dependency\n\n1. **File → Add Package Dependencies**\n2. **Enter URL:** `https://github.com/mapbox/mapbox-maps-ios.git`\n3. **Version:** \"Up to Next Major\" from `11.0.0`\n4. **Verify** four dependencies appear: MapboxCommon, MapboxCoreMaps, MapboxMaps, Turf\n\n**Alternative:** CocoaPods or direct download ([install guide](https://docs.mapbox.com/ios/maps/guides/install/))\n\n---\n\n## Map Initialization\n\n### SwiftUI Pattern\n\n**Basic map:**\n\n```swift\nimport SwiftUI\nimport MapboxMaps\n\nstruct ContentView: View {\n    @State private var viewport: Viewport = .camera(\n        center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),\n        zoom: 12\n    )\n\n    var body: some View {\n        Map(viewport: $viewport)\n            .mapStyle(.standard)\n    }\n}\n```\n\n**With ornaments:**\n\n```swift\nMap(viewport: $viewport)\n    .mapStyle(.standard)\n    .ornamentOptions(OrnamentOptions(\n        scaleBar: .init(visibility: .visible),\n        compass: .init(visibility: .adaptive),\n        logo: .init(position: .bottomLeading)\n    ))\n```\n\n### UIKit Pattern\n\n```swift\nimport UIKit\nimport MapboxMaps\n\nclass MapViewController: UIViewController {\n    private var mapView: MapView!\n\n    override func viewDidLoad() {\n        super.viewDidLoad()\n\n        let options = MapInitOptions(\n            cameraOptions: CameraOptions(\n                center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),\n                zoom: 12\n            )\n        )\n\n        mapView = MapView(frame: view.bounds, mapInitOptions: options)\n        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]\n        view.addSubview(mapView)\n\n        mapView.mapboxMap.loadStyle(.standard)\n    }\n}\n```\n\n---\n\n## Add Markers\n\nThe SDK offers three ways to place a point on the map. Pick the simplest one that fits.\n\n**Agent note:** A SwiftUI Mapbox sketch is incomplete without at least one annotation (`Marker`, `PointAnnotation`, or `MapViewAnnotation`). Do not ship a bare `Map { }` with no pin.\n\n### Which API should I use?\n\n| API                                                       | Use it when                                                                                    | Platforms       | Notes                                                                                                                                                                        |\n| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `Marker` (Markers API)                                    | You need a default pin and don't have a custom image asset                                     | SwiftUI only    | No image assets required. Experimental SPI — needs `@_spi(Experimental) import MapboxMaps`. Best < 100 markers.                                                              |\n| `PointAnnotation`                                         | You have a custom image and want layer-level placement                                         | SwiftUI + UIKit | Backed by a symbol layer, so it scales well to hundreds of markers. Accepts any `UIImage` that `UIKit` can render.                                                           |\n| View annotations (`ViewAnnotation` / `MapViewAnnotation`) | You want to render a full native view (card, badge, animated content) anchored to a coordinate | SwiftUI + UIKit | SwiftUI uses `MapViewAnnotation`; UIKit uses `mapView.viewAnnotations` with a `ViewAnnotation`. Each annotation is a real view — costs more than `PointAnnotation` at scale. |\n\nFor hundreds or thousands of features, use a style layer (`SymbolLayer` on a `GeoJSONSource`) instead of annotations.\n\n### Markers API (recommended for simple cases, SwiftUI)\n\n```swift\nimport SwiftUI\n@_spi(Experimental) import MapboxMaps\n\nstruct ContentView: View {\n    var body: some View {\n        Map {\n            Marker(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))\n                .color(.red)\n                .text(\"San Francisco\")\n        }\n    }\n}\n```\n\nMultiple markers from a collection:\n\n```swift\nMap {\n    ForEvery(locations, id: \\.id) { location in\n        Marker(coordinate: location.coordinate)\n            .color(.red)\n            .text(location.name)\n    }\n}\n```\n\n> **Scaling note.** `Marker` and `PointAnnotation` each create their own view or symbol entry per pin — fine up to about 100 markers. For larger datasets (hundreds or thousands of features — common with open-ended GeoJSON feeds), load the data into a `GeoJSONSource` and render it with a `SymbolLayer` instead. That scales to thousands of features and enables clustering.\n\n### PointAnnotation (custom image)\n\n**SwiftUI:**\n\n```swift\nMap(viewport: $viewport) {\n    PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))\n        .image(.init(image: UIImage(named: \"marker\")!, name: \"marker\"))\n}\n```\n\n**UIKit:**\n\n```swift\n// Create annotation manager (once, reuse for updates)\nvar pointAnnotationManager = mapView.annotations.makePointAnnotationManager()\n\n// Create marker\nvar annotation = PointAnnotation(coordinate: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194))\nannotation.image = .init(image: UIImage(named: \"marker\")!, name: \"marker\")\nannotation.iconAnchor = .bottom\n\n// Add to map\npointAnnotationManager.annotations = [annotation]\n```\n\n**Multiple markers:**\n\n```swift\nlet annotations = locations.map { coordinate in\n    var annotation = PointAnnotation(coordinate: coordinate)\n    annotation.image = .init(image: UIImage(named: \"marker\")!, name: \"marker\")\n    return annotation\n}\n\npointAnnotationManager.annotations = annotations\n```\n\n---\n\n## Show User Location\n\n**Step 1: Add location permission to Info.plist:**\n\n```xml\n<key>NSLocationWhenInUseUsageDescription</key>\n<string>Show your location on the map</string>\n```\n\n**Step 2: Request permissions and show location:**\n\n```swift\nimport CoreLocation\n\n// Request permissions\nlet locationManager = CLLocationManager()\nlocationManager.requestWhenInUseAuthorization()\n\n// Show user location puck\nmapView.location.options.puckType = .puck2D()\nmapView.location.options.puckBearingEnabled = true\n```\n\n---\n\n## Performance Best Practices\n\n### Reuse Annotation Managers\n\n```swift\n// ❌ Don't create new managers repeatedly\nfunc updateMarkers() {\n    let manager = mapView.annotations.makePointAnnotationManager()\n    manager.annotations = markers\n}\n\n// ✅ Create once, reuse\nlet pointAnnotationManager: PointAnnotationManager\n\ninit() {\n    pointAnnotationManager = mapView.annotations.makePointAnnotationManager()\n}\n\nfunc updateMarkers() {\n    pointAnnotationManager.annotations = markers\n}\n```\n\n### Batch Annotation Updates\n\n```swift\n// ✅ Update all at once\npointAnnotationManager.annotations = newAnnotations\n\n// ❌ Don't update one by one\nfor annotation in newAnnotations {\n    pointAnnotationManager.annotations.append(annotation)\n}\n```\n\n### Memory Management\n\n```swift\n// Use weak self in closures\nmapView.gestures.onMapTap.observe { [weak self] context in\n    self?.handleTap(context.coordinate)\n}.store(in: &cancelables)\n\n// Clean up on deinit\ndeinit {\n    cancelables.forEach { $0.cancel() }\n}\n```\n\n### Use Standard Style\n\n```swift\n// ✅ Standard style is optimized and recommended\n.mapStyle(.standard)\n\n// Use other styles only when needed for specific use cases\n.mapStyle(.standardSatellite) // Satellite imagery\n```\n\n---\n\n## Troubleshooting\n\n### Map Not Displaying\n\n**Check:**\n\n1. ✅ `MBXAccessToken` in Info.plist\n2. ✅ Token is valid (test at mapbox.com)\n3. ✅ MapboxMaps framework imported\n4. ✅ MapView added to view hierarchy\n5. ✅ Correct frame/constraints set\n\n### Style Not Loading\n\n```swift\nmapView.mapboxMap.onStyleLoaded.observe { [weak self] _ in\n    print(\"Style loaded successfully\")\n    // Add layers and sources here\n}.store(in: &cancelables)\n```\n\n### Performance Issues\n\n- Use `.standard` style (recommended and optimized)\n- Limit visible annotations to viewport\n- Reuse annotation managers\n- Avoid frequent style reloads\n- Batch annotation updates\n\n---\n\n## Reference Files\n\nLoad these references when the task requires deeper patterns:\n\n- **`references/annotations.md`** — Circle, Polyline, Polygon Annotations\n- **`references/location-tracking.md`** — Camera Follow User + Get Current Location\n- **`references/custom-data.md`** — GeoJSON: Lines, Polygons, Points, Update/Remove\n- **`references/camera-styles.md`** — Camera Control + Map Styles\n- **`references/interactions.md`** — Featureset Interactions, Custom Layer Taps, Long Press, Gestures\n\n---\n\n## Additional Resources\n\n- [iOS Maps Guides](https://docs.mapbox.com/ios/maps/guides/)\n- [API Reference](https://docs.mapbox.com/ios/maps/api/11.18.1/documentation/mapboxmaps/)\n- [Interactions Guide](https://docs.mapbox.com/ios/maps/guides/user-interaction/Interactions/)\n- [SwiftUI User Guide](https://docs.mapbox.com/ios/maps/api/11.18.1/documentation/mapboxmaps/swiftui-user-guide)\n- [Example Apps](https://github.com/mapbox/mapbox-maps-ios/tree/main/Sources/Examples)\n- [Migration Guide (v10 → v11)](https://docs.mapbox.com/ios/maps/guides/migrate-to-v11/)\n"
}