feat: apply marker diffs over frames and draw flat pins on MapKit

CHANGELOG.md

@@ -29,8 +29,33 @@ fetch the ids on demand when you need them:
 />
 ```
 
+### Behavior changes
+
+**Image-less markers on Apple Maps are flat pins by default**
+
+MapKit used to draw every marker as an `MKMarkerAnnotationView`, the balloon marker with
+a drop and selection animation. Those views are a small view tree each, and MapKit lays
+all of them out on the main thread every frame, which is what limited a map to a few
+hundred visible markers at 120 Hz. Markers without an `image` are now one pre-rendered
+image on a plain `MKAnnotationView`. Pass `pinStyle="system"` to get the balloon back:
+
+```tsx
+<MapView provider="apple" pinStyle="system" />
+```
+
+With flat pins the `system` entering animation is a plain appearance; `fade` and
+`fade-scale` still animate.
+
+**Marker changes reach the map over several frames**
+
+Adds and removals from a viewport refresh used to be applied in one main-thread pass, so a
+zoom into a dense area cost one long frame. They are now spread over frames within a
+budget, nearest to the camera first. During a large change the outer markers appear a few
+frames after the inner ones; no frame waits for all of them.
+
 ### Added
 
+- `pinStyle` prop (`'flat' | 'system'`) for the Apple provider.
 - `MarkerCollection` and `useMarkerCollection`: a native-owned marker dataset updated
   through `set`, `upsert`, `remove` and `updatePositions`, passed to `MapView` with the
   new `markerCollection` prop. Each call ships one packed batch that only carries what
@@ -46,6 +71,9 @@ fetch the ids on demand when you need them:
   dataset, addressed by integer handles, with a spatial index that is updated in place.
 - Cluster badges keep member handles instead of id strings, so a cluster of 100,000
   markers no longer carries 100,000 strings through the render pipeline.
+- The MapKit live refresh during gestures is driven by `CADisplayLink` instead of a
+  wall-clock timer, and clustering reuses the grid cells that stay in view across a pan
+  within one zoom octave.
 
 ## 1.1.0
 

README.md

@@ -54,6 +54,7 @@ Built with [Nitro Modules](https://nitro.margelo.com/) for high-performance nati
 - **Markers and overlays** - Markers with title/subtitle callouts and drag support, plus polylines, polygons, circles, and GeoJSON FeatureCollections.
 - **Markers and overlays** - Markers with title/subtitle callouts and drag support, plus polylines, polygons, and circles.
 - **Delta marker updates** - The marker dataset lives natively. `markers` and `<Marker>` compile to deltas, and `MarkerCollection` updates it directly: one packed batch per change, `updatePositions` for animated markers, nothing re-serialized for markers that did not change.
+- **Frame-budgeted rendering** - Marker changes reach the map SDK over several frames, nearest to the camera first, with a per-frame budget that adapts to the frame rate; a zoom into a dense area no longer costs one long frame.
 - **Native POI taps** - `onPoiPress` reports provider-owned places from Apple Maps and Google Maps without confusing them with app-owned markers.
 - **Camera control** - Declarative region/camera props plus imperative camera helpers.
 - **Marker clustering** - Native marker clustering for large point sets.
@@ -277,7 +278,7 @@ When `provider` is omitted, defaults stay backward-compatible:
 
 Changing `provider` remounts the native map view. Controlled props such as `region`, `camera`, overlays, and callbacks should therefore be supplied again through React props.
 
-Provider-specific TypeScript props are exposed through `MapViewPropsForProvider<P>`. For example, `showsScale` is accepted for `apple` but rejected for `google` because Google Maps SDK has no native scale control.
+Provider-specific TypeScript props are exposed through `MapViewPropsForProvider<P>`. For example, `showsScale` and `pinStyle` are accepted for `apple` but rejected for `google`, because Google Maps SDK has no native scale control and draws its own default marker.
 
 ## Native POI press events
 
@@ -574,6 +575,16 @@ Explicit configs use milliseconds. `duration` defaults to `180`, `delay` default
 
 On Google Maps providers, marker and cluster entering animations can reduce UI-thread frame rate when a large viewport refresh adds many markers at once. The provider caps animated markers per refresh and may show the remaining markers immediately to preserve map gesture performance. For very large marker sets, prefer clustering, shorter durations, or `markerEnteringAnimation={false}` / `clusterEnteringAnimation={false}` when smooth gestures are more important than entrance motion.
 
+## Pin style on Apple Maps
+
+Markers without an `image` are drawn by MapKit. By default they are `flat` pins: one pre-rendered image per pin on a plain `MKAnnotationView`, which MapKit can move by the hundred at 120 Hz. `pinStyle="system"` switches to `MKMarkerAnnotationView`, the balloon marker with its drop and selection animations, at a higher per-marker cost:
+
+```tsx
+<MapView provider="apple" pinStyle="system" />
+```
+
+The prop is accepted for the `apple` provider and the default provider on iOS; Google Maps draws its own default marker. With flat pins the `system` entering animation is a plain appearance; use `fade` or `fade-scale` for motion.
+
 ## Re-renders
 
 Nitro compares view props by reference identity, so a prop rebuilt from unchanged data would still be re-serialized across JSI and re-applied to the native map. `MapView` guards against that on your behalf:
@@ -616,6 +627,7 @@ setMarkers((current) =>
 | Scale control              | Supported                                                   | Unsupported                                | Unsupported                                |
 | Markers / overlays         | Supported                                                   | Supported                                  | Supported                                  |
 | Marker collections (deltas) | Supported                                                  | Supported                                  | Supported                                  |
+| Pin style                  | `flat` (default) or `system`                                | Google default marker                      | Google default marker                      |
 | Custom marker images       | Supported                                                   | Supported                                  | Supported                                  |
 | Marker callouts / dragging | Supported                                                   | Supported                                  | Supported                                  |
 | Overlay press events       | Supported                                                   | Supported                                  | Supported                                  |
@@ -658,6 +670,7 @@ setMarkers((current) =>
 | `Camera`                   | Position, zoom, heading, pitch                       |
 | `MapType`                  | `'standard' \| 'satellite' \| 'hybrid' \| 'terrain'` |
 | `MapProvider`              | `'apple' \| 'google' \| 'openstreetmap' \| 'mapbox'` |
+| `MarkerPinStyle`           | `'flat' \| 'system'`, Apple MapKit pin rendering     |
 | `PoiPressEvent`            | Provider-discriminated native POI press payload             |
 | `ApplePoiPressEvent`       | Apple Maps POI payload with category                        |
 | `GooglePoiPressEvent`      | Google Maps POI payload with place ID                       |

docs/adr/0006-frame-budgeted-rendering.md

@@ -0,0 +1,76 @@
+# ADR 0006: Frame-budgeted marker rendering
+
+## Status
+
+Accepted
+
+## Context
+
+After [ADR 0005](0005-marker-collection-store.md) the transport is O(Δ), but the render
+layer still applied every viewport diff in one main-thread pass. Zooming into a dense area
+or crossing a cluster octave produced diffs of several hundred adds and removals; on
+MapKit each add was an `MKMarkerAnnotationView`, a small view tree that MapKit lays out
+on the main thread every frame, so the frame that applied the diff ran for 100–300 ms and
+every later frame paid for the views that stayed. The MapKit live refresh during gestures
+ran off a wall-clock `Timer`, so its applies landed at arbitrary points in a frame, and
+clustering rebuilt every bucket from scratch on every refresh even when a pan within one
+zoom octave had only moved the viewport by a few cells.
+
+The performance audit rated these the next items after the transport: bounded apply
+passes with a frame budget (P1), lightweight MapKit annotation views (P1) and an
+incremental cluster cache, plus vsync-aligned refresh (P3).
+
+## Decision
+
+- **A frame-budgeted apply scheduler per map.** `MarkerApplyScheduler` (Swift) and
+  `MarkerApplyQueue` + `MarkerApplyScheduler` (Kotlin) hold one pending diff. Each step
+  applies all removals first, then a bounded number of adds sorted by distance to the
+  viewport centre, then retained updates until a 2 ms budget is spent. The add count
+  starts at 32, halves after a frame longer than 1.5× the display interval and grows by
+  half after a frame within 1.1× of it, between 8 and 256, but never above three quarters
+  of the last count that dropped a frame; that ceiling creeps up by one per good frame, so
+  a one-off hitch does not pin the rate and a real limit is probed slowly. The scheduler runs a
+  `CADisplayLink` / `Choreographer` callback only while work is pending. A new diff
+  replaces the pending one: diffs are computed against what is on the map, so anything
+  not yet applied is either in the new diff again or no longer wanted.
+- **Flat pins by default on MapKit.** Image-less markers use `NitroFlatPinAnnotationView`,
+  an `MKAnnotationView` with one pre-rendered pin image per screen scale. `pinStyle="system"`
+  keeps `MKMarkerAnnotationView`. Google providers are unaffected.
+- **Vsync-aligned live refresh.** The MapKit adapter's 10 Hz `Timer` is replaced by a
+  display link that triggers a viewport refresh at most every 100 ms while the camera
+  moves and is stopped otherwise.
+- **Octave cache for clustering.** `ClusterOctaveCache` keeps the buckets of the cells
+  that were fully inside the previous padded viewport, keyed by cell, for as long as the
+  cell size (zoom octave) and the dataset generation stay the same. Cells that entered are
+  accumulated from the candidates; cells that left are dropped. Edge cells that the
+  candidate region only partially covers are never cached. The union-find merge works on
+  copies so cached buckets are not mutated. The cache is off across the antimeridian,
+  where cell keys depend on the viewport's own longitude reference.
+
+## Consequences
+
+- The worst frame of a viewport change is bounded by the per-frame add count instead of
+  the diff size. During a large change the map fills from the centre outwards over a few
+  frames.
+- Apple markers look different by default. The flat pin is drawn to resemble the system
+  marker; apps that want the balloon and its animations set `pinStyle="system"`.
+- Entering animations on MapKit: `fade` and `fade-scale` work on flat pins; `system` has
+  no drop animation there.
+- A diff superseded mid-way leaves the map exactly as the next diff expects; there is no
+  partial-state bookkeeping beyond the versions of what was actually applied.
+- The cluster cache holds about one padded viewport of buckets per map. Any dataset change
+  invalidates it, so live-updating clustered datasets get no reuse; static datasets get
+  reuse for every pan within an octave.
+
+## Alternatives considered
+
+- **A fixed chunk size per frame.** Simpler, but the right number differs by SDK, device
+  and view class. The observed frame interval is the only signal that includes what the
+  SDK does after our call returns.
+- **Measuring our own apply time as the budget.** MapKit and Google Maps create views and
+  upload icons after the apply call, in their own layout pass, so the time inside
+  `addAnnotations` says little about the frame's cost.
+- **An `MKOverlayRenderer` sprite layer for bulk markers.** Would remove per-marker views
+  entirely above a few hundred visible markers, at the cost of a second rendering path
+  and no per-marker hit testing. Left for a later phase; the scheduler and flat pins
+  keep the annotation model.

docs/architecture.md

@@ -93,6 +93,7 @@ Map and overlay callbacks are wired through Nitro listeners on the HybridView. C
 | `mapPadding` | Edge insets in density-independent pixels. Applied via `layoutMargins` (iOS) or `setPadding` (Android). |
 | `fitToCoordinates(coords, padding?, animated?)` | Imperative ref method; fits camera to a set of coordinates with optional padding. |
 | `markerCollection` | A `MarkerCollection` owned by the app. Replaces `markers` and `<Marker>` children; updated through `set`, `upsert`, `remove` and `updatePositions`. |
+| `pinStyle` | Apple MapKit only. `flat` (default) draws image-less markers as one pre-rendered image on an `MKAnnotationView`; `system` uses `MKMarkerAnnotationView`. |
 | `getClusterMembers(clusterId)` | Imperative ref method; resolves the marker ids inside a displayed cluster. |
 
 ### Platform gaps (Phase 8)
@@ -109,6 +110,8 @@ Map and overlay callbacks are wired through Nitro listeners on the HybridView. C
 
 Markers take a different route, because their datasets are large and change often. The dataset lives in a native `MarkerStore` behind the `MarkerCollection` HybridObject. JS assigns every marker an integer handle, keeps the last descriptor it sent per id, and compiles `set` / `upsert` / `remove` / `updatePositions` into packed batches (`src/markers/markerBatch.ts`: a fixed-size record per upsert, four bytes per removal, 24 bytes per position update, plus a string table). The `markers` prop and `<Marker>` children compile to the same batches through a collection `MapView` owns. Natively the store decodes batches on a background thread into flat coordinate arrays, flags, versions and one descriptor per handle, keeps a grid index over handles that is updated in place, and notifies every attached map view. The map's pipeline queries the index for the viewport, clusters or thins the candidate handles, materializes descriptors only for what will be displayed, and diffs by `(handle, id)` against what is on screen. See [ADR 0005](adr/0005-marker-collection-store.md).
 
+The diff does not reach the map SDK in one pass. A per-map scheduler driven by `CADisplayLink` on iOS and `Choreographer` on Android applies removals at once, then a bounded number of adds per frame, nearest to the camera first, then retained updates within a 2 ms budget; the add count halves after a long frame and grows back on frames within budget. A newer diff replaces whatever is still pending, which is safe because diffs are computed against what is actually on the map. On MapKit the live refresh during gestures runs off the same display link instead of a wall-clock timer, and image-less markers are flat pre-rendered pins unless `pinStyle="system"` asks for `MKMarkerAnnotationView`. Clustering keeps the buckets of the cells that were fully inside the previous padded viewport for as long as the zoom octave and the dataset stay the same, so a pan only accumulates the cells that entered. See [ADR 0006](adr/0006-frame-budgeted-rendering.md).
+
 Marker and marker-cluster entering animations follow the same descriptor model. The public API accepts `false`, `system`, or a serializable preset config; the React wrapper normalizes that into native descriptors. Native provider adapters execute the animation when a marker render element appears in the render diff. Updating animation config for an already retained marker does not restart the animation; the new config is used the next time that marker is added again.
 
 Google Maps SDKs are sensitive to marker animation churn. Large viewport refreshes can add many native marker instances on the main thread, so the Google provider limits how many markers animate per refresh and reveals the rest immediately. This keeps gestures responsive, but very large marker sets may still need clustering, disabled entering animations, or a future provider-specific animation strategy.