maplibre-gl 6.2.0 → 6.4.0

package/src/style/style.ts

@@ -5,6 +5,7 @@ import {isRasterStyleLayer} from './style_layer/raster_style_layer.ts';
 import {createStyleLayer} from './create_style_layer.ts';
 import {loadSprite} from './load_sprite.ts';
 import {ImageManager, type MissingImageRequestHandler} from '../render/image_manager.ts';
+import {PatternAtlas} from '../render/pattern_atlas.ts';
 import {GlyphManager} from '../render/glyph_manager.ts';
 import {Light} from './light.ts';
 import {Sky} from './sky.ts';
@@ -205,6 +206,7 @@ export class Style extends Evented<MapEventType> {
     stylesheet: StyleSpecification;
     dispatcher: Dispatcher;
     imageManager: ImageManager;
+    patternAtlas: PatternAtlas;
     glyphManager: GlyphManager;
     lineAtlas: LineAtlas;
     light: Light;
@@ -229,10 +231,6 @@ export class Style extends Evented<MapEventType> {
     _glyphsDidChange: boolean;
     _updatedPaintProps: {[layer: string]: true};
     _layerOrderChanged: boolean;
-    // image ids of images loaded from style's sprite
-    _spritesImagesIds: {[spriteId: string]: string[]};
-    // image ids of all images loaded (sprite + user)
-    _availableImages: string[];
     _globalState: Record<string, any>;
     crossTileSymbolIndex: CrossTileSymbolIndex;
     pauseablePlacement: PauseablePlacement;
@@ -256,6 +254,7 @@ export class Style extends Evented<MapEventType> {
         this.imageManager = new ImageManager();
         this.imageManager.setEventedParent(this);
         this.imageManager.setMissingImageResolver(map._missingStyleImageResolver);
+        this.patternAtlas = new PatternAtlas(this.imageManager);
         const glyphLang = map._container?.lang || (typeof document !== 'undefined' && document.documentElement?.lang) || undefined;
         this.glyphManager = new GlyphManager(map._requestManager, options.localIdeographFontFamily, glyphLang);
         this.lineAtlas = new LineAtlas(256, 512);
@@ -293,12 +292,10 @@ export class Style extends Evented<MapEventType> {
     }
 
     private _setInitialValues() {
-        this._spritesImagesIds = {};
         this._layers = {};
         this._order = [];
         this.tileManagers = {};
         this.zoomHistory = new ZoomHistory();
-        this._availableImages = [];
         this._imagesListDirty = false;
         this._globalState = {};
         this._serializedLayers = {};
@@ -529,73 +526,46 @@ export class Style extends Evented<MapEventType> {
         }
     }
 
-    _loadSprite(sprite: SpriteSpecification, isUpdate: boolean = false, completion: (err: Error) => void = undefined): void {
+    async _loadSprite(sprite: SpriteSpecification, isUpdate: boolean = false, completion: (err: Error) => void = undefined): Promise<void> {
         this.imageManager.setLoaded(false);
 
         const abortController = new AbortController();
         this._spriteRequest = abortController;
         let err: Error;
-        loadSprite(sprite, this.map._requestManager, this.map.getPixelRatio(), this._spriteRequest).then((images) => {
-            this._spriteRequest = null;
-            if (images) {
-                for (const spriteId in images) {
-                    this._spritesImagesIds[spriteId] = [];
-
-                    // remove old sprite's loaded images (for the same sprite id) that are not in new sprite
-                    const imagesToRemove = this._spritesImagesIds[spriteId] ? this._spritesImagesIds[spriteId].filter(id => !(id in images)) : [];
-                    for (const id of imagesToRemove) {
-                        this.imageManager.removeImage(id);
-                        this._changedImages[id] = true;
-                    }
-
-                    for (const id in images[spriteId]) {
-                        // don't prefix images of the "default" sprite
-                        const imageId = spriteId === 'default' ? id : `${spriteId}:${id}`;
-                        // save all the sprite's images' ids to be able to delete them in `removeSprite`
-                        this._spritesImagesIds[spriteId].push(imageId);
-                        if (imageId in this.imageManager.images) {
-                            this.imageManager.updateImage(imageId, images[spriteId][id], false);
-                        } else {
-                            this.imageManager.addImage(imageId, images[spriteId][id]);
-                        }
-
-                        if (isUpdate) {
-                            this._changedImages[imageId] = true;
-                        }
-                    }
+        try {
+            const images = await loadSprite(sprite, this.map._requestManager, this.map.getPixelRatio(), abortController);
+            if (!images) return;
+
+            for (const spriteId in images) {
+                const {loaded, removed} = this.imageManager.setSpriteImages(spriteId, images[spriteId]);
+                this._markImagesChanged(removed);
+                if (isUpdate) {
+                    this._markImagesChanged(loaded);
                 }
             }
-        }).catch((error) => {
-            this._spriteRequest = null;
+        } catch (error) {
             err = error;
             if (!abortController.signal.aborted) { // ignore abort
                 this.fire(new ErrorEvent(err));
             }
-        }).finally(() => {
+        } finally {
+            this._spriteRequest = null;
             this.imageManager.setLoaded(true);
-            this._availableImages = this.imageManager.listImages();
 
             if (isUpdate) {
                 this._changed = true;
             }
 
-            this.dispatcher.broadcast(MessageType.setImages, this._availableImages);
+            this.dispatcher.broadcast(MessageType.setImages, this.imageManager.listImages());
             this.fire(new MapStyleDataEvent('data'));
 
-            if (completion) {
-                completion(err);
-            }
-        });
+            completion?.(err);
+        }
     }
 
     _unloadSprite(): void {
-        for (const id of Object.values(this._spritesImagesIds).flat()) {
-            this.imageManager.removeImage(id);
-            this._changedImages[id] = true;
-        }
+        this._markImagesChanged(this.imageManager.removeAllSpriteImages());
 
-        this._spritesImagesIds = {};
-        this._availableImages = this.imageManager.listImages();
         this._imagesListDirty = true;
         this._changed = true;
         this.fire(new MapStyleDataEvent('data'));
@@ -731,7 +701,7 @@ export class Style extends Evented<MapEventType> {
         const changed = this._changed;
         if (changed) {
             if (this._imagesListDirty) {
-                this.dispatcher.broadcast(MessageType.setImages, this._availableImages);
+                this.dispatcher.broadcast(MessageType.setImages, this.imageManager.listImages());
                 this._imagesListDirty = false;
             }
 
@@ -779,10 +749,11 @@ export class Style extends Evented<MapEventType> {
 
         // loop all layers and find layers that are not hidden at parameters.zoom
         // and set used to true in tileManagers dictionary for the sources of these layers
+        const availableImages = this.imageManager.listImages();
         for (const layerId of this._order) {
             const layer = this._layers[layerId];
 
-            layer.recalculate(parameters, this._availableImages);
+            layer.recalculate(parameters, availableImages);
             if (!layer.isHidden(parameters.zoom) && layer.source) {
                 this.tileManagers[layer.source].used = true;
             }
@@ -1005,8 +976,17 @@ export class Style extends Evented<MapEventType> {
         this._afterImageUpdated(id);
     }
 
+    /**
+     * Queues the tiles that depend on these images to be reloaded on the next update, which is
+     * needed whenever an image appears, disappears or changes size.
+     */
+    _markImagesChanged(ids: string[]): void {
+        for (const id of ids) {
+            this._changedImages[id] = true;
+        }
+    }
+
     _afterImageUpdated(id: string): void {
-        this._availableImages = this.imageManager.listImages();
         this._changedImages[id] = true;
         this._imagesListDirty = true;
         this._changed = true;
@@ -1616,7 +1596,7 @@ export class Style extends Evented<MapEventType> {
 
         const sourceResults: QueryRenderedFeaturesResults[] = [];
 
-        params.availableImages = this._availableImages;
+        params.availableImages = this.imageManager.listImages();
 
         // LayerSpecification is serialized StyleLayer, and this casting is safe.
         const serializedLayers = this._serializedAllLayers() as {[_: string]: StyleLayer};
@@ -2000,18 +1980,12 @@ export class Style extends Evented<MapEventType> {
             return;
         }
 
-        if (this._spritesImagesIds[id]) {
-            for (const imageId of this._spritesImagesIds[id]) {
-                this.imageManager.removeImage(imageId);
-                this._changedImages[imageId] = true;
-            }
-        }
+        const changedImages = this.imageManager.removeSpriteImages(id);
+        this._markImagesChanged(changedImages);
 
         internalSpriteRepresentation.splice(internalSpriteRepresentation.findIndex(sprite => sprite.id === id), 1);
         this.stylesheet.sprite = internalSpriteRepresentation.length > 0 ? internalSpriteRepresentation : undefined;
 
-        delete this._spritesImagesIds[id];
-        this._availableImages = this.imageManager.listImages();
         this._imagesListDirty = true;
         this._changed = true;
         this.fire(new MapStyleDataEvent('data'));
@@ -2082,8 +2056,7 @@ export class Style extends Evented<MapEventType> {
         if (this.imageManager) {
             this.imageManager.setEventedParent(null);
             this.imageManager.destroy();
-            this._availableImages = [];
-            this._spritesImagesIds = {};
+            this.patternAtlas.destroy();
         }
 
         // Destroy glyphManager

package/src/style/style_image.ts

@@ -27,6 +27,7 @@ export type StyleImageData = {
     data: RGBAImage;
     version?: number;
     hasRenderCallback?: boolean;
+    isWebGLImage?: boolean;
     userImage?: StyleImageInterface;
     spriteData?: SpriteOnDemandStyleImage;
 };
@@ -91,6 +92,48 @@ export type StyleImageMetadata = {
  */
 export type StyleImage = StyleImageData & StyleImageMetadata;
 
+/**
+ * Where a {@link StyleImageWebGLData.renderWithWebGL} callback writes its pixels.
+ */
+export type StyleImageWebGLTarget = {
+    gl: WebGL2RenderingContext;
+    /**
+     * The icon atlas to write into. MapLibre does not bind it for you, so start with
+     * `gl.bindTexture(gl.TEXTURE_2D, texture)` or attach it to your own framebuffer.
+     */
+    texture: WebGLTexture;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+/**
+ * What a {@link StyleImageInterface} gives as its `data` when it renders itself with WebGL rather
+ * than handing over an array of pixels.
+ *
+ * @see [Animate an icon on the GPU.](https://maplibre.org/maplibre-gl-js/docs/examples/animate-an-icon-on-the-gpu/)
+ */
+export type StyleImageWebGLData = {
+    /**
+     * Render exactly `width` x `height` premultiplied-alpha pixels at (`x`, `y`) of
+     * `target.texture`. That rectangle is the only part of the shared atlas that belongs to this
+     * image; drawing outside it corrupts the others.
+     *
+     * This is the image's counterpart to {@link CustomLayerInterface.render}, and the context
+     * arrives in the same state a custom layer's is given: cull face, active texture and the pixel
+     * store settings at their WebGL defaults, and no vertex array bound. Everything is yours to
+     * change, and MapLibre restores its own state afterwards. The scissor test is the one
+     * exception: MapLibre never touches it, so an image that enables it has to disable it again.
+     *
+     * Called before the first frame the image is used in, again whenever
+     * {@link StyleImageInterface.render} returns `true`, and again for each atlas holding a slot
+     * this image has never rendered into, so one change may mean several calls with different
+     * targets.
+     */
+    renderWithWebGL: (target: StyleImageWebGLTarget) => void;
+};
+
 /**
  * Interface for dynamically generated style images. This is a specification for
  * implementers to model: it is not an exported method or class.
@@ -148,7 +191,13 @@ export type StyleImage = StyleImageData & StyleImageMetadata;
 export interface StyleImageInterface {
     width: number;
     height: number;
-    data: Uint8Array | Uint8ClampedArray;
+    /**
+     * The image's pixels, in the same format as `ImageData`, or a {@link StyleImageWebGLData}
+     * callback that renders them with WebGL. A WebGL image renders straight into its slot of the
+     * shared icon atlas. Nothing new is possible that pixels could not express, but an image that
+     * changes often, such as an animated icon, gets much cheaper: no CPU pixel work and no upload.
+     */
+    data: Uint8Array | Uint8ClampedArray | StyleImageWebGLData;
     /**
      * This method is called once before every frame where the icon will be used.
      * The method can optionally update the image's `data` member with a new image.
@@ -156,6 +205,9 @@ export interface StyleImageInterface {
      * If the method updates the image it must return `true` to commit the change.
      * If the method returns `false` or nothing the image is assumed to not have changed.
      *
+     * An image whose `data` renders with WebGL has nothing to update here; returning `true` is how
+     * it asks for {@link StyleImageWebGLData.renderWithWebGL} to be called again.
+     *
      * If updates are infrequent it maybe easier to use {@link Map.updateImage} to update
      * the image instead of implementing this method.
      *
@@ -171,18 +223,24 @@ export interface StyleImageInterface {
     /**
      * Optional method called when the icon is removed from the map with {@link Map.removeImage}.
      * This gives the image a chance to clean up resources and event listeners.
+     *
+     * This also fires when the WebGL context is lost, after which the same image is added back
+     * without a matching `onAdd`, so the image has to be able to build again whatever it
+     * released here.
      */
     onRemove?: () => void;
 }
 
+export function isStyleImageWebGLData(data: StyleImageInterface['data']): data is StyleImageWebGLData {
+    return typeof (data as StyleImageWebGLData)?.renderWithWebGL === 'function';
+}
+
 export function renderStyleImage(image: StyleImage): boolean {
     const {userImage} = image;
-    if (userImage?.render) {
-        const updated = userImage.render();
-        if (updated) {
-            image.data.replace(new Uint8Array(userImage.data.buffer));
-            return true;
-        }
-    }
-    return false;
+    if (!userImage?.render) return false;
+    const updated = userImage.render();
+    if (!updated) return false;
+
+    if (!isStyleImageWebGLData(userImage.data)) image.data.replace(new Uint8Array(userImage.data.buffer));
+    return true;
 }

package/src/style/style_layer.bench.ts

@@ -0,0 +1,65 @@
+import {bench, describe} from 'vitest';
+import {readFileSync} from 'fs';
+import {VectorTile} from '@mapbox/vector-tile';
+import {PbfReader} from 'pbf';
+import {featureFilter} from '@maplibre/maplibre-gl-style-spec';
+import filters from '../../test/bench/data/filters.json' with {type: 'json'};
+
+import type {VectorTileFeature} from '@mapbox/vector-tile';
+import type {FeatureFilter, FilterSpecification} from '@maplibre/maplibre-gl-style-spec';
+
+type FilteredLayer = {
+    features: VectorTileFeature[];
+    filters: FeatureFilter[];
+};
+
+function readLayers(): FilteredLayer[] {
+    const data = readFileSync(new URL('../../test/bench/data/785.vector.pbf', import.meta.url));
+    const tile = new VectorTile(new PbfReader(new Uint8Array(data)));
+    const layers: FilteredLayer[] = [];
+
+    for (const name in tile.layers) {
+        const layer = tile.layers[name];
+        if (!layer.length) {
+            continue;
+        }
+
+        const features = [];
+        for (let i = 0; i < layer.length; i++) {
+            features.push(layer.feature(i));
+        }
+
+        const layerFilters = [];
+        for (const filter of filters) {
+            if (filter.layer === name) {
+                layerFilters.push(featureFilter(filter.filter as FilterSpecification, 'filter'));
+            }
+        }
+
+        layers.push({features, filters: layerFilters});
+    }
+
+    return layers;
+}
+
+const layers = readLayers();
+
+describe('featureFilter', () => {
+    bench('create', () => {
+        for (const filter of filters) {
+            featureFilter(filter.filter as FilterSpecification, 'filter');
+        }
+    });
+
+    bench('evaluate', () => {
+        for (const layer of layers) {
+            for (const filter of layer.filters) {
+                for (const feature of layer.features) {
+                    if (typeof filter.filter({zoom: 0}, feature) !== 'boolean') {
+                        throw new Error('Expected boolean result from filter');
+                    }
+                }
+            }
+        }
+    });
+});

package/src/style/style_layer.test.ts

@@ -13,7 +13,7 @@ describe('StyleLayer', () => {
     test('instantiates the correct subclass', () => {
         const layer = createStyleLayer({type: 'fill'} as LayerSpecification, {});
 
-        expect(layer instanceof FillStyleLayer).toBeTruthy();
+        expect(layer).toBeInstanceOf(FillStyleLayer);
     });
 });
 

package/src/style/style_layer.ts

@@ -2,7 +2,7 @@ import {filterObject} from '../util/util.ts';
 
 import {createVisibilityExpression, featureFilter, supportsPropertyExpression} from '@maplibre/maplibre-gl-style-spec';
 import {validateStyle, validateAndEmit, type Validator} from './validate_style.ts';
-import {Evented, ErrorEvent} from '../util/evented.ts';
+import {Evented, ErrorEvent, type ErrorEventType} from '../util/evented.ts';
 import {Layout, Transitionable, type Transitioning, type Properties, PossiblyEvaluated, PossiblyEvaluatedPropertyValue, TRANSITION_SUFFIX} from './properties.ts';
 
 import type {Bucket, BucketParameters} from '../data/bucket.ts';
@@ -83,7 +83,7 @@ const ERROR_LAYOUT_NOT_PAINT = ' is a LAYOUT property not a PAINT property. Use
 /**
  * A base class for style layers
  */
-export abstract class StyleLayer extends Evented {
+export abstract class StyleLayer extends Evented<ErrorEventType> {
     id: string;
     metadata: unknown;
     type: LayerSpecification['type'] | CustomLayerInterface['type'];

package/src/style/validate_style.bench.ts

@@ -0,0 +1,11 @@
+import {bench} from 'vitest';
+import {validateStyle} from './validate_style.ts';
+import brightV9 from '../../test/integration/assets/styles/bright-v9.json' with {type: 'json'};
+
+import type {StyleSpecification} from '@maplibre/maplibre-gl-style-spec';
+
+const style = brightV9 as unknown as StyleSpecification;
+
+bench('validateStyle', () => {
+    validateStyle(style);
+});

package/src/style/validate_style.test.ts

@@ -1,9 +1,9 @@
 import {describe, test, expect, vi, afterEach} from 'vitest';
 import {validateAndEmit, validateStyle, validateStyleAndEmit} from './validate_style.ts';
-import {Evented} from '../util/evented.ts';
+import {Evented, type ErrorEventType} from '../util/evented.ts';
 import type {StyleSpecification} from '@maplibre/maplibre-gl-style-spec';
 
-class TestEmitter extends Evented {}
+class TestEmitter extends Evented<ErrorEventType> {}
 
 afterEach(() => {
     vi.restoreAllMocks();

package/src/symbol/anchor.test.ts

@@ -3,8 +3,8 @@ import {Anchor} from './anchor.ts';
 
 describe('Anchor', () => {
     test('constructor', () => {
-        expect(new Anchor(0, 0, 0) instanceof Anchor).toBeTruthy();
-        expect(new Anchor(0, 0, 0, 0) instanceof Anchor).toBeTruthy();
+        expect(new Anchor(0, 0, 0)).toBeInstanceOf(Anchor);
+        expect(new Anchor(0, 0, 0, 0)).toBeInstanceOf(Anchor);
     });
     test('clone', () => {
         const a = new Anchor(1, 2, 3);

package/src/symbol/collision_index.bench.ts

@@ -0,0 +1,116 @@
+import {bench, describe} from 'vitest';
+import Point from '@mapbox/point-geometry';
+import {CollisionIndex} from './collision_index.ts';
+import {EXTENT} from '../data/extent.ts';
+import {OverscaledTileID} from '../tile/tile_id.ts';
+import {MercatorTransform} from '../geo/projection/mercator_transform.ts';
+import {GlobeTransform} from '../geo/projection/globe_transform.ts';
+
+import type {mat4} from 'gl-matrix';
+import type {ITransform} from '../geo/transform_interface.ts';
+import type {UnwrappedTileID} from '../tile/tile_id.ts';
+import type {SingleCollisionBox} from '../data/bucket/symbol_bucket.ts';
+import type {OverlapMode} from '../style/style_layer/overlap_mode.ts';
+
+type TestSymbol = {
+    collisionBox: SingleCollisionBox;
+    overlapMode: OverlapMode;
+    textPixelRatio: number;
+    tileID: OverscaledTileID;
+    unwrappedTileID: UnwrappedTileID;
+    pitchWithMap: boolean;
+    rotateWithMap: boolean;
+    translation: [number, number];
+    shift?: Point;
+    simpleProjectionMatrix?: mat4;
+};
+
+// https://stackoverflow.com/a/47593316
+function splitmix32(a: number): () => number {
+    return function() {
+        a |= 0;
+        a = a + 0x9e3779b9 | 0;
+        let t = a ^ a >>> 16;
+        t = Math.imul(t, 0x21f0aaad);
+        t = t ^ t >>> 15;
+        t = Math.imul(t, 0x735a2d97);
+        return ((t = t ^ t >>> 15) >>> 0) / 4294967296;
+    };
+}
+
+const symbolCount = 20000;
+
+function createSymbols(transform: ITransform, calculatePosMatrix: (tileID: UnwrappedTileID) => mat4 | undefined): TestSymbol[] {
+    transform.resize(1024, 1024, true);
+
+    const tileID = new OverscaledTileID(0, 0, 0, 0, 0);
+    const unwrappedTileID = tileID.toUnwrapped();
+    const rng = splitmix32(0xdeadbeef);
+    const rndRange = (min: number, max: number) => rng() * (max - min) + min;
+    const symbols: TestSymbol[] = [];
+
+    for (let i = 0; i < symbolCount; i++) {
+        symbols.push({
+            collisionBox: {
+                anchorPointX: rndRange(4, EXTENT - 4),
+                anchorPointY: rndRange(4, EXTENT - 4),
+                x1: rndRange(-20, -2),
+                y1: rndRange(-20, -2),
+                x2: rndRange(2, 20),
+                y2: rndRange(2, 20)
+            },
+            overlapMode: 'never',
+            textPixelRatio: 1,
+            tileID,
+            unwrappedTileID,
+            pitchWithMap: rng() > 0.5,
+            rotateWithMap: rng() > 0.5,
+            translation: [
+                rndRange(-20, 20),
+                rndRange(-20, 20)
+            ],
+            shift: rng() > 0.5 ? new Point(rndRange(-20, 20), rndRange(-20, 20)) : undefined,
+            simpleProjectionMatrix: calculatePosMatrix(unwrappedTileID),
+        });
+    }
+
+    return symbols;
+}
+
+function placeAll(transform: ITransform, symbols: TestSymbol[]): void {
+    const collisionIndex = new CollisionIndex(transform);
+    collisionIndex.grid.hitTest = () => true;
+
+    for (const symbol of symbols) {
+        collisionIndex.placeCollisionBox(
+            symbol.collisionBox,
+            symbol.overlapMode,
+            symbol.textPixelRatio,
+            symbol.tileID,
+            symbol.unwrappedTileID,
+            symbol.pitchWithMap,
+            symbol.rotateWithMap,
+            symbol.translation,
+            null,
+            null,
+            symbol.shift,
+            symbol.simpleProjectionMatrix,
+        );
+    }
+}
+
+const mercatorTransform = new MercatorTransform({minZoom: 0, maxZoom: 22, minPitch: 0, maxPitch: 60, renderWorldCopies: true});
+const mercatorSymbols = createSymbols(mercatorTransform, (tileID) => mercatorTransform.calculatePosMatrix(tileID, false));
+
+const globeTransform = new GlobeTransform();
+const globeSymbols = createSymbols(globeTransform, () => undefined);
+
+describe('placeCollisionBox', () => {
+    bench('mercator', () => {
+        placeAll(mercatorTransform, mercatorSymbols);
+    });
+
+    bench('globe', () => {
+        placeAll(globeTransform, globeSymbols);
+    });
+});

package/src/symbol/cross_tile_symbol_index.bench.ts

@@ -0,0 +1,49 @@
+import {bench} from 'vitest';
+import {CrossTileSymbolIndex} from './cross_tile_symbol_index.ts';
+import {OverscaledTileID} from '../tile/tile_id.ts';
+
+import type {Tile} from '../tile/tile.ts';
+import type {StyleLayer} from '../style/style_layer.ts';
+
+type TestSymbolInstance = {
+    anchorX: number;
+    anchorY: number;
+    key: string;
+    crossTileID: number;
+};
+
+const styleLayer = {id: 'test'} as StyleLayer;
+const symbolCount = 3000;
+
+function createTile(tileID: OverscaledTileID, symbolInstances: TestSymbolInstance[]): Tile {
+    const bucket = {
+        symbolInstances: {
+            get(i: number) { return symbolInstances[i]; },
+            length: symbolInstances.length
+        },
+        layerIds: ['test']
+    };
+    return {
+        tileID,
+        getBucket: () => bucket,
+        latestFeatureIndex: {}
+    } as unknown as Tile;
+}
+
+function createInstances(): TestSymbolInstance[] {
+    return Array.from({length: symbolCount}, (_, i) => ({
+        anchorX: 0,
+        anchorY: 0,
+        key: '',
+        crossTileID: i + 1
+    }));
+}
+
+const mainTile = createTile(new OverscaledTileID(6, 0, 6, 8, 8), createInstances());
+const childTile = createTile(new OverscaledTileID(7, 0, 7, 16, 16), createInstances());
+
+bench('CrossTileSymbolIndex.addLayer', () => {
+    const index = new CrossTileSymbolIndex();
+    index.addLayer(styleLayer, [mainTile], 0);
+    index.addLayer(styleLayer, [childTile], 0);
+});

package/src/symbol/cross_tile_symbol_index.test.ts

@@ -236,6 +236,37 @@ describe('CrossTileSymbolIndex.addLayer', () => {
         expect(childInstances[0].crossTileID).toBe(1);
 
     });
+
+    test('claims the lowest-index match among coincident symbols', () => {
+        const index = new CrossTileSymbolIndex();
+
+        const mainID = new OverscaledTileID(6, 0, 6, 8, 8);
+        const childID = new OverscaledTileID(7, 0, 7, 16, 16);
+
+        // more instances than KDBUSH_THRESHHOLD to exercise the KDBush-indexed path
+        const count = KDBUSH_THRESHHOLD + 2;
+        const mainInstances: any[] = [];
+        const childInstances: any[] = [];
+        for (let i = 0; i < count; i++) {
+            // all symbols are coincident and share the same key
+            mainInstances.push(makeSymbolInstance(1000, 1000, 'Dense'));
+            childInstances.push(makeSymbolInstance(2000, 2000, 'Dense'));
+        }
+
+        const mainTile = makeTile(mainID, mainInstances);
+        const childTile = makeTile(childID, childInstances);
+
+        index.addLayer(styleLayer, [mainTile], 0);
+        index.addLayer(styleLayer, [mainTile, childTile], 0);
+
+        // Each child symbol should claim the lowest-index unclaimed parent
+        // symbol, so parents are claimed in symbol-instance order. (A
+        // lexicographic ordering of the candidate indexes would instead claim
+        // parent 10 for child 2 once 0 and 1 are taken, because '10' < '2'.)
+        for (let i = 0; i < 12; i++) {
+            expect(childInstances[i].crossTileID).toBe(mainInstances[i].crossTileID);
+        }
+    });
 });
 
 test('CrossTileSymbolIndex.pruneUnusedLayers', () => {