mapbox / mapbox/mapbox-maps-ios
Visible two-stage full-viewport flash during globe/mercator projection handoff on 11.26.0 (not visible on 11.24.3)
Nobody has claimed this yet.
- Dominant language
- Swift
- Stars
- 601
- Forks
- 196
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
On Mapbox Maps iOS 11.26.0, our app (a run-club discovery app) shows a full-map two-stage visual flash during continuous zoom-out. The same app code on 11.24.3 does not visibly flash on device.
The flash is the mercator-to-globe projection handoff. That handoff exists structurally on both versions. 11.26.0 renders it as an abrupt, visible discontinuity; 11.24.3 renders the same handoff smoothly enough that it is not perceived.
## Environment
- MapboxMaps 11.24.3: no visible flash (good)
- MapboxMaps 11.26.0: visible flash (regressed)
- MapboxMaps 11.25.x: not tested
- Device: iPhone 15 Pro (iPhone16,1), iOS 26.6, device builds
- A/B on device with identical app code: reproduced twice
- Styles: classic `outdoors-v12` / `dark-v11` (both declare `projection: globe`)
- Map setup: one clustered `PointAnnotationManager` (~2.3k points, `clusterRadius` 22, `clusterMaxZoom` 20); one empty overlay `PointAnnotationManager`; camera ease sweeps
Related commits in the 11.24.3 → 11.26.0 window (not asserted as root cause): view-annotation collision work (#12646, #15549, #15651) and "Fix black flash when removing/re-adding annotations" (#12326).
## Steps to reproduce
1. Load a classic style that declares `projection: globe` (`mapbox://styles/mapbox/outdoors-v12` or `dark-v11`).
2. Add ~2.3k clustered point annotations as above.
3. Continuously pinch-zoom or ease-zoom out from zoom 13 to zoom 1.
4. Observe the z5–7 band.
## Expected
Smooth globe–mercator projection transition, as rendered on 11.24.3 on device. No perceptible full-viewport flash.
## Actual
Two distinct full-viewport flashes in the z5–7 projection-handoff band during continuous zoom-out on 11.26.0.
On simulator, per-frame analysis of four instrumented full-range zoom sweeps (zoom 13 → 1 → 13) shows the visual discontinuity band on both 11.24.3 and 11.26.0; on device, only 11.26.0 is visibly flashing.
## Ruled out (app-side)
- Second (empty) point-annotation manager: removing it does not remove the events.
- View annotations / placement machinery: events persist with those removed.
- Attribution check: `setProjection(.mercator)` at style load produces zero transition events on 11.26 (machine-verified), confirming the events are the projection transition, not annotation lifecycle.
## Additional evidence
Per-frame `RenderFrameFinished` telemetry (renderMode / placementChanged per frame with zoom) and A/B screen recordings (device and simulator) are available on request.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue on an iPhone 15 Pro using MapboxMaps 11.26.0 and 11.24.3, the specified globe styles, clustered annotations, and zoom sweep from 13 to 1. Compare device behavior with the available RenderFrameFinished telemetry and simulator recordings; done means the z5–7 handoff no longer produces a perceptible full-viewport flash on 11.26.0.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ios, swift
- Domain
- computer-graphics, mobile-dev
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100