Constraint
For the Mapbox globe, 5 < zoom < 6 is a distinct globe-to-Mercator morph mode. A custom layer must not independently mix globe and Mercator coordinates inside this interval.
Required approach
Use a surface projected by Mapbox, such as a CanvasSource or another draped path, during the morph. Return a GPU custom layer only at zoom <= 5 or zoom >= 6.
Local point effects use the screen surface at every globe zoom because Mapbox does not support CustomLayerInterface with the globe projection. Marker centers come from Mapbox's public projection and surface-visibility APIs. The beam fallback projects its rotating geodesic sector edges through the same public API on every animation frame. The geographic GPU custom layer is restricted to Mercator. This prevents mobile GPU projection artifacts while preserving one analytic animation phase across projection changes.
During camera movement, Mapbox custom layers receive the current camera matrix directly. The screen fallback is reprojected on every Mapbox render event while retaining the last sampled animation time. Camera motion therefore does not lag behind native layers and does not bypass the viewer FPS cap or advance a frozen 0 FPS animation.
Camera movement reprojects the fallback with current monotonic time on every Mapbox camera frame. Combined with stable MVT identity, this keeps the beam rotating throughout a pinch and preserves the same phase after movement ends.
For MVT point effects, use the stable scalar properties.id when Mapbox does not expose a top-level feature ID. Tile coordinate quantization changes across zoom levels and must never seed a deterministic animation phase.
Point-effect scene assembly is not camera-frame work. Source-data bursts and short repeated camera moves only mark the scene dirty; the runtime keeps drawing the existing geographic instances and performs one rendered-feature query after the camera has settled. This prevents keyboard rotation from repeatedly scanning every marker when only a small subset owns an effect.
Static scalar fields stay on a Mapbox-owned raster surface at every zoom. They do not need the animated-particle GPU path, and keeping one renderer identity prevents an opaque raster such as satellite imagery from changing their persisted layer order at the morph boundaries.
Every global scalar field owns north and south azimuthal textures while a globe pole is visible. At zoom <= 5, a version-pinned custom layer tessellates the ±85°–±90° caps in globe coordinates and alpha-composites those textures above Mapbox's default basemap pole. A renderer-derived edge-clamped texture is always available; a Channel with real polar data may replace it with dedicated native caps. Native-cap loading is an independent enhancement and cannot turn an already accepted Mercator surface into a failed layer.
The polar custom layer returns before drawing throughout 5 < zoom < 6; the Mapbox-owned CanvasSource body alone follows the globe-to-Mercator morph. It is also absent in Mercator at zoom >= 6. Mapbox GL 3.26 joins its globe tile mesh at exactly ±85°, not at the mathematical Web Mercator limit ±85.0511287798066°. Polar texture contracts and the custom cap mesh must use that boundary, Mapbox's unrotated longitude UV, and an edge-padded square or they produce a latitude or filtering seam.
Pre-colored raster tiles and CanvasSource surfaces remain in the same Mapbox ground-drape with raster-elevation: 0 at every zoom. Persisted order is applied through the shared runtime layer registry and Standard top slot, never through depth offsets. A positive elevation is not a safe ordering primitive: Mapbox GL 3.26 classifies it as an experimental 3D raster and intentionally fades the surface near the camera. It can also bypass raster-color presentation and expose a provider's encoded RGB.
Do not publish a ground-level polar ImageSource. Mapbox GL 3.26 treats it as a replacement for its default pole, so transparent NoData pixels expose the clear color as a circular basemap hole. It can also leave the corresponding private painter flag disabled after removal. Compatibility cleanup removes legacy polar ImageSources, but current rendering does not mutate private Mapbox pole state.
Verification points
Every changed geographic overlay must be checked at zoom values 4.99, 5, 5.5, 6, 6.01, and a close camera above provider native max zoom, including zoom while the camera is moving.
The overlay must not:
- Change its visible geographic radius.
- Detach from the ground.
- Fade out merely because the camera approaches it.
- Lose accumulated history when switching renderer.