Class MaplibreAdapter

The error the MapLibre constructor threw during init(), or null.

The facade turns a failed construction into null; this is what lets the boot still name the cause.

Whether error is MapLibre's GPUInitializationError — thrown when the browser cannot create the WebGL2 context MapLibre 6 requires.

The class is matched when the MapLibre global exposes it; the name is the fallback for a build or a test double that does not.

Whether a MapLibre GL JS engine is in reach — the ambient maplibregl global the adapter builds with, carrying a Map constructor.

Whether error is the one MaplibreAdapter.init throws when no engine is in reach (see MaplibreAdapter.hasEngine).

Creates and mounts the map inside the given container. Must be called exactly once before any other method.

Returns true after init() has completed successfully. Methods that depend on a live map instance should guard on this flag.

Destroys the map instance and releases all resources. After destroy(), no other method may be called.

Sets the map center and zoom level without animation.

Returns the current geographic center of the map viewport.

Returns the current zoom level.

Sets the zoom level without changing the center.

Pans the map to the given center without changing the zoom level.

MapLibre uses easeTo() without zoom change.

Smoothly animates the viewport to the target center and zoom level.

Adjusts the viewport to fit the given bounding box.

Returns the current viewport as a geographic bounding box.

Subscribes to a map event.

The handler receives an engine-specific event object (unknown). Adapters normalise geographic coordinates to GeoLeafLatLng within the event object where applicable.

Unsubscribes a previously registered event handler. Silently does nothing if the handler was not registered.

Subscribes to a map event for a single occurrence, then auto-unsubscribes.

Creates a GeoJSON source + fill/line/circle sub-layers for the given data.

Adds a native vector-tile source + its styled sub-layers (socle B.1). The vector-tiles capability resolves config/style and delegates rendering here, mirroring addGeoJSONLayer. Returns the created sub-layer ids for the caller to bind interactions and record in shared state.

Updates the paint of an existing vector-tile layer's sub-layers.

Removes all MapLibre layers and the source for the given GeoLeaf layer.

Returns true if the layer is registered in the adapter.

Shows all sub-layers for the given GeoLeaf layer.

Hides all sub-layers for the given GeoLeaf layer.

Replaces the GeoJSON data of an existing source.

Applies a partial update to an existing source, and reports whether it took it.

Returns false — never throws, never falls back on its own — whenever the live source cannot address features by id. The caller owns the fallback because the caller owns the whole collection; see the contract's note on why that placement is what makes the fallback observable.

⚠️ The promise from updateData is dropped, exactly as setData's already is (it is Promise<void> too in MapLibre 6). The catch is a guard against a FUTURE version rejecting: today _dispatchWorkerUpdate swallows everything into an ErrorEvent, so this handler cannot fire. Said plainly here so the next reader does not mistake it for a covered case.

Sets feature-state on a registered source's feature, targeted by its promoted id. Used for reactive paint (POI sync badge, hover/selection halo) without rebuilding the source data. No-op if the source is gone. The source must declare promoteId for a string id to resolve.

Applies a style to an existing layer by updating paint properties on each sub-layer.

Applies owner's filter expression to a registered layer's sub-layers, AND-ed with the other owners' filters (_composeFilterSlots). For cluster groups, filters the unclustered-point layer specifically. Pass null to clear owner's filter — the other owners' stay.

🛑 The caller's filter is COMPOSED with the filter each sub-layer was BUILT with, never substituted for it. setFilter replaces a layer's filter wholesale, and the builders put there predicates the drawing depends on: a typed sub-layer's geometry guard, a clustered layer's point_count predicates (the unclustered circle, the bubbles, their count), an icon sub-layer's symbolId. A plain assignment stripped them for as long as a filter was active — a clustered layer drew its centroids as points and its points as bubbles — and clearing it stripped them for good. The built filter is read from the engine the first time a caller filters the sub-layer: until then, only the builders have written it — a filter written through getNativeMap() before that is taken for the built one, one written after is replaced.

