maplibre-gl 6.2.0 → 6.4.0

package/src/source/raster_dem_tile_source.ts

@@ -55,11 +55,10 @@ export class RasterDEMTileSource extends RasterTileSource implements Source {
 
     override async loadTile(tile: Tile): Promise<void> {
         const url = tile.tileID.canonical.url(this.tiles, this.map.getPixelRatio(), this.scheme);
-        const request = await this.map._requestManager.transformRequest(url, ResourceType.Tile);
         tile.neighboringTiles = this._getNeighboringTiles(tile.tileID);
         tile.abortController = new AbortController();
         try {
-            const response = await ImageRequest.getImage(request, tile.abortController, this.map._refreshExpiredTiles);
+            const response = await ImageRequest.transformAndGetImage(this.map._requestManager, url, ResourceType.Tile, tile.abortController, this.map._refreshExpiredTiles, {colorSpaceConversion: 'none'});
             delete tile.abortController;
             if (tile.aborted) {
                 tile.state = 'unloaded';

package/src/source/raster_dem_tile_worker_source.test.ts

@@ -14,7 +14,7 @@ describe('loadTile', () => {
             dim: 256
         } as any as WorkerDEMTileParameters);
         expect(Object.keys(source.loaded)).toEqual(['0']);
-        expect(data instanceof DEMData).toBeTruthy();
+        expect(data).toBeInstanceOf(DEMData);
     });
 });
 

package/src/source/raster_tile_source.test.ts

@@ -445,36 +445,18 @@ describe('RasterTileSource', () => {
         expect(expiryDataSpy).toHaveBeenCalledTimes(1);
     });
 
