@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/maplibre/renderer.js

@@ -0,0 +1,889 @@
+import { deepEqual } from '../core/equal.js';
+import { DemSampler } from '../render/terrarium.js';
+import { fromLngLat, spatial, toFeature, toLngLat } from '../spatial/index.js';
+import { isLocalUrl, styleUrls } from '../render/offline.js';
+import { ICON_PIXELS, shapeImage } from './icons.js';
+import { DeckHost, hostedByDeck, loadDeck, shimTransformForDeck } from './deck-host.js';
+import { CONTOUR_LABELS, CONTOUR_LINES, CONTOUR_SOURCE, contourLayers, isPmtiles, PREFIX, DEFAULT_THEME, HILLSHADE_LAYER, HILLSHADE_SOURCE, TERRAIN_SOURCE, demSourceFor, hillshadeLayer, LABEL_POINT_PROP, LAYER_ID_PROP, OBJECT_ID_PROP, basemapStyle, needsLabelPoints, withLabelFont, imagesFor, sourceId, sourceSpecFor, styleLayersFor } from './style.js';
+/** The label point of an area shares its source; its feature id is the shape's id plus this offset. */
+const LABEL_ID_OFFSET = 2 ** 30;
+const splitKey = (key) => {
+    const i = key.indexOf(':'); // layer ids cannot contain ':'; object ids may
+    return [key.slice(0, i), key.slice(i + 1)];
+};
+/** MapLibre reports ErrorLike ({ message }) — not always a real Error. */
+const toError = (e, fallback) => (e instanceof Error ? e : new Error(e?.message ?? fallback));
+const normalizeBearing = (b) => ((b % 360) + 360) % 360;
+/** MapLibre modules that already speak pmtiles:// (the protocol is global to the module). */
+const pmtilesReady = new WeakSet();
+/** An image's four corners (top-left, top-right, bottom-right, bottom-left) as [lng, lat]: a four-corner polygon as given, else the bounds. */
+function imageCorners(g) {
+    if (g.type === 'Polygon') {
+        const ring = g.coordinates[0] ?? [];
+        const pts = ring.length > 1 && ring[0].latitude === ring[ring.length - 1].latitude && ring[0].longitude === ring[ring.length - 1].longitude ? ring.slice(0, -1) : ring;
+        if (pts.length === 4)
+            return pts.map((p) => toLngLat(p));
+    }
+    if (g.type === 'Point' || g.type === 'LineString' || g.type === 'MultiPoint')
+        return null;
+    const b = spatial.bounds(g);
+    return [[b.west, b.north], [b.east, b.north], [b.east, b.south], [b.west, b.south]];
+}
+const clampLon = (v) => Math.max(-180, Math.min(180, v));
+const clampLat = (v) => Math.max(-85.051129, Math.min(85.051129, v));
+export class MapLibreRenderer {
+    options;
+    /**
+     * Globe, terrain and ground heights (3B); heights and models through deck.gl, extrusions natively (3C).
+     * Known limit: with MapLibre v6 and deck.gl 9.4, deck.gl layers do not draw in the globe projection — so in globe
+     * mode heights and models are not claimed (the runtime reports the gap) and those layers are drawn flat by
+     * MapLibre instead of disappearing. A full 3D globe is the Cesium renderer's job (phase 3D).
+     */
+    get capabilities() {
+        const lifted = this.projection !== 'globe';
+        return { globe: true, terrain: true, elevation: true, extrusion: true, altitude: lifted, models: lifted, volumes: lifted };
+    }
+    /** The layers last given by the scene (before any globe-mode flattening). */
+    sceneLayers = [];
+    /** deck.gl host for layers at a height and models (created with the map, loads deck.gl on first use). */
+    deckHost = null;
+    fontName;
+    groundRefresh = null;
+    projection = 'mercator';
+    terrain = null;
+    dem = null;
+    map = null;
+    lib = null;
+    offline = null;
+    /** Image layers: per layer, per object, the image source drawn (doc 28 G12). */
+    images = new Map();
+    /** Contour tiles from the terrain's DEM (doc 28 G11), created on first use. */
+    contourDem = null;
+    theme;
+    layers = new Map();
+    features = new Map();
+    mapHandlers = [];
+    hoverKey = null;
+    hasFont = false;
+    warnedNoFont = false;
+    /** Bumped by destroy(): an initialize() or setBasemap() that started before it is stale. */
+    gen = 0;
+    /** Rejects the style load being waited for (destroy() during initialize or a basemap swap). */
+    cancelWait = null;
+    /** The one-off check that engine data really reached MapLibre's worker (see workerCheckMs). */
+    workerCheck = null;
+    workerChecked = false;
+    listeners = {
+        viewport: new Set(),
+        pick: new Set(),
+        click: new Set(),
+        hover: new Set(),
+        error: new Set(),
+        move: new Set(),
+    };
+    constructor(options = {}) {
+        this.options = options;
+        this.theme = { ...DEFAULT_THEME, ...options.theme };
+    }
+    async initialize(container, options) {
+        const gen = this.gen;
+        const lib = this.options.maplibre ?? (await import('maplibre-gl'));
+        if (gen !== this.gen)
+            return;
+        this.lib = lib;
+        this.offline = options.offline?.allowedOrigins ?? null;
+        const archives = [options.basemap.tileUrl, options.basemap.styleUrl, options.basemap.rasterFallback, options.terrain?.tileUrl];
+        if (archives.some(isPmtiles)) {
+            await this.ensurePmtiles(archives);
+            if (gen !== this.gen)
+                return;
+        }
+        this.hasFont = options.basemap.font !== undefined;
+        this.fontName = options.basemap.font?.name;
+        this.warnedNoFont = false;
+        this.hoverKey = null;
+        this.projection = options.projection ?? 'mercator';
+        this.terrain = options.terrain ?? null;
+        if (this.options.workerUrl)
+            lib.setWorkerUrl?.(this.options.workerUrl);
+        const v = options.viewport;
+        const style = await this.resolveStyle(options.basemap);
+        if (gen !== this.gen)
+            return;
+        const map = new lib.Map({
+            // A style declares its sources' credits (often required, e.g. OpenStreetMap), so it always gets the control.
+            attributionControl: options.basemap.attribution || options.basemap.kind === 'style' ? { compact: true } : false,
+            ...this.options.mapOptions,
+            container,
+            style,
+            center: toLngLat(v.center),
+            zoom: v.zoom,
+            bearing: v.bearing ?? 0,
+            pitch: v.pitch ?? 0,
+            // A tilted 3D view (terrain, objects in the air) needs more than MapLibre's default 60°.
+            maxPitch: 85,
+        });
+        this.map = map;
+        await this.waitFor(map, 'load');
+        if (gen !== this.gen)
+            return;
+        this.applyEnvironment();
+        this.deckHost = new DeckHost({
+            addControl: (o) => {
+                shimTransformForDeck(map);
+                map.addControl(o);
+            },
+            removeControl: (o) => map.removeControl(o),
+            theme: this.theme,
+            font: () => this.fontName,
+            terrainExaggeration: () => (this.terrain ? (this.terrain.exaggeration ?? 1) : 1),
+            ground: (lng, lat) => (this.terrain ? (map.queryTerrainElevation([lng, lat]) ?? 0) : 0),
+            warn: (e) => this.emitError(e),
+        }, this.options.deck ? async () => this.options.deck : loadDeck);
+        this.bindMapEvents(map);
+    }
+    setProjection(projection) {
+        const changed = projection !== this.projection;
+        this.projection = projection;
+        if (!this.map)
+            return;
+        this.applyEnvironment();
+        // Heights and models move between deck.gl and flat MapLibre drawing with the projection.
+        if (changed && this.sceneLayers.length)
+            this.applyLayers(this.sceneLayers.map((l) => this.drawable(l)));
+    }
+    /**
+     * The layer as this renderer can draw it now: in globe mode, layers at a height and models are drawn flat by
+     * MapLibre (see `capabilities`), so their objects stay visible.
+     */
+    drawable(layer) {
+        if (this.projection !== 'globe' || !hostedByDeck(layer))
+            return layer;
+        const { elevation: _e, model: _m, volume: _v, ...vz } = layer.visualization;
+        return { ...layer, visualization: { ...vz, type: vz.type === 'model' || vz.type === 'volume' ? 'marker' : vz.type } };
+    }
+    setTerrain(terrain) {
+        this.terrain = terrain;
+        if (!this.map)
+            return;
+        if (isPmtiles(terrain?.tileUrl) && !(this.lib && pmtilesReady.has(this.lib))) {
+            void this.ensurePmtiles([terrain?.tileUrl]).then(() => this.map && this.terrain === terrain && this.applyEnvironment());
+            return;
+        }
+        this.applyEnvironment();
+    }
+    /** pmtiles:// archives (offline tile packs, doc 28 G14): the protocol is loaded the first time a URL uses it. */
+    async ensurePmtiles(urls) {
+        const lib = this.lib;
+        if (!lib || pmtilesReady.has(lib) || !urls.some(isPmtiles))
+            return;
+        if (!lib.addProtocol)
+            return this.emitError(new Error('pmtiles:// needs a MapLibre module with addProtocol'));
+        const { Protocol } = await import('pmtiles');
+        if (pmtilesReady.has(lib))
+            return;
+        lib.addProtocol('pmtiles', new Protocol().tile);
+        pmtilesReady.add(lib);
+    }
+    /**
+     * Ground heights from the terrain the map shows. MapLibre answers only where terrain tiles are loaded (null
+     * elsewhere) and multiplies by the exaggeration; the engine reports true metres, so that is divided out.
+     */
+    /**
+     * True heights from the DEM tiles, decoded by the engine. Not MapLibre's queryTerrainElevation: it answers 0 (sea
+     * level, not "unknown") wherever the view has no tile loaded, so a line of sight off screen came out flat.
+     */
+    async sampleElevation(positions) {
+        if (!this.map || !this.terrain)
+            return positions.map(() => null);
+        if (this.dem?.terrain !== this.terrain)
+            this.dem = { terrain: this.terrain, sampler: new DemSampler(this.terrain, undefined, undefined, this.options.loadDemTile) };
+        return this.dem.sampler.sample(positions);
+    }
+    /**
+     * Projection, terrain (3D surface + hillshade) and sky — the map's environment, under every engine layer.
+     * Applied after load and again after a basemap swap (a new style drops them).
+     */
+    applyEnvironment() {
+        const map = this.map;
+        map.setProjection({ type: this.projection });
+        const t = this.terrain;
+        if (t) {
+            if (!map.getSource(TERRAIN_SOURCE))
+                map.addSource(TERRAIN_SOURCE, demSourceFor(t));
+            if (!map.getSource(HILLSHADE_SOURCE))
+                map.addSource(HILLSHADE_SOURCE, demSourceFor(t));
+            // Under the engine's layers: they are moved to the top as they are added.
+            if (!map.getLayer(HILLSHADE_LAYER))
+                map.addLayer(hillshadeLayer(this.theme), this.firstEngineLayer());
+            map.setTerrain({ source: TERRAIN_SOURCE, exaggeration: t.exaggeration ?? 1 });
+        }
+        else {
+            map.setTerrain(null);
+            if (map.getLayer(HILLSHADE_LAYER))
+                map.removeLayer(HILLSHADE_LAYER);
+            for (const id of [HILLSHADE_SOURCE, TERRAIN_SOURCE])
+                if (map.getSource(id))
+                    map.removeSource(id);
+        }
+        this.deckHost?.refresh(); // heights stand on the ground and scale with its exaggeration
+        void this.applyContours();
+        // A sky shows when the camera tilts above the horizon, and gives the globe its atmosphere.
+        map.setSky(t || this.projection === 'globe' ? { 'sky-color': this.theme.skyColor, 'horizon-color': this.theme.horizonColor, 'sky-horizon-blend': 0.5, 'atmosphere-blend': this.projection === 'globe' ? 0.8 : 0 } : {});
+    }
+    /** Contour lines from the terrain's DEM tiles (doc 28 G11), under every engine layer; removed when off. */
+    async applyContours() {
+        const map = this.map;
+        if (!map)
+            return;
+        const t = this.terrain;
+        const c = t?.contours;
+        const drop = () => {
+            for (const id of [CONTOUR_LABELS, CONTOUR_LINES])
+                if (map.getLayer(id))
+                    map.removeLayer(id);
+            if (map.getSource(CONTOUR_SOURCE))
+                map.removeSource(CONTOUR_SOURCE);
+        };
+        if (!t || !c)
+            return drop();
+        if (isPmtiles(t.tileUrl))
+            return this.emitError(new Error('contours read DEM tiles by URL template; a pmtiles:// terrain has no contours yet'));
+        if (!this.lib?.addProtocol)
+            return this.emitError(new Error('contours need a MapLibre module with addProtocol'));
+        const gen = this.gen;
+        const mod = (await import('maplibre-contour')).default;
+        if (gen !== this.gen || this.map !== map || this.terrain !== t)
+            return;
+        if (!this.contourDem || this.contourDem.url !== t.tileUrl) {
+            const source = new mod.DemSource({ url: t.tileUrl, encoding: t.encoding ?? 'terrarium', maxzoom: Math.min(t.maxZoom ?? 14, 14), worker: false });
+            source.setupMaplibre(this.lib);
+            this.contourDem = { url: t.tileUrl, source };
+        }
+        const major = c.majorEvery ?? 5;
+        // Coarser lines when zoomed out, the configured interval from zoom 13.
+        const tiles = this.contourDem.source.contourProtocolUrl({ thresholds: { 9: [c.interval * 4, c.interval * 4 * major], 11: [c.interval * 2, c.interval * 2 * major], 13: [c.interval, c.interval * major] }, contourLayer: 'contours', elevationKey: 'ele', levelKey: 'level' });
+        drop();
+        map.addSource(CONTOUR_SOURCE, { type: 'vector', tiles: [tiles], minzoom: 9, maxzoom: 15 });
+        for (const spec of contourLayers(this.theme, c.color, this.hasFont))
+            map.addLayer(spec, this.firstEngineLayer());
+    }
+    /** The first engine style layer in draw order, so environment layers can go beneath it. */
+    firstEngineLayer() {
+        for (const layer of [...this.layers.values()].sort((a, b) => a.zIndex - b.zIndex)) {
+            const first = styleLayersFor(layer, this.theme, this.hasFont)[0];
+            if (first && this.map?.getLayer(first.id))
+                return first.id;
+        }
+        return undefined;
+    }
+    /**
+     * A style swap (MapLibre setStyle): the camera, canvas and GPU context stay. Every engine source and layer goes
+     * with the old style, so the caller renders the full scene again afterwards (Renderer contract).
+     */
+    async setBasemap(basemap) {
+        const map = this.map;
+        if (!map)
+            return;
+        const gen = this.gen;
+        await this.ensurePmtiles([basemap.tileUrl, basemap.styleUrl, basemap.rasterFallback]);
+        const style = await this.resolveStyle(basemap);
+        if (gen !== this.gen || this.map !== map)
+            return;
+        this.hasFont = basemap.font !== undefined;
+        this.fontName = basemap.font?.name;
+        this.warnedNoFont = false;
+        this.hoverKey = null;
+        this.layers.clear();
+        this.features.clear();
+        this.images.clear();
+        const loaded = this.waitFor(map, 'style.load');
+        map.setStyle(style, { diff: false });
+        await loaded;
+        if (gen !== this.gen || this.map !== map)
+            return;
+        this.applyEnvironment(); // the new style has no terrain, projection or sky of ours (and re-places deck.gl layers)
+    }
+    /** The style for a basemap. A street-map style brings its own glyph server; engine labels use the app font, so it is added. */
+    async resolveStyle(basemap) {
+        const style = basemapStyle(basemap, this.theme);
+        if (typeof style !== 'string' || (!basemap.font && !this.offline))
+            return style;
+        const fetchFn = this.options.fetch ?? ((url) => fetch(url));
+        const res = await fetchFn(style);
+        if (!res.ok)
+            throw new Error(`basemap style ${style} returned HTTP ${res.status}`);
+        const json = (await res.json());
+        if (this.offline) {
+            // Offline profile: what the style file itself points at must stay on the site too (doc 28 G14).
+            const leaving = styleUrls(json).filter((u) => !isLocalUrl(u, this.offline));
+            if (leaving.length)
+                throw new Error(`offline profile: the basemap style points outside the site: ${leaving.slice(0, 5).join(', ')}`);
+        }
+        return (basemap.font ? withLabelFont(json, style, basemap.font.url) : json);
+    }
+    /** Waits for a style to load ('load' first time, 'style.load' after a swap); destroy() cancels the wait. */
+    waitFor(map, event) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                cleanup();
+                reject(new Error(`map style did not load within ${this.options.loadTimeoutMs ?? 15000} ms`));
+            }, this.options.loadTimeoutMs ?? 15000);
+            const onLoad = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (e) => {
+                // A tile that fails (offline, 404, rate limit) is not a failed map: keep waiting for the style.
+                if (e?.tile !== undefined || e?.sourceId !== undefined)
+                    return;
+                cleanup();
+                reject(toError(e?.error, 'map failed to load'));
+            };
+            const cancel = (reason) => {
+                cleanup();
+                reject(reason);
+            };
+            const cleanup = () => {
+                clearTimeout(timeout);
+                map.off(event, onLoad);
+                map.off('error', onError);
+                if (this.cancelWait === cancel)
+                    this.cancelWait = null;
+            };
+            this.cancelWait = cancel;
+            map.on(event, onLoad);
+            map.on('error', onError);
+        });
+    }
+    setViewport(viewport, options) {
+        if (!this.map)
+            return;
+        const camera = { center: toLngLat(viewport.center), zoom: viewport.zoom, bearing: viewport.bearing ?? 0, pitch: viewport.pitch ?? 0 };
+        if (options?.animate)
+            this.map.easeTo(camera);
+        else
+            this.map.jumpTo(camera);
+    }
+    render(scene) {
+        if (!this.map)
+            return;
+        for (const id of [...this.layers.keys()])
+            this.removeEngineLayer(id);
+        this.applyLayers(scene.layers.map((l) => this.drawable(l)));
+        this.sceneLayers = scene.layers;
+        this.applyObjects({ added: scene.objects });
+    }
+    update(patch) {
+        if (!this.map)
+            return;
+        if (patch.layers) {
+            this.sceneLayers = patch.layers;
+            this.applyLayers(patch.layers.map((l) => this.drawable(l)));
+        }
+        this.applyObjects(patch);
+    }
+    resize() {
+        if (!this.map)
+            return;
+        this.map.resize();
+        // MapLibre does not fire moveend on resize, but the visible bounds changed.
+        const v = this.currentViewport();
+        for (const l of this.listeners.viewport)
+            l(v);
+    }
+    project(position) {
+        if (!this.map)
+            return null;
+        const p = this.map.project(toLngLat(position));
+        return { x: p.x, y: p.y };
+    }
+    onCameraMove(l) {
+        const fn = () => l();
+        this.listeners.move.add(fn);
+        return () => this.listeners.move.delete(fn);
+    }
+    getSize() {
+        const c = this.map?.getContainer();
+        return { width: c?.clientWidth ?? 0, height: c?.clientHeight ?? 0 };
+    }
+    destroy() {
+        this.gen++;
+        this.cancelWait?.(new Error('renderer destroyed'));
+        this.deckHost?.destroy();
+        this.deckHost = null;
+        if (this.groundRefresh !== null)
+            clearTimeout(this.groundRefresh);
+        this.groundRefresh = null;
+        if (this.workerCheck !== null)
+            clearTimeout(this.workerCheck);
+        this.workerCheck = null;
+        this.workerChecked = false;
+        const map = this.map;
+        this.map = null;
+        if (map) {
+            for (const off of this.mapHandlers)
+                off();
+            try {
+                map.remove();
+            }
+            catch {
+                // Removing must always complete.
+            }
+        }
+        this.mapHandlers.length = 0;
+        this.layers.clear();
+        this.features.clear();
+        for (const set of Object.values(this.listeners))
+            set.clear();
+    }
+    onViewportChange(l) {
+        return this.add(this.listeners.viewport, l);
+    }
+    onPick(l) {
+        return this.add(this.listeners.pick, l);
+    }
+    onMapClick(l) {
+        return this.add(this.listeners.click, l);
+    }
+    onHover(l) {
+        return this.add(this.listeners.hover, l);
+    }
+    onError(l) {
+        return this.add(this.listeners.error, l);
+    }
+    // ---------------------------------------------------------------- layers
+    /** Adds, removes, restyles, shows/hides and reorders engine layers. Basemap layers are never touched. */
+    applyLayers(next) {
+        const map = this.map;
+        const nextIds = new Set(next.map((l) => l.id));
+        for (const id of [...this.layers.keys()])
+            if (!nextIds.has(id))
+                this.removeEngineLayer(id);
+        if (!this.hasFont && !this.warnedNoFont && next.some((l) => l.visualization.label)) {
+            this.warnedNoFont = true;
+            this.emitError(new Error('labels need a label font: set basemap.font = { name, url } (no glyph server is used)'));
+        }
+        for (const layer of next) {
+            const prev = this.layers.get(layer.id);
+            this.ensureImages(layer);
+            if (!prev) {
+                map.addSource(sourceId(layer.id), sourceSpecFor(layer));
+                this.features.set(layer.id, { ids: new Map(), objects: new Map(), next: 1 });
+                for (const spec of styleLayersFor(layer, this.theme, this.hasFont))
+                    map.addLayer(spec);
+            }
+            else if (!deepEqual(sourceSpecFor(prev), sourceSpecFor(layer))) {
+                // Clustering is a source option: rebuild this layer's source, then put its objects back (same feature ids).
+                for (const spec of styleLayersFor(prev, this.theme, this.hasFont))
+                    if (map.getLayer(spec.id))
+                        map.removeLayer(spec.id);
+                map.removeSource(sourceId(layer.id));
+                map.addSource(sourceId(layer.id), sourceSpecFor(layer));
+                for (const spec of styleLayersFor(layer, this.theme, this.hasFont))
+                    map.addLayer(spec);
+                const lf = this.features.get(layer.id);
+                this.layers.set(layer.id, structuredClone(layer));
+                const src = this.source(layer.id);
+                if (src)
+                    this.writeSource(layer.id, src, [], [...lf.objects.values()].flatMap((so) => this.featuresOf(so, lf.ids.get(so.object.objectId), layer)));
+                for (const so of lf.objects.values())
+                    if (so.selected || so.hovered)
+                        map.setFeatureState({ source: sourceId(layer.id), id: lf.ids.get(so.object.objectId) }, { selected: so.selected, hovered: so.hovered });
+            }
+            else if (!deepEqual(prev.visualization, layer.visualization)) {
+                // Style or type changed: rebuild only this layer's style layers; the source and its data stay.
+                for (const spec of styleLayersFor(prev, this.theme, this.hasFont))
+                    if (map.getLayer(spec.id))
+                        map.removeLayer(spec.id);
+                for (const spec of styleLayersFor(layer, this.theme, this.hasFont))
+                    map.addLayer(spec);
+                if (needsLabelPoints(prev) !== needsLabelPoints(layer) || prev.visualization.label?.placement !== layer.visualization.label?.placement) {
+                    // Label points come, go or move with the label: rewrite this layer's features.
+                    const lf = this.features.get(layer.id);
+                    const src = this.source(layer.id);
+                    const ids = [...lf.ids.values()];
+                    this.layers.set(layer.id, structuredClone(layer));
+                    if (src)
+                        this.writeSource(layer.id, src, [...ids, ...ids.map((fid) => fid + LABEL_ID_OFFSET)], [...lf.objects.values()].flatMap((so) => this.featuresOf(so, lf.ids.get(so.object.objectId), layer)));
+                }
+            }
+            else if (prev.visible !== layer.visible) {
+                for (const spec of styleLayersFor(layer, this.theme, this.hasFont))
+                    map.setLayoutProperty(spec.id, 'visibility', layer.visible ? 'visible' : 'none');
+            }
+            this.layers.set(layer.id, structuredClone(layer));
+        }
+        // Layers at a height and models live in the deck.gl host; keep it in step with the layer list.
+        this.syncDeck(next);
+        // zIndex order: move each engine style layer to the top, lowest zIndex first (an image layer's pictures go
+        // first, under its outline).
+        const ordered = [...next].sort((a, b) => a.zIndex - b.zIndex || a.id.localeCompare(b.id));
+        for (const layer of ordered) {
+            if (layer.visualization.type === 'image')
+                this.syncImages(layer);
+            for (const id of this.imageLayerIds(layer.id))
+                map.moveLayer(id);
+            for (const spec of styleLayersFor(layer, this.theme, this.hasFont))
+                map.moveLayer(spec.id);
+        }
+    }
+    // ---------------------------------------------------------------- image layers (doc 28 G12)
+    imageId(layerId, objectId) {
+        return `${PREFIX}:img:${layerId}:${objectId}`;
+    }
+    imageLayerIds(layerId) {
+        return [...(this.images.get(layerId)?.keys() ?? [])].map((oid) => this.imageId(layerId, oid));
+    }
+    /** One image source and raster layer per object, placed by its corners; follows moves, image changes and removal. */
+    syncImages(layer) {
+        const map = this.map;
+        const have = this.images.get(layer.id) ?? new Map();
+        const seen = new Set();
+        const cfg = layer.visualization.image;
+        const visibility = layer.visible ? 'visible' : 'none';
+        for (const so of this.features.get(layer.id)?.objects.values() ?? []) {
+            const corners = imageCorners(so.object.geometry);
+            const raw = cfg?.urlProperty ? so.object.properties?.[cfg.urlProperty] : undefined;
+            const url = typeof raw === 'string' && raw ? raw : cfg?.url;
+            if (!corners || !url)
+                continue;
+            const oid = so.object.objectId;
+            seen.add(oid);
+            const id = this.imageId(layer.id, oid);
+            const coords = JSON.stringify(corners);
+            const prev = have.get(oid);
+            if (!prev || !map.getSource(id)) {
+                map.addSource(id, { type: 'image', url, coordinates: corners });
+                map.addLayer({ id, type: 'raster', source: id, layout: { visibility }, paint: { 'raster-opacity': cfg?.opacity ?? 0.85, 'raster-fade-duration': 0 } }, styleLayersFor(layer, this.theme, this.hasFont)[0]?.id);
+            }
+            else if (prev.url !== url)
+                map.getSource(id).updateImage({ url, coordinates: corners });
+            else if (prev.coords !== coords)
+                map.getSource(id).setCoordinates(corners);
+            else
+                map.setLayoutProperty(id, 'visibility', visibility);
+            have.set(oid, { url, coords });
+        }
+        for (const oid of [...have.keys()]) {
+            if (seen.has(oid))
+                continue;
+            const id = this.imageId(layer.id, oid);
+            if (map.getLayer(id))
+                map.removeLayer(id);
+            if (map.getSource(id))
+                map.removeSource(id);
+            have.delete(oid);
+        }
+        this.images.set(layer.id, have);
+    }
+    dropImages(layerId) {
+        const map = this.map;
+        for (const id of this.imageLayerIds(layerId)) {
+            if (map.getLayer(id))
+                map.removeLayer(id);
+            if (map.getSource(id))
+                map.removeSource(id);
+        }
+        this.images.delete(layerId);
+    }
+    /** Registers the icon images a layer uses (built-in shapes synchronously, URLs when they load). */
+    ensureImages(layer) {
+        const map = this.map;
+        for (const img of imagesFor(layer)) {
+            if (map.hasImage(img.id))
+                continue;
+            if (img.shape) {
+                map.addImage(img.id, shapeImage(img.shape), { sdf: true, pixelRatio: 1 });
+            }
+            else if (img.url) {
+                map.loadImage(img.url).then((res) => {
+                    // Icon sizes assume a 32-pixel image; any other size is declared through its pixel ratio.
+                    if (this.map && !this.map.hasImage(img.id))
+                        this.map.addImage(img.id, res.data, { pixelRatio: Math.max(0.1, res.data.width / ICON_PIXELS) });
+                }, (e) => this.emitError(new Error(`icon image ${img.url} failed to load: ${e instanceof Error ? e.message : String(e)}`)));
+            }
+        }
+    }
+    removeEngineLayer(id) {
+        const map = this.map;
+        this.dropImages(id);
+        const layer = this.layers.get(id);
+        if (layer)
+            for (const spec of styleLayersFor(layer, this.theme, this.hasFont))
+                if (map.getLayer(spec.id))
+                    map.removeLayer(spec.id);
+        if (map.getSource(sourceId(id)))
+            map.removeSource(sourceId(id));
+        this.layers.delete(id);
+        this.features.delete(id);
+    }
+    // ---------------------------------------------------------------- objects
+    applyObjects(patch) {
+        const diffs = new Map();
+        const diffFor = (layerId) => {
+            let d = diffs.get(layerId);
+            if (!d)
+                diffs.set(layerId, (d = { remove: [], add: [], states: [], cleared: [] }));
+            return d;
+        };
+        for (const key of patch.removed ?? []) {
+            const [layerId, objectId] = splitKey(key);
+            const lf = this.features.get(layerId);
+            const fid = lf?.ids.get(objectId);
+            if (!lf || fid === undefined)
+                continue;
+            lf.ids.delete(objectId);
+            lf.objects.delete(objectId);
+            const d = diffFor(layerId);
+            d.remove.push(fid);
+            if (this.layers.get(layerId) && needsLabelPoints(this.layers.get(layerId)))
+                d.remove.push(fid + LABEL_ID_OFFSET);
+            d.cleared.push(fid);
+        }
+        for (const so of [...(patch.added ?? []), ...(patch.updated ?? [])]) {
+            const lf = this.features.get(so.layerId);
+            if (!lf)
+                continue;
+            const objectId = so.object.objectId;
+            const prev = lf.objects.get(objectId);
+            let fid = lf.ids.get(objectId);
+            const d = diffFor(so.layerId);
+            const layer = this.layers.get(so.layerId);
+            if (fid === undefined) {
+                fid = lf.next++;
+                lf.ids.set(objectId, fid);
+                d.add.push(...this.featuresOf(so, fid, layer));
+            }
+            else if (!prev || !deepEqual(prev.object, so.object)) {
+                d.remove.push(fid);
+                if (layer && needsLabelPoints(layer))
+                    d.remove.push(fid + LABEL_ID_OFFSET);
+                d.add.push(...this.featuresOf(so, fid, layer));
+            }
+            if (!prev || prev.selected !== so.selected || prev.hovered !== so.hovered)
+                d.states.push([fid, so]);
+            lf.objects.set(objectId, so);
+        }
+        for (const [layerId, d] of diffs) {
+            const layer = this.layers.get(layerId);
+            if (layer?.visualization.type === 'image')
+                this.syncImages(layer);
+            if (layer && hostedByDeck(layer)) {
+                this.deckHost?.setLayer(layer, [...(this.features.get(layerId)?.objects.values() ?? [])]);
+                continue;
+            }
+            const src = this.source(layerId);
+            if (!src)
+                continue;
+            if (d.remove.length || d.add.length)
+                this.writeSource(layerId, src, d.remove, d.add);
+            for (const fid of d.cleared)
+                this.map.removeFeatureState({ source: sourceId(layerId), id: fid });
+            for (const [fid, so] of d.states)
+                this.map.setFeatureState({ source: sourceId(layerId), id: fid }, { selected: so.selected, hovered: so.hovered });
+        }
+    }
+    /**
+     * Hands deck.gl the layers it draws; a layer that moves back to MapLibre (its height removed) gets its features
+     * written to its source again, since they were not kept there while deck.gl drew it.
+     */
+    syncDeck(next) {
+        const host = this.deckHost;
+        if (!host)
+            return;
+        const ids = new Set(next.map((l) => l.id));
+        for (const layer of next) {
+            const lf = this.features.get(layer.id);
+            if (hostedByDeck(layer))
+                host.setLayer(layer, [...(lf?.objects.values() ?? [])]);
+            else if (host.has(layer.id)) {
+                host.removeLayer(layer.id);
+                const src = this.source(layer.id);
+                if (src && lf)
+                    this.writeSource(layer.id, src, [], [...lf.objects.values()].flatMap((so) => this.featuresOf(so, lf.ids.get(so.object.objectId), layer)));
+            }
+        }
+        for (const id of [...this.layers.keys()])
+            if (!ids.has(id) && host.has(id))
+                host.removeLayer(id);
+    }
+    /** The shape, plus for labelled areas its one label point (an area is labelled once, not once per map tile). */
+    featuresOf(so, fid, layer) {
+        const shape = this.feature(so, fid);
+        if (!layer || !needsLabelPoints(layer))
+            return [shape];
+        const at = toFeature({ type: 'Point', coordinates: spatial.labelPoint(so.object.geometry, layer.visualization.label?.placement) }, { ...shape.properties, [LABEL_POINT_PROP]: true });
+        return [shape, { ...at, id: fid + LABEL_ID_OFFSET }];
+    }
+    feature(so, fid) {
+        const props = {};
+        for (const [k, v] of Object.entries(so.object.properties ?? {})) {
+            // Only primitives can drive style expressions; nested data stays in the engine.
+            if (v === null || ['string', 'number', 'boolean'].includes(typeof v))
+                props[k] = v;
+        }
+        props[OBJECT_ID_PROP] = so.object.objectId;
+        props[LAYER_ID_PROP] = so.layerId;
+        return { ...toFeature(so.object.geometry, props), id: fid };
+    }
+    /**
+     * MapLibre's v6 module needs its worker bundled by the app; without it nothing errors, the map just stays empty.
+     * Once, after the first objects are written, check that their source finished loading — and name the fix if not.
+     */
+    watchWorker(layerId) {
+        if (this.workerChecked)
+            return;
+        this.workerChecked = true;
+        const gen = this.gen;
+        this.workerCheck = setTimeout(() => {
+            this.workerCheck = null;
+            const map = this.map;
+            if (gen !== this.gen || !map || !map.getSource(sourceId(layerId)) || map.isSourceLoaded(sourceId(layerId)))
+                return;
+            this.emitError(new Error("map data did not load: MapLibre's web worker is probably not wired. Pass `workerUrl` to MapLibreRenderer (with Vite: import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url')."));
+        }, this.options.workerCheckMs ?? 8000);
+    }
+    writeSource(layerId, src, remove, add) {
+        if (add.length)
+            this.watchWorker(layerId);
+        const report = (e) => this.emitError(e instanceof Error ? e : new Error(String(e)));
+        try {
+            if (typeof src.updateData === 'function') {
+                const r = src.updateData({ remove, add });
+                if (r instanceof Promise)
+                    r.catch(report);
+            }
+            else {
+                // Fallback for sources without diff support: rewrite this one layer's collection.
+                const lf = this.features.get(layerId);
+                const layer = this.layers.get(layerId);
+                const features = [...lf.objects.values()].flatMap((so) => this.featuresOf(so, lf.ids.get(so.object.objectId), layer));
+                const r = src.setData({ type: 'FeatureCollection', features });
+                if (r instanceof Promise)
+                    r.catch(report);
+            }
+        }
+        catch (e) {
+            report(e);
+        }
+    }
+    source(layerId) {
+        return this.map?.getSource(sourceId(layerId));
+    }
+    // ---------------------------------------------------------------- events
+    bindMapEvents(map) {
+        const on = (type, fn) => {
+            map.on(type, fn);
+            this.mapHandlers.push(() => map.off(type, fn));
+        };
+        on('move', () => {
+            for (const l of this.listeners.move)
+                l(undefined);
+        });
+        on('moveend', () => {
+            const v = this.currentViewport();
+            for (const l of this.listeners.viewport)
+                l(v);
+        });
+        on('click', (ev) => {
+            const e = ev;
+            const hit = this.hitTest(e.point);
+            const position = fromLngLat(e.lngLat);
+            if (hit && 'clusterId' in hit)
+                this.zoomIntoCluster(hit);
+            else if (hit)
+                for (const l of this.listeners.pick)
+                    l({ ...hit, position });
+            else
+                for (const l of this.listeners.click)
+                    l({ position });
+        });
+        on('mousemove', (ev) => {
+            const hit = this.hitTest(ev.point);
+            this.setHover(hit && 'clusterId' in hit ? null : hit, hit !== null);
+        });
+        on('mouseout', () => this.setHover(null));
+        // Heights stand on terrain: as its tiles arrive, place objects again (debounced; no loop, unlike 'idle').
+        on('sourcedata', (ev) => {
+            const e = ev;
+            if (e.sourceId !== TERRAIN_SOURCE || !this.terrain)
+                return;
+            if (this.groundRefresh !== null)
+                clearTimeout(this.groundRefresh);
+            this.groundRefresh = setTimeout(() => {
+                this.groundRefresh = null;
+                this.deckHost?.refresh();
+            }, 250);
+        });
+        on('error', (e) => this.emitError(toError(e.error, 'map error')));
+        on('webglcontextlost', () => this.emitError(new Error('WebGL context lost')));
+    }
+    setHover(hit, pointer = hit !== null) {
+        const canvas = this.map?.getCanvas();
+        if (canvas)
+            canvas.style.cursor = pointer ? 'pointer' : '';
+        const key = hit ? `${hit.layerId}:${hit.objectId}` : null;
+        if (key === this.hoverKey)
+            return;
+        this.hoverKey = key;
+        for (const l of this.listeners.hover)
+            l(hit);
+    }
+    /** Top-most engine feature under the pointer: an object (stable objectId) or a cluster bubble. Heatmaps are not pickable. */
+    hitTest(point) {
+        if (!this.map)
+            return null;
+        // Objects in the air and models sit above everything MapLibre draws: they are picked first.
+        const lifted = this.deckHost?.pick(point.x, point.y, this.options.hitTolerance ?? 4);
+        if (lifted)
+            return lifted;
+        const layers = [...this.layers.values()]
+            .filter((l) => l.visible)
+            .flatMap((l) => styleLayersFor(l, this.theme, this.hasFont).filter((s) => s.type !== 'heatmap').map((s) => s.id));
+        if (!layers.length)
+            return null;
+        const t = this.options.hitTolerance ?? 4;
+        const hits = this.map.queryRenderedFeatures([[point.x - t, point.y - t], [point.x + t, point.y + t]], { layers });
+        for (const f of hits) {
+            if (f.properties.cluster === true && typeof f.properties.cluster_id === 'number') {
+                const layerId = f.layer.id.split(':')[1];
+                const c = f.geometry?.type === 'Point' ? f.geometry.coordinates : undefined;
+                return { layerId, clusterId: f.properties.cluster_id, ...(c ? { lngLat: c } : {}) };
+            }
+            const objectId = f.properties[OBJECT_ID_PROP];
+            const layerId = f.properties[LAYER_ID_PROP];
+            if (typeof objectId === 'string' && typeof layerId === 'string')
+                return { objectId, layerId };
+        }
+        return null;
+    }
+    /** A click on a cluster bubble zooms to where it splits; the camera move then reaches the engine as usual. */
+    zoomIntoCluster(hit) {
+        const src = this.source(hit.layerId);
+        if (!src?.getClusterExpansionZoom || !this.map)
+            return;
+        src.getClusterExpansionZoom(hit.clusterId).then((zoom) => this.map?.easeTo({ ...(hit.lngLat ? { center: hit.lngLat } : {}), zoom }), (e) => this.emitError(e instanceof Error ? e : new Error(String(e))));
+    }
+    currentViewport() {
+        const map = this.map;
+        const c = map.getCenter();
+        const center = c.wrap ? c.wrap() : c;
+        const b = map.getBounds();
+        return {
+            center: fromLngLat(center),
+            zoom: map.getZoom(),
+            bearing: normalizeBearing(map.getBearing()),
+            pitch: map.getPitch(),
+            bounds: { west: clampLon(b.getWest()), south: clampLat(b.getSouth()), east: clampLon(b.getEast()), north: clampLat(b.getNorth()) },
+        };
+    }
+    emitError(error) {
+        for (const l of this.listeners.error)
+            l(error);
+    }
+    add(set, l) {
+        set.add(l);
+        return () => set.delete(l);
+    }
+}