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)

Open
#2,438 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

auto-triaged bug :beetle:
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.