-    test('passes a live AbortController to ImageRequest when the tile is aborted during an async transformRequest', async () => {
-        let transformStarted: () => void;
-        const transformCalled = new Promise<void>((resolve) => {
-            transformStarted = resolve;
-        });
+    test('does not request a tile that was aborted while its request was being transformed', async () => {
         let releaseTransform: (params: {url: string}) => void;
         const source = createSource({
             tiles: ['http://example.com/{z}/{x}/{y}.png']
         }, (url, type) => {
             if (type !== 'Tile') return {url};
-            transformStarted();
             return new Promise<{url: string}>((resolve) => {
                 releaseTransform = resolve;
             });
         });
         source.tiles = ['http://example.com/{z}/{x}/{y}.png'];
 
-        const image = {width: 256, height: 256} as ImageBitmap;
-        let requestController: AbortController;
-        let tileControllerAtRequestTime: AbortController;
-        const getImageSpy = vi.spyOn(ImageRequest, 'getImage').mockImplementation(async (_request, abortController) => {
-            requestController = abortController;
-            tileControllerAtRequestTime = tile.abortController;
-            return {data: image};
-        });
-        source.map.painter = {
-            context: {gl: {}},
-            getTileTexture: () => ({update: vi.fn()})
-        } as any;
-
         const tile = {
             tileID: new OverscaledTileID(10, 0, 10, 5, 5),
             state: 'loading',
@@ -482,16 +464,13 @@ describe('RasterTileSource', () => {
         } as any as Tile;
 
         const loadPromise = source.loadTile(tile);
-        await transformCalled; // loadTile is suspended in the transform
-        await source.abortTile(tile); // the abort lands during that suspension
+        tile.aborted = true;
+        await source.abortTile(tile);
         releaseTransform({url: 'http://example.com/10/5/5.png'});
         await expect(loadPromise).resolves.toBeUndefined();
 
-        expect(getImageSpy).toHaveBeenCalledTimes(1);
-        // The request must carry the tile's own live controller, so an abort
-        // arriving while it is in flight reaches exactly this request.
-        expect(requestController).toBeInstanceOf(AbortController);
-        expect(requestController).toBe(tileControllerAtRequestTime);
+        expect(server.requests).toHaveLength(0);
+        expect(tile.state).toBe('unloaded');
     });
 
     test('does not throw when tile is aborted', async () => {

package/src/source/raster_tile_source.ts

@@ -206,11 +206,12 @@ export class RasterTileSource extends Evented<SourceEventType> implements Source
         const url = tile.tileID.canonical.url(this.tiles, this.map.getPixelRatio(), this.scheme);
         const premultiply = this._premultiplyAlpha;
         const imageBitmapOptions = premultiply ? undefined : {premultiplyAlpha: 'none'} as const;
-        const request = await this.map._requestManager.transformRequest(url, ResourceType.Tile);
         tile.abortController = new AbortController();
         try {
-            const response = await ImageRequest.getImage(
-                request,
+            const response = await ImageRequest.transformAndGetImage(
+                this.map._requestManager,
+                url,
+                ResourceType.Tile,
                 tile.abortController,
                 this.map._refreshExpiredTiles,
                 imageBitmapOptions

package/src/source/vector_tile_worker_source.test.ts

@@ -170,6 +170,100 @@ describe('vector tile worker source', () => {
         expect(res.rawTileData).toStrictEqual(rawTileData);
     });
 
+    test('VectorTileWorkerSource.reloadTile includes rawTileData in response if loadTile was aborted', async () => {
+        const rawTileData = new ArrayBuffer(0);
+
+        const layerIndex = new StyleLayerIndex([{
+            id: 'test',
+            source: 'source',
+            'source-layer': 'test',
+            type: 'symbol',
+            layout: {
+                'icon-image': 'hello',
+                'text-font': ['StandardFont-Bold'],
+                'text-field': '{name}'
+            }
+        }]);
+
+        let sendAsyncShouldAbort = false;
+        const actor = {
+            sendAsync: (message: {type: string; data: unknown}, abortController: AbortController) => {
+                if (sendAsyncShouldAbort) {
+                    return new Promise((_resolve, reject) => {
+                        reject('aborted by test');
+                    });
+                }
+
+                return new Promise((resolve, reject) => {
+                    const res = setTimeout(() => {
+                        const response = message.type === 'getImages' ?
+                            {'hello': {width: 1, height: 1, data: new Uint8Array([0])}} :
+                            {'StandardFont-Bold': {width: 1, height: 1, data: new Uint8Array([0])}};
+                        resolve(response);
+                    }, 100);
+                    abortController.signal.addEventListener('abort', () => {
+                        clearTimeout(res);
+                        reject('aborted by abortController');
+                    });
+                });
+            }
+        };
+
+        const source = new VectorTileWorkerSource(actor, layerIndex, ['hello']);
+        source.loadVectorTile = (_params, _rawData) => {
+            return {
+                vectorTile: {
+                    layers: {
+                        test: {
+                            version: 2,
+                            name: 'test',
+                            extent: 8192,
+                            length: 1,
+                            feature: (featureIndex: number) => ({
+                                extent: 8192,
+                                type: 1,
+                                id: featureIndex,
+                                properties: {
+                                    name: 'test'
+                                },
+                                loadGeometry () {
+                                    return [[new Point(0, 0)]];
+                                }
+                            })
+                        }
+                    }
+                },
+                rawData: rawTileData
+            };
+        };
+
+        server.respondWith(request => {
+            request.respond(200, {'Content-Type': 'application/pbf'}, rawTileData as any);
+        });
+
+        sendAsyncShouldAbort = true;
+        const loadTilePromise = source.loadTile({
+            source: 'source',
+            uid: 0,
+            tileID: {overscaledZ: 0, wrap: 0, canonical: {x: 0, y: 0, z: 0, w: 0}},
+            request: {url: 'http://localhost:2900/faketile.pbf'},
+            subdivisionGranularity: SubdivisionGranularitySetting.noSubdivision,
+        } as any as WorkerTileParameters);
+        server.respond();
+        await expect(loadTilePromise).rejects.toThrow(/aborted/);
+
+        sendAsyncShouldAbort = false;
+        const res = await source.reloadTile({
+            source: 'source',
+            uid: 0,
+            tileID: {overscaledZ: 0, wrap: 0, canonical: {x: 0, y: 0, z: 0, w: 0}},
+            subdivisionGranularity: SubdivisionGranularitySetting.noSubdivision,
+        } as any as WorkerTileParameters) as WorkerTileWithData;
+        expect(res).toBeDefined();
+        expect(res.rawTileData).toBeDefined();
+        expect(res.rawTileData).toStrictEqual(rawTileData);
+    });
+
     test('VectorTileWorkerSource.loadTile reparses tile if reloadTile is called during reparsing', async () => {
         const rawTileData = new ArrayBuffer(0);
         const loadVectorData = (_params, _rawData) => {
@@ -193,7 +287,6 @@ describe('vector tile worker source', () => {
         const parseWorkerTileMock = vi
             .spyOn(WorkerTile.prototype, 'parse')
             .mockImplementation(function(this: WorkerTile, _data, _layerIndex, _availableImages, _actor) {
-                this.status = 'parsing';
                 return new Promise((resolve) => {
                     setTimeout(() => resolve({} as WorkerTileResult), 20);
                 });
@@ -248,7 +341,6 @@ describe('vector tile worker source', () => {
         const parseWorkerTileMock = vi
             .spyOn(WorkerTile.prototype, 'parse')
             .mockImplementation(function(this: WorkerTile, _data, _layerIndex, _availableImages, _actor) {
-                this.status = 'parsing';
                 return new Promise((resolve) => {
                     setTimeout(() => resolve({} as WorkerTileResult), 20);
                 });

package/src/source/vector_tile_worker_source.ts

@@ -3,7 +3,7 @@ import {VectorTile} from '@mapbox/vector-tile';
 import {fromVectorTileJs, type VectorTileLayerLike, type VectorTileLike} from '@maplibre/vt-pbf';
 import {type ExpiryData, getArrayBuffer} from '../util/ajax.ts';
 import {WorkerTile} from './worker_tile.ts';
-import {WorkerTileState, type ParsingState} from './worker_tile_state.ts';
+import {WorkerTileState} from './worker_tile_state.ts';
 import {BoundedLRUCache} from '../tile/tile_cache.ts';
 import {ensureError, extend} from '../util/util.ts';
 import {RequestPerformance} from '../util/request_performance.ts';
@@ -106,17 +106,12 @@ export class VectorTileWorkerSource implements WorkerSource {
 
             workerTile.vectorTile = vectorTile;
             this.tileState.markLoaded(uid, workerTile);
+            const parsingState = {rawData, cacheControl, resourceTiming};
+            this.tileState.setParsing(uid, parsingState);
 
-            const parseState = {rawData, cacheControl, resourceTiming};  // Keep data so reloadTile can access if parse is canceled.
-            this.tileState.setParsing(uid, parseState);
-            try {
-                return await this._parseWorkerTile(workerTile, params, parseState);
-            } finally {
-                this.tileState.removeParsing(uid);
-            }
+            return await this._parseWorkerTile(workerTile, params);
         } catch (err) {
             this.tileState.finishLoading(uid);
-            workerTile.status = 'done';
             this.tileState.markLoaded(uid, workerTile);
             throw err;
         }
@@ -128,16 +123,23 @@ export class VectorTileWorkerSource implements WorkerSource {
         return extend({etagUnmodified: true as const}, cacheControl, resourceTiming);
     }
 
-    async _parseWorkerTile(workerTile: WorkerTile, params: WorkerTileParameters, parseState?: ParsingState): Promise<WorkerTileResult> {
+    async _parseWorkerTile(workerTile: WorkerTile, params: WorkerTileParameters): Promise<WorkerTileResult> {
+        const parseState = this.tileState.getParsing(workerTile.uid);
+
         let result = await workerTile.parse(workerTile.vectorTile, this.layerIndex, this.availableImages, this.actor, params.subdivisionGranularity);
 
+        // We need to pass rawTileData back to the main thread so that it can be stored in the Tile and FeatureIndex.
+        // After the main thread has successfully received and stored rawTileData,
+        // we no longer need to store it in the worker or transfer additional copies of it.
         if (parseState) {
             const {rawData, cacheControl, resourceTiming} = parseState;
             // Overzoomed tiles are always re-encoded to MVT protobuf by _getOverzoomTile
             const encoding = params.overzoomParameters ? 'mvt' : params.encoding;
-            // Transferring a copy of rawTileData because the worker needs to retain its copy.
+            // Return a copy of rawData to the main thread to avoid clearing the worker's buffer
             result = extend({rawTileData: rawData.slice(0), encoding}, result, cacheControl, resourceTiming);
+            this.tileState.removeParsing(workerTile.uid);
         }
+        // else: this seems like a missing case where cache control is lost? see #3309
 
         return result;
     }
@@ -209,27 +211,16 @@ export class VectorTileWorkerSource implements WorkerSource {
      */
     async reloadTile(params: WorkerTileParameters): Promise<WorkerTileResult> {
         const uid = params.uid;
-
         const workerTile = this.tileState.getLoaded(uid);
         if (!workerTile) throw new Error('Should not be trying to reload a tile that was never loaded or has been removed');
 
-        workerTile.showCollisionBoxes = params.showCollisionBoxes;
-
-        if (workerTile.status === 'parsing') {
-            // if we are cancelling the original parse, make sure to pass the rawTileData from the original parse
-            const parseState = this.tileState.getParsing(uid);
-            try {
-                return await this._parseWorkerTile(workerTile, params, parseState);
-            } finally {
-                this.tileState.removeParsing(uid);
-            }
+        // If there was no vector tile data on the initial load, don't try to reparse the tile.
+        if (!workerTile.vectorTile) {
+            return;
         }
 
-        // If there was no vector tile data on the initial load, don't try and reparse the tile.
-        // this seems like a missing case where cache control is lost? see #3309
-        if (workerTile.status === 'done' && workerTile.vectorTile) {
-            return await this._parseWorkerTile(workerTile, params);
-        }
+        workerTile.showCollisionBoxes = params.showCollisionBoxes;
+        return await this._parseWorkerTile(workerTile, params);
     }
 
     /**

package/src/source/video_source.test.ts

@@ -1,14 +1,13 @@
-import {describe, test, expect, vi} from 'vitest';
-import {VideoSource} from './video_source.ts';
-import {extend} from '../util/util.ts';
+import {describe, expect, test, vi} from 'vitest';
 import {getMockDispatcher, waitForEvent} from '../util/test/util.ts';
-
-import type {Coordinates} from './image_source.ts';
+import {extend} from '../util/util.ts';
+import {VideoSource} from './video_source.ts';
+import {MercatorTransform} from '../geo/projection/mercator_transform.ts';
 import {Tile} from '../tile/tile.ts';
 import {OverscaledTileID} from '../tile/tile_id.ts';
 import {Evented} from '../util/evented.ts';
-import {type IReadonlyTransform} from '../geo/transform_interface.ts';
-import {MercatorTransform} from '../geo/projection/mercator_transform.ts';
+import type {IReadonlyTransform} from '../geo/transform_interface.ts';
+import type {Coordinates} from './image_source.ts';
 
 class StubMap extends Evented {
     transform: IReadonlyTransform;
@@ -117,7 +116,7 @@ describe('VideoSource', () => {
         expect(tile.state).toBe('loaded');
     });
 
-    test('onRemove removes playing listener and pauses video', () => {
+    test('onRemove removes playing listener, pauses video and deletes the texture', () => {
         const video = window.document.createElement('video');
         const removeListenerSpy = vi.spyOn(video, 'removeEventListener');
         const pauseSpy = vi.spyOn(video, 'pause').mockImplementation(() => {});
@@ -129,9 +128,14 @@ describe('VideoSource', () => {
         });
         source.video = video;
 
+        const texture = {destroy: vi.fn()} as any;
+        source.texture = texture;
+
         source.onRemove();
 
         expect(removeListenerSpy).toHaveBeenCalledWith('playing', expect.any(Function));
         expect(pauseSpy).toHaveBeenCalled();
+        expect(texture.destroy).toHaveBeenCalledTimes(1);
+        expect(source.texture).toBeNull();
     });
 });

package/src/source/worker_tile.bench.ts

@@ -0,0 +1,10 @@
+import {bench} from 'vitest';
+import {fixtureTiles, parseTile} from '../../test/bench/lib/parse_tile.ts';
+
+await Promise.all(fixtureTiles.map(tile => parseTile(tile, false)));
+
+bench('WorkerTile.parse', async () => {
+    for (const tile of fixtureTiles) {
+        await parseTile(tile, false);
+    }
+});

package/src/source/worker_tile.ts

@@ -37,7 +37,6 @@ export class WorkerTile {
     collectResourceTiming: boolean;
     returnDependencies: boolean;
 
-    status: 'parsing' | 'done';
     data: VectorTileLike;
     collisionBoxArray: CollisionBoxArray;
 
@@ -61,7 +60,6 @@ export class WorkerTile {
     }
 
     async parse(data: VectorTileLike, layerIndex: StyleLayerIndex, availableImages: string[], actor: IActor, subdivisionGranularity: SubdivisionGranularitySetting): Promise<WorkerTileResult> {
-        this.status = 'parsing';
         this.data = data;
 
         this.collisionBoxArray = new CollisionBoxArray();
@@ -192,7 +190,6 @@ export class WorkerTile {
             }
         }
 
-        this.status = 'done';
         return {
             buckets: Object.values(buckets).filter(b => !b.isEmpty()),
             featureIndex,

package/src/style/create_style_layer.bench.ts

@@ -0,0 +1,15 @@
+import {bench} from 'vitest';
+import {derefLayers} from '@maplibre/maplibre-gl-style-spec';
+import {createStyleLayer} from './create_style_layer.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;
+const layers = derefLayers(style.layers);
+
+bench('createStyleLayer', () => {
+    for (const layer of layers) {
+        createStyleLayer(layer, {});
+    }
+});

package/src/style/properties.bench.ts

@@ -0,0 +1,81 @@
+import {bench, describe} from 'vitest';
+import {latest as spec, convertFunction, isFunction, createFunction, createPropertyExpression} from '@maplibre/maplibre-gl-style-spec';
+import brightV9 from '../../test/integration/assets/styles/bright-v9.json' with {type: 'json'};
+
+import type {StyleSpecification, StylePropertyExpression, StylePropertySpecification} from '@maplibre/maplibre-gl-style-spec';
+
+type Sample = {
+    propertySpec: StylePropertySpecification;
+    rawValue: unknown;
+    rawExpression: unknown;
+    compiledFunction: StylePropertyExpression;
+    compiledExpression: StylePropertyExpression;
+};
+
+function sample(rawValue: unknown, propertySpec: StylePropertySpecification): Sample {
+    const rawExpression = convertFunction(rawValue, propertySpec);
+    const compiledFunction = createFunction(rawValue, propertySpec) as StylePropertyExpression;
+    const compiledExpression = createPropertyExpression(rawExpression, 'expression', propertySpec);
+    if (compiledExpression.result === 'error') {
+        throw new Error(compiledExpression.value.map(err => `${err.key}: ${err.message}`).join(', '));
+    }
+    return {
+        propertySpec,
+        rawValue,
+        rawExpression,
+        compiledFunction,
+        compiledExpression: compiledExpression.value
+    };
+}
+
+function collect(style: StyleSpecification): Sample[] {
+    const samples: Sample[] = [];
+
+    for (const layer of style.layers) {
+        if (!layer.type) {
+            continue;
+        }
+
+        for (const key in layer.paint) {
+            if (isFunction(layer.paint[key])) {
+                samples.push(sample(layer.paint[key], spec[`paint_${layer.type}`][key]));
+            }
+        }
+
+        for (const key in layer.layout) {
+            if (isFunction(layer.layout[key])) {
+                samples.push(sample(layer.layout[key], spec[`layout_${layer.type}`][key]));
+            }
+        }
+    }
+
+    return samples;
+}
+
+const samples = collect(brightV9 as unknown as StyleSpecification);
+
+describe('style property functions', () => {
+    bench('createFunction', () => {
+        for (const {rawValue, propertySpec} of samples) {
+            createFunction(rawValue, propertySpec);
+        }
+    });
+
+    bench('evaluate function', () => {
+        for (const {compiledFunction} of samples) {
+            compiledFunction.evaluate({zoom: 0});
+        }
+    });
+
+    bench('createPropertyExpression', () => {
+        for (const {rawExpression, propertySpec} of samples) {
+            createPropertyExpression(rawExpression, 'expression', propertySpec);
+        }
+    });
+
+    bench('evaluate expression', () => {
+        for (const {compiledExpression} of samples) {
+            compiledExpression.evaluate({zoom: 0});
+        }
+    });
+});

package/src/style/style.test.ts

@@ -3,13 +3,15 @@ import {Style} from './style.ts';
 import {TileManager} from '../tile/tile_manager.ts';
 import {StyleLayer} from './style_layer.ts';
 import {extend} from '../util/util.ts';
-import {Event} from '../util/evented.ts';
+import {ErrorEvent, Event} from '../util/evented.ts';
 import {type AJAXError} from '../util/ajax.ts';
+import {MapSourceDataEvent} from '../ui/events.ts';
 import {RGBAImage} from '../util/image.ts';
 import {rtlMainThreadPluginFactory} from '../source/rtl_text_plugin_main_thread.ts';
 import {browser} from '../util/browser.ts';
 import {OverscaledTileID} from '../tile/tile_id.ts';
 import {fakeServer, type FakeServer} from 'nise';
+import {ImageRequest} from '../util/image_request.ts';
 
 import {type EvaluationParameters} from './evaluation_parameters.ts';
 import {Color, type Feature, type LayerSpecification, type GeoJSONSourceSpecification, type FilterSpecification, type SourceSpecification, type StyleSpecification, type SymbolLayerSpecification, type SkySpecification, type CameraFunctionSpecification} from '@maplibre/maplibre-gl-style-spec';
@@ -72,6 +74,7 @@ let mockConsoleError: MockInstance;
 beforeEach(() => {
     global.fetch = null;
     server = fakeServer.create();
+    ImageRequest.resetRequestQueue();
     mockConsoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
 });
 
@@ -374,7 +377,7 @@ describe('Style.loadJSON', () => {
         }));
 
         await style.once('style.load');
-        expect(style.tileManagers['mapLibre'] instanceof TileManager).toBeTruthy();
+        expect(style.tileManagers['mapLibre']).toBeInstanceOf(TileManager);
     });
 
     test('creates layers', async () => {
@@ -396,7 +399,7 @@ describe('Style.loadJSON', () => {
         });
 
         await style.once('style.load');
-        expect(style.getLayer('fill') instanceof StyleLayer).toBeTruthy();
+        expect(style.getLayer('fill')).toBeInstanceOf(StyleLayer);
     });
 
     test('transforms sprite json and image URLs before request', async () => {
@@ -460,7 +463,7 @@ describe('Style.loadJSON', () => {
         const errorPromise = style.once('error');
 
         await style.once('style.load');
-        style._layers.background.fire(new Event('error', {mapLibre: true}));
+        style._layers.background.fire(new ErrorEvent(new Error('test'), {mapLibre: true}));
 
         const e = await errorPromise;
         expect((e as any).layer).toEqual({id: 'background'});
@@ -1347,8 +1350,8 @@ describe('Style.addSource', () => {
         });
 
         style.addSource('source-id', source); // fires data twice
-        style.tileManagers['source-id'].fire(new Event('error'));
-        style.tileManagers['source-id'].fire(new Event('data'));
+        style.tileManagers['source-id'].fire(new ErrorEvent(new Error('test')));
+        style.tileManagers['source-id'].fire(new MapSourceDataEvent('data'));
 
         await expect(Promise.all(promises)).resolves.toBeDefined();
     });
@@ -1446,8 +1449,8 @@ describe('Style.removeSource', () => {
 
         style.on('data', () => expect(false).toBeTruthy());
         style.on('error', () => expect(false).toBeTruthy());
-        tileManager.fire(new Event('data'));
-        tileManager.fire(new Event('error'));
+        tileManager.fire(new MapSourceDataEvent('data'));
+        tileManager.fire(new ErrorEvent(new Error('test')));
     });
 });
 
@@ -1704,6 +1707,68 @@ describe('Style.setSprite', () => {
     });
 });
 
+describe('Style._loadSprite', () => {
+    const FIRST_SPRITE_URL = 'http://example.com/sprite1';
+    const SECOND_SPRITE_URL = 'http://example.com/sprite2';
+
+    const spriteJSON = (...imageIds: string[]) => JSON.stringify(
+        Object.fromEntries(imageIds.map(id => [id, {width: 1, height: 1, x: 0, y: 0, pixelRatio: 1}]))
+    );
+
+    /** Loads a sprite through `setSprite` and resolves once it has been applied to the image manager */
+    function loadSprite(style: Style, url: string): Promise<void> {
+        return new Promise((resolve, reject) => {
+            style.setSprite(url, {}, (err) => err ? reject(err) : resolve());
+            sleep(0).then(() => server.respond());
+        });
+    }
+
+    async function createLoadedStyle(): Promise<Style> {
+        const style = new Style(getStubMap());
+        style.loadJSON(createStyleJSON());
+        await style.once('style.load');
+        return style;
+    }
+
+    beforeEach(() => {
+        vi.spyOn(browser, 'getImageData');
+        server.respondWith('GET', /sprite\d\.png$/, new ArrayBuffer(8) as any);
+        server.respondWith('GET', `${FIRST_SPRITE_URL}.json`, spriteJSON('sharedImage', 'firstSpriteOnlyImage'));
+        server.respondWith('GET', `${SECOND_SPRITE_URL}.json`, spriteJSON('sharedImage', 'secondSpriteOnlyImage'));
+    });
+
+    test('removes the images of the previous sprite that are absent from the new one', async () => {
+        const style = await createLoadedStyle();
+
+        await loadSprite(style, FIRST_SPRITE_URL);
+        expect(style.imageManager.listImages().sort()).toEqual(['firstSpriteOnlyImage', 'sharedImage']);
+
+        await loadSprite(style, SECOND_SPRITE_URL);
+        expect(style.imageManager.listImages().sort()).toEqual(['secondSpriteOnlyImage', 'sharedImage']);
+    });
+
+    test('leaves no image behind when the sprite is unset after having been replaced', async () => {
+        const style = await createLoadedStyle();
+        await loadSprite(style, FIRST_SPRITE_URL);
+        await loadSprite(style, SECOND_SPRITE_URL);
+
+        style.setSprite(undefined);
+
+        expect(style.imageManager.listImages()).toEqual([]);
+    });
+
+    test('only marks the images shared with the previous sprite as updated, so that returning to a sprite does not accumulate per-frame patching work', async () => {
+        const style = await createLoadedStyle();
+        await loadSprite(style, FIRST_SPRITE_URL);
+        const updateVersionAfterFirstLoad = style.imageManager.updateVersion;
+
+        await loadSprite(style, SECOND_SPRITE_URL);
+        await loadSprite(style, FIRST_SPRITE_URL);
+
+        expect(style.imageManager.updateVersion - updateVersionAfterFirstLoad).toBe(2);
+    });
+});
+
 describe('Style.setGeoJSONSourceData', () => {
     const geoJSON = {type: 'FeatureCollection', features: []} as GeoJSON.GeoJSON;
 
@@ -2297,7 +2362,7 @@ describe('Style.addLayer', () => {
             type: 'background'
         });
 
-        style._layers.background.fire(new Event('error', {mapLibre: true}));
+        style._layers.background.fire(new ErrorEvent(new Error('test'), {mapLibre: true}));
 
         const e = await errorPromise;
         expect((e as any).layer).toEqual({id: 'background'});
@@ -2614,7 +2679,7 @@ describe('Style.removeLayer', () => {
         // Bind a listener to prevent fallback Evented error reporting.
         layer.on('error', () => {});
 
-        layer.fire(new Event('error', {mapLibre: true}));
+        layer.fire(new ErrorEvent(new Error('test'), {mapLibre: true}));
 
         expect(styleErrorListener).not.toHaveBeenCalled();
     });