⚠️ A bubble carries none of its points' properties — only cluster, cluster_id, point_count and point_count_abbreviated. A filter that REQUIRES a property value therefore hides every bubble; one that passes a feature lacking the property — such as hideFeatures' exclusion — keeps them. The core's own filter re-feeds a clustered layer instead (geojson-filter.ts).

Sets the zoom range on every sub-layer of a registered layer.

Iterates getSubLayerIds rather than subLayerTypes: only the former carries the cluster sub-layers (they are registered via customSubLayerIds), and a cluster left out of the range would keep rendering outside it.

Re-ranks a GeoJSON layer in place, and reports whether it did. The contract says where the layer lands, what is kept and when the answer is false; the move itself is applyLayerZIndex.

Creates a DOM marker at the given position and adds it to the map.

Removes a marker from the map and releases its resources.

Updates the geographic position of an existing marker.

Rotates an existing marker's icon. See the contract for why alignment matters.

Returns the native marker registered under id, or null.

maplibregl.Marker structurally satisfies GeoLeafMarkerHandle (it exposes both getLngLat() and on()), so the handle needs no wrapper — but the narrow return type keeps the rest of the engine surface out of callers' reach.

Creates a popup (not opened — call openPopup() after). Content must be pre-sanitised.

Opens (displays) a popup on the map.

Closes a popup without destroying it. When popup is omitted, all open popups are closed.

Adds a control (HTMLElement or native IControl) at the given position.

Removes a control from the map.

Projects a geographic coordinate to a pixel point relative to the map container's top-left corner.

Unprojects a pixel point (relative to the map container) back to a geographic coordinate.

Returns the map's root DOM container element. Useful for positioning custom overlays or reading container dimensions.

Returns the WebGL drawing canvas.

The element cursor changes must target — see the contract for why getContainer() is not a substitute.

Re-reads the container size and resizes the WebGL drawing buffer.

The third of the three gestures resize needs: declaring it on the contract and calling it from reattach() is not enough — without an implementation the call lands on undefined and, the member being optional, does so in SILENCE.

Escape hatch — returns the underlying maplibregl.Map instance.

Enters exclusive mode, painting cursor on the canvas when given. The contract says what the mode stops and why there is no token; the bookkeeping is armToolCursor's.

Exits exclusive mode, restoring a cursor the entry painted. A no-op on a map not yet created or already destroyed: a tool's teardown must not throw for that.

Whether a tool holds exclusive mode; false while there is no map.

Builds a transformStyle callback that preserves the GeoLeaf-owned sources and layers across a map.setStyle() basemap swap, so they survive natively instead of being torn down and re-injected from JS (the former geoleaf:style:rebuild dance — audit redundancy #1).

What GeoLeaf owns — the layer registry (GeoJSON sub-layers + sources), the POI cluster ids, the sentinel z-anchor, and what code outside the adapter declared through declareOwnedStyleIds — is read when MapLibre RUNS the callback, not here. For a style given by URL that is once the style has downloaded, and the layers created in between must be carried too.

🛑 Never null, even with nothing owned and no credit declared: an empty registry NOW says nothing about the registry when the style lands. Returning null handed the caller a plain setStyle(), which diffs the arriving style all the same and erased every layer created during the download — the boot of a vector default basemap, whose data layers land exactly then.

Called by the basemap registry immediately before setStyle().

Declares engine layers and sources placed on the map outside this adapter, so that a basemap swap carries them. See the contract: keyed by owner, null withdraws, read when the swap runs, forgotten on destroy().

Puts back the runtime images a map.setStyle() may have left behind: the hatch patterns, then the POI sprite icons.

The transformStyle merge (see buildStyleChangeTransform) carries sources and layers. Images added via map.addImage() are not part of the style spec, and what becomes of them depends on the engine: a style change it can DIFF keeps them, one it cannot — it then rebuilds the style from scratch — starts with an empty image store. Both steps only add what is missing, so they cost nothing on the first path.

The sprite step is skipped when no profile sprite is present, so sprite-less profiles pay nothing and log no warning; the hatch step runs regardless.

Called by the basemap registry inside the post-swap style.load handler.

Returns the layer registry (read-only, for popup-tooltip event binding).