@defra/interactive-map 0.0.17-alpha → 0.0.18-alpha

package/plugins/beta/datasets/src/DatasetsInit.jsx

@@ -1,11 +1,12 @@
 // src/plugins/datasets/datasetsInit.jsx
 import { useEffect, useRef } from 'react'
+import { EVENTS } from '../../../../src/config/events.js'
 import { datasetDefaults } from './defaults.js'
 import { createDatasets } from './datasets.js'
 
 export function DatasetsInit ({ pluginConfig, pluginState, appState, mapState, mapProvider, services }) {
   const { dispatch } = pluginState
-  const { events, eventBus } = services
+  const { eventBus, symbolRegistry, patternRegistry } = services
 
   const isMapStyleReady = !!mapProvider.map?.getStyle()
 
@@ -40,7 +41,7 @@ export function DatasetsInit ({ pluginConfig, pluginState, appState, mapState, m
       }
 
       const { default: LayerAdapter } = await pluginConfig.layerAdapter.load()
-      const adapter = new LayerAdapter(mapProvider.map)
+      const adapter = new LayerAdapter(mapProvider, symbolRegistry, patternRegistry)
 
       dispatch({ type: 'SET_LAYER_ADAPTER', payload: adapter })
 
@@ -48,9 +49,9 @@ export function DatasetsInit ({ pluginConfig, pluginState, appState, mapState, m
         adapter,
         pluginConfig,
         pluginStateRef,
-        mapStyleId: mapState.mapStyle.id,
+        mapStyle: mapState.mapStyle,
         mapProvider,
-        events,
+        events: EVENTS,
         eventBus
       })
     }
@@ -58,6 +59,10 @@ export function DatasetsInit ({ pluginConfig, pluginState, appState, mapState, m
     initDatasets()
   }, [isMapStyleReady, appState.mode])
 
+  useEffect(() => {
+    dispatch({ type: 'BUILD_KEY_GROUPS', payload: null })
+  }, [pluginState.datasets])
+
   // Cleanup only on unmount
   useEffect(() => {
     return () => {

package/plugins/beta/datasets/src/adapters/maplibre/layerBuilders.js

@@ -1,7 +1,8 @@
 import { getValueForStyle } from '../../../../../../src/utils/getValueForStyle.js'
-import { hasPattern, getPatternImageId } from '../../styles/patterns.js'
+import { hasPattern, getPatternImageId } from './patternImages.js'
 import { mergeSublayer } from '../../utils/mergeSublayer.js'
 import { getSourceId, getLayerIds, getSublayerLayerIds, isDynamicSource, MAX_TILE_ZOOM } from './layerIds.js'
+import { hasSymbol, getSymbolDef, getSymbolAnchor, anchorToMaplibre, getSymbolImageId } from './symbolImages.js'
 
 // ─── Source ───────────────────────────────────────────────────────────────────
 
@@ -28,14 +29,14 @@ export const addSource = (map, dataset, sourceId) => {
 
 // ─── Fill layer ───────────────────────────────────────────────────────────────
 
-export const addFillLayer = (map, config, layerId, sourceId, sourceLayer, visibility, mapStyleId) => {
+export const addFillLayer = (map, config, layerId, sourceId, sourceLayer, visibility, { mapStyleId, patternRegistry }) => {
   if (!layerId || map.getLayer(layerId)) {
     return
   }
   if (!config.fill && !hasPattern(config)) {
     return
   }
-  const patternImageId = hasPattern(config) ? getPatternImageId(config, mapStyleId) : null
+  const patternImageId = hasPattern(config) ? getPatternImageId(config, mapStyleId, patternRegistry) : null
   const paint = patternImageId
     ? { 'fill-pattern': patternImageId, 'fill-opacity': config.opacity || 1 }
     : { 'fill-color': getValueForStyle(config.fill, mapStyleId), 'fill-opacity': config.opacity || 1 }
@@ -44,6 +45,8 @@ export const addFillLayer = (map, config, layerId, sourceId, sourceLayer, visibi
     type: 'fill',
     source: sourceId,
     'source-layer': sourceLayer,
+    minzoom: config.minZoom,
+    maxzoom: config.maxZoom,
     layout: { visibility },
     paint,
     ...(config.filter ? { filter: config.filter } : {})
@@ -61,6 +64,8 @@ export const addStrokeLayer = (map, config, layerId, sourceId, sourceLayer, visi
     type: 'line',
     source: sourceId,
     'source-layer': sourceLayer,
+    minzoom: config.minZoom,
+    maxzoom: config.maxZoom,
     layout: { visibility },
     paint: {
       'line-color': getValueForStyle(config.stroke, mapStyleId),
@@ -72,15 +77,46 @@ export const addStrokeLayer = (map, config, layerId, sourceId, sourceLayer, visi
   })
 }
 
+// ─── Symbol layer ─────────────────────────────────────────────────────────────
+
+export const addSymbolLayer = (map, dataset, layerId, sourceId, sourceLayer, visibility, { mapStyle, symbolRegistry, pixelRatio }) => {
+  if (!layerId || map.getLayer(layerId)) { return }
+  const symbolDef = getSymbolDef(dataset, symbolRegistry)
+  if (!symbolDef) { return }
+  const imageId = getSymbolImageId(dataset, mapStyle, symbolRegistry, false, pixelRatio)
+  if (!imageId) { return }
+  const anchor = getSymbolAnchor(dataset, symbolDef)
+  map.addLayer({
+    id: layerId,
+    type: 'symbol',
+    source: sourceId,
+    'source-layer': sourceLayer,
+    minzoom: dataset.minZoom,
+    maxzoom: dataset.maxZoom,
+    layout: {
+      visibility,
+      'icon-image': imageId,
+      'icon-anchor': anchorToMaplibre(anchor),
+      'icon-allow-overlap': true
+    },
+    ...(dataset.filter ? { filter: dataset.filter } : {})
+  })
+}
+
 // ─── Dataset layers ───────────────────────────────────────────────────────────
 
-export const addSublayerLayers = (map, dataset, sublayer, sourceId, sourceLayer, mapStyleId) => {
+export const addSublayerLayers = (map, dataset, sublayer, sourceId, sourceLayer, { mapStyle, symbolRegistry, patternRegistry, pixelRatio }) => {
+  const mapStyleId = mapStyle.id
   const merged = mergeSublayer(dataset, sublayer)
-  const { fillLayerId, strokeLayerId } = getSublayerLayerIds(dataset.id, sublayer.id)
+  const { fillLayerId, strokeLayerId, symbolLayerId } = getSublayerLayerIds(dataset.id, sublayer.id)
   const parentHidden = dataset.visibility === 'hidden'
   const sublayerHidden = dataset.sublayerVisibility?.[sublayer.id] === 'hidden'
   const visibility = (parentHidden || sublayerHidden) ? 'none' : 'visible'
-  addFillLayer(map, merged, fillLayerId, sourceId, sourceLayer, visibility, mapStyleId)
+  if (hasSymbol(merged) && symbolRegistry) {
+    addSymbolLayer(map, merged, symbolLayerId, sourceId, sourceLayer, visibility, { mapStyle, symbolRegistry, pixelRatio })
+    return
+  }
+  addFillLayer(map, merged, fillLayerId, sourceId, sourceLayer, visibility, { mapStyleId, patternRegistry })
   addStrokeLayer(map, merged, strokeLayerId, sourceId, sourceLayer, visibility, mapStyleId)
 }
 
@@ -89,10 +125,14 @@ export const addSublayerLayers = (map, dataset, sublayer, sourceId, sourceLayer,
  * Returns the sourceId so the caller can track the datasetId → sourceId mapping.
  * @param {Object} map - MapLibre map instance
  * @param {Object} dataset
- * @param {string} mapStyleId
+ * @param {Object} mapStyle - Current map style config (provides id, selectedColor, haloColor)
+ * @param {Object} [symbolRegistry]
+ * @param {Object} [patternRegistry]
+ * @param {number} [pixelRatio] - Device pixel ratio × map size scale factor
  * @returns {string} sourceId
  */
-export const addDatasetLayers = (map, dataset, mapStyleId) => {
+export const addDatasetLayers = (map, dataset, mapStyle, symbolRegistry, patternRegistry, pixelRatio) => {
+  const mapStyleId = mapStyle.id
   const sourceId = getSourceId(dataset)
   addSource(map, dataset, sourceId)
 
@@ -100,14 +140,20 @@ export const addDatasetLayers = (map, dataset, mapStyleId) => {
 
   if (dataset.sublayers?.length) {
     dataset.sublayers.forEach(sublayer => {
-      addSublayerLayers(map, dataset, sublayer, sourceId, sourceLayer, mapStyleId)
+      addSublayerLayers(map, dataset, sublayer, sourceId, sourceLayer, { mapStyle, symbolRegistry, patternRegistry, pixelRatio })
     })
     return sourceId
   }
 
-  const { fillLayerId, strokeLayerId } = getLayerIds(dataset)
+  const { fillLayerId, strokeLayerId, symbolLayerId } = getLayerIds(dataset)
   const visibility = dataset.visibility === 'hidden' ? 'none' : 'visible'
-  addFillLayer(map, dataset, fillLayerId, sourceId, sourceLayer, visibility, mapStyleId)
+
+  if (hasSymbol(dataset) && symbolRegistry) {
+    addSymbolLayer(map, dataset, symbolLayerId, sourceId, sourceLayer, visibility, { mapStyle, symbolRegistry, pixelRatio })
+    return sourceId
+  }
+
+  addFillLayer(map, dataset, fillLayerId, sourceId, sourceLayer, visibility, { mapStyleId, patternRegistry })
   addStrokeLayer(map, dataset, strokeLayerId, sourceId, sourceLayer, visibility, mapStyleId)
   return sourceId
 }

package/plugins/beta/datasets/src/adapters/maplibre/layerIds.js

@@ -1,7 +1,9 @@
-import { hasPattern } from '../../styles/patterns.js'
+import { hasPattern } from '../../../../../../src/utils/patternUtils.js'
 
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 
+const hasSymbol = (dataset) => !!dataset.symbol
+
 export const isDynamicSource = (dataset) =>
   typeof dataset.geojson === 'string' &&
   !!dataset.idProperty &&
@@ -42,28 +44,32 @@ export const getSourceId = (dataset) => {
 // ─── Layer IDs ────────────────────────────────────────────────────────────────
 
 export const getLayerIds = (dataset) => {
-  const hasFill = !!dataset.fill || hasPattern(dataset)
+  if (hasSymbol(dataset)) {
+    return { fillLayerId: null, strokeLayerId: null, symbolLayerId: dataset.id }
+  }
+  const hasFill = (!!dataset.fill && dataset.fill !== 'transparent') || hasPattern(dataset)
   const hasStroke = !!dataset.stroke
   const fillLayerId = hasFill ? dataset.id : null
   let strokeLayerId = null
   if (hasStroke) {
     strokeLayerId = hasFill ? `${dataset.id}-stroke` : dataset.id
   }
-  return { fillLayerId, strokeLayerId }
+  return { fillLayerId, strokeLayerId, symbolLayerId: null }
 }
 
 export const getSublayerLayerIds = (datasetId, sublayerId) => ({
   fillLayerId: `${datasetId}-${sublayerId}`,
-  strokeLayerId: `${datasetId}-${sublayerId}-stroke`
+  strokeLayerId: `${datasetId}-${sublayerId}-stroke`,
+  symbolLayerId: `${datasetId}-${sublayerId}-symbol`
 })
 
 export const getAllLayerIds = (dataset) => {
   if (dataset.sublayers?.length) {
     return dataset.sublayers.flatMap(sublayer => {
-      const { fillLayerId, strokeLayerId } = getSublayerLayerIds(dataset.id, sublayer.id)
-      return [strokeLayerId, fillLayerId]
+      const { fillLayerId, strokeLayerId, symbolLayerId } = getSublayerLayerIds(dataset.id, sublayer.id)
+      return [strokeLayerId, fillLayerId, symbolLayerId]
     })
   }
-  const { fillLayerId, strokeLayerId } = getLayerIds(dataset)
-  return [strokeLayerId, fillLayerId].filter(Boolean)
+  const { fillLayerId, strokeLayerId, symbolLayerId } = getLayerIds(dataset)
+  return [strokeLayerId, fillLayerId, symbolLayerId].filter(Boolean)
 }

package/plugins/beta/datasets/src/adapters/maplibre/maplibreLayerAdapter.js

@@ -1,7 +1,10 @@
 import { applyExclusionFilter } from '../../utils/filters.js'
 import { getSourceId, getLayerIds, getSublayerLayerIds, getAllLayerIds } from './layerIds.js'
 import { addDatasetLayers, addSublayerLayers } from './layerBuilders.js'
-import { registerPatterns } from './patternRegistry.js'
+import { getPatternConfigs } from './patternImages.js'
+import { getSymbolConfigs, getSymbolImageId } from './symbolImages.js'
+import { mergeSublayer } from '../../utils/mergeSublayer.js'
+import { scaleFactor } from '../../../../../../src/config/appConfig.js'
 
 /**
  * MapLibre GL JS implementation of the LayerAdapter interface for the datasets plugin.
@@ -11,12 +14,25 @@ import { registerPatterns } from './patternRegistry.js'
  * - Pattern image registration (delegated to patternRegistry)
  * - Visibility toggling, feature filtering, style changes
  * - Style-change recovery (re-adding layers after basemap swap)
+ *
+ * Symbol image rasterisation is delegated to the map provider via
+ * `mapProvider.registerSymbols()`, keeping this adapter free of provider internals.
  */
 export default class MaplibreLayerAdapter {
-  constructor (map) {
-    this._map = map
+  /**
+   * @param {Object} mapProvider - Map provider instance (e.g. MapLibreProvider)
+   * @param {Object} symbolRegistry
+   * @param {Object} patternRegistry
+   */
+  constructor (mapProvider, symbolRegistry, patternRegistry) {
+    this._mapProvider = mapProvider
+    this._map = mapProvider.map
+    this._symbolRegistry = symbolRegistry
+    this._patternRegistry = patternRegistry
     // datasetId → sourceId, used by setData to update the correct source
     this._datasetSourceMap = new Map()
+    // Tracks all active symbol-type layer IDs so non-symbol layers can be kept below them
+    this._symbolLayerIds = new Set()
   }
 
   // ─── Lifecycle ──────────────────────────────────────────────────────────────
@@ -24,12 +40,18 @@ export default class MaplibreLayerAdapter {
   /**
    * Initialise all datasets: register patterns, add layers, then wait for idle.
    * @param {Object[]} datasets
-   * @param {string} mapStyleId
+   * @param {Object} mapStyle
    * @returns {Promise<void>} Resolves once the map has processed all layers.
    */
-  async init (datasets, mapStyleId) {
-    await registerPatterns(this._map, datasets, mapStyleId)
-    datasets.forEach(dataset => this._addLayers(dataset, mapStyleId))
+  async init (datasets, mapStyle) {
+    const mapStyleId = mapStyle.id
+    const pixelRatio = this._pixelRatio
+    await Promise.all([
+      this._mapProvider.registerPatterns(getPatternConfigs(datasets, this._patternRegistry), mapStyleId, this._patternRegistry),
+      this._mapProvider.registerSymbols(getSymbolConfigs(datasets), mapStyle, this._symbolRegistry)
+    ])
+    this._symbolLayerIds.clear()
+    datasets.forEach(dataset => this._addLayers(dataset, mapStyle, pixelRatio))
     await new Promise(resolve => this._map.once('idle', resolve))
   }
 
@@ -58,17 +80,23 @@ export default class MaplibreLayerAdapter {
    * Re-register patterns and re-add all layers after a basemap style change,
    * then reapply cached dynamic source data and hidden-feature filters.
    * @param {Object[]} datasets
-   * @param {string} newStyleId
+   * @param {Object} newMapStyle
    * @param {Object} hiddenFeatures - pluginState.hiddenFeatures
    * @param {Map} dynamicSources - datasetId → dynamic source instance
    * @returns {Promise<void>}
    */
-  async onStyleChange (datasets, newStyleId, hiddenFeatures, dynamicSources) {
+  async onStyleChange (datasets, newMapStyle, hiddenFeatures, dynamicSources) {
     // MapLibre wipes all sources/layers on style change — must wait for idle first
     await new Promise(resolve => this._map.once('idle', resolve))
 
-    await registerPatterns(this._map, datasets, newStyleId)
-    datasets.forEach(dataset => this._addLayers(dataset, newStyleId))
+    const newStyleId = newMapStyle.id
+    const pixelRatio = this._pixelRatio
+    await Promise.all([
+      this._mapProvider.registerPatterns(getPatternConfigs(datasets, this._patternRegistry), newStyleId, this._patternRegistry),
+      this._mapProvider.registerSymbols(getSymbolConfigs(datasets), newMapStyle, this._symbolRegistry)
+    ])
+    this._symbolLayerIds.clear()
+    datasets.forEach(dataset => this._addLayers(dataset, newMapStyle, pixelRatio))
 
     // Re-push cached data for dynamic sources
     dynamicSources.forEach(source => source.reapply())
@@ -83,15 +111,45 @@ export default class MaplibreLayerAdapter {
     })
   }
 
+  /**
+   * Re-register symbols at the new pixel ratio and update icon-image on all symbol layers.
+   * Called when the map size changes so symbols are rasterised at the correct resolution.
+   * @param {Object[]} datasets
+   * @param {Object} mapStyle
+   * @returns {Promise<void>}
+   */
+  async onSizeChange (datasets, mapStyle) {
+    await this._mapProvider.registerSymbols(getSymbolConfigs(datasets), mapStyle, this._symbolRegistry)
+    const pixelRatio = this._pixelRatio
+    datasets.forEach(dataset => {
+      getAllLayerIds(dataset).forEach(layerId => {
+        if (!this._symbolLayerIds.has(layerId) || !this._map.getLayer(layerId)) { return }
+        const imageId = getSymbolImageId(dataset, mapStyle, this._symbolRegistry, false, pixelRatio)
+        if (imageId) {
+          this._map.setLayoutProperty(layerId, 'icon-image', imageId)
+        }
+      })
+      dataset.sublayers?.forEach(sublayer => {
+        const { symbolLayerId } = getSublayerLayerIds(dataset.id, sublayer.id)
+        if (!this._map.getLayer(symbolLayerId)) { return }
+        const merged = mergeSublayer(dataset, sublayer)
+        const imageId = getSymbolImageId(merged, mapStyle, this._symbolRegistry, false, pixelRatio)
+        if (imageId) {
+          this._map.setLayoutProperty(symbolLayerId, 'icon-image', imageId)
+        }
+      })
+    })
+  }
+
   // ─── Dataset operations ─────────────────────────────────────────────────────
 
   /**
    * Add a single dataset's source and layers to the map.
    * @param {Object} dataset
-   * @param {string} mapStyleId
+   * @param {Object} mapStyle
    */
-  addDataset (dataset, mapStyleId) {
-    this._addLayers(dataset, mapStyleId)
+  addDataset (dataset, mapStyle) {
+    this._addLayers(dataset, mapStyle, this._pixelRatio)
   }
 
   /**
@@ -108,6 +166,7 @@ export default class MaplibreLayerAdapter {
       if (this._map.getLayer(layerId)) {
         this._map.removeLayer(layerId)
       }
+      this._symbolLayerIds.delete(layerId)
     })
 
     const sourceIsShared = allDatasets.some(d => d.id !== dataset.id && getSourceId(d) === sourceId)
@@ -141,13 +200,12 @@ export default class MaplibreLayerAdapter {
    * @param {string} sublayerId
    */
   showSublayer (datasetId, sublayerId) {
-    const { fillLayerId, strokeLayerId } = getSublayerLayerIds(datasetId, sublayerId)
-    if (this._map.getLayer(fillLayerId)) {
-      this._map.setLayoutProperty(fillLayerId, 'visibility', 'visible')
-    }
-    if (this._map.getLayer(strokeLayerId)) {
-      this._map.setLayoutProperty(strokeLayerId, 'visibility', 'visible')
-    }
+    const { fillLayerId, strokeLayerId, symbolLayerId } = getSublayerLayerIds(datasetId, sublayerId)
+    ;[fillLayerId, strokeLayerId, symbolLayerId].forEach(layerId => {
+      if (this._map.getLayer(layerId)) {
+        this._map.setLayoutProperty(layerId, 'visibility', 'visible')
+      }
+    })
   }
 
   /**
@@ -156,13 +214,12 @@ export default class MaplibreLayerAdapter {
    * @param {string} sublayerId
    */
   hideSublayer (datasetId, sublayerId) {
-    const { fillLayerId, strokeLayerId } = getSublayerLayerIds(datasetId, sublayerId)
-    if (this._map.getLayer(fillLayerId)) {
-      this._map.setLayoutProperty(fillLayerId, 'visibility', 'none')
-    }
-    if (this._map.getLayer(strokeLayerId)) {
-      this._map.setLayoutProperty(strokeLayerId, 'visibility', 'none')
-    }
+    const { fillLayerId, strokeLayerId, symbolLayerId } = getSublayerLayerIds(datasetId, sublayerId)
+    ;[fillLayerId, strokeLayerId, symbolLayerId].forEach(layerId => {
+      if (this._map.getLayer(layerId)) {
+        this._map.setLayoutProperty(layerId, 'visibility', 'none')
+      }
+    })
   }
 
   // ─── Feature operations ─────────────────────────────────────────────────────
@@ -190,42 +247,54 @@ export default class MaplibreLayerAdapter {
   /**
    * Update a dataset's style and re-render all its layers.
    * @param {Object} dataset - Updated dataset (style changes already merged in)
-   * @param {string} mapStyleId
+   * @param {Object} mapStyle
    * @returns {Promise<void>}
    */
-  async setStyle (dataset, mapStyleId) {
+  async setStyle (dataset, mapStyle) {
+    const mapStyleId = mapStyle.id
+    const pixelRatio = this._pixelRatio
     getAllLayerIds(dataset).forEach(layerId => {
       if (this._map.getLayer(layerId)) {
         this._map.removeLayer(layerId)
       }
+      this._symbolLayerIds.delete(layerId)
     })
-    await registerPatterns(this._map, [dataset], mapStyleId)
-    this._addLayers(dataset, mapStyleId)
+    await Promise.all([
+      this._mapProvider.registerPatterns(getPatternConfigs([dataset], this._patternRegistry), mapStyleId, this._patternRegistry),
+      this._mapProvider.registerSymbols(getSymbolConfigs([dataset]), mapStyle, this._symbolRegistry)
+    ])
+    this._addLayers(dataset, mapStyle, pixelRatio)
   }
 
   /**
    * Update a single sublayer's style and re-render its layers.
    * @param {Object} dataset - Updated dataset (sublayer style changes already merged in)
    * @param {string} sublayerId
-   * @param {string} mapStyleId
+   * @param {Object} mapStyle
    * @returns {Promise<void>}
    */
-  async setSublayerStyle (dataset, sublayerId, mapStyleId) {
-    const { fillLayerId, strokeLayerId } = getSublayerLayerIds(dataset.id, sublayerId)
-    if (this._map.getLayer(fillLayerId)) {
-      this._map.removeLayer(fillLayerId)
-    }
-    if (this._map.getLayer(strokeLayerId)) {
-      this._map.removeLayer(strokeLayerId)
-    }
+  async setSublayerStyle (dataset, sublayerId, mapStyle) {
+    const mapStyleId = mapStyle.id
+    const pixelRatio = this._pixelRatio
+    const { fillLayerId, strokeLayerId, symbolLayerId } = getSublayerLayerIds(dataset.id, sublayerId)
+    ;[fillLayerId, strokeLayerId, symbolLayerId].forEach(layerId => {
+      if (this._map.getLayer(layerId)) {
+        this._map.removeLayer(layerId)
+      }
+      this._symbolLayerIds.delete(layerId)
+    })
     const sublayer = dataset.sublayers?.find(s => s.id === sublayerId)
     if (!sublayer) {
       return
     }
-    await registerPatterns(this._map, [dataset], mapStyleId)
+    await Promise.all([
+      this._mapProvider.registerPatterns(getPatternConfigs([dataset], this._patternRegistry), mapStyleId, this._patternRegistry),
+      this._mapProvider.registerSymbols(getSymbolConfigs([dataset]), mapStyle, this._symbolRegistry)
+    ])
     const sourceId = this._datasetSourceMap.get(dataset.id)
     const sourceLayer = dataset.tiles?.length ? dataset.sourceLayer : undefined
-    addSublayerLayers(this._map, dataset, sublayer, sourceId, sourceLayer, mapStyleId)
+    addSublayerLayers(this._map, dataset, sublayer, sourceId, sourceLayer, { mapStyle, symbolRegistry: this._symbolRegistry, patternRegistry: this._patternRegistry, pixelRatio })
+    this._maintainSymbolOrdering(dataset)
   }
 
   /**
@@ -275,9 +344,43 @@ export default class MaplibreLayerAdapter {
 
   // ─── Private ─────────────────────────────────────────────────────────────────
 
-  _addLayers (dataset, mapStyleId) {
-    const sourceId = addDatasetLayers(this._map, dataset, mapStyleId)
+  get _pixelRatio () {
+    return this._mapProvider.map.getPixelRatio() * (scaleFactor[this._mapProvider.mapSize] || 1)
+  }
+
+  _addLayers (dataset, mapStyle, pixelRatio) {
+    const sourceId = addDatasetLayers(this._map, dataset, mapStyle, this._symbolRegistry, this._patternRegistry, pixelRatio)
     this._datasetSourceMap.set(dataset.id, sourceId)
+    this._maintainSymbolOrdering(dataset)
+  }
+
+  _getFirstSymbolLayerId () {
+    const style = this._map.getStyle()
+    if (!style?.layers) {
+      return null
+    }
+    const layer = style.layers.find(l => this._symbolLayerIds.has(l.id))
+    return layer?.id ?? null
+  }
+
+  _maintainSymbolOrdering (dataset) {
+    const layerIds = getAllLayerIds(dataset).filter(id => id && this._map.getLayer(id))
+    layerIds.forEach(id => {
+      if (this._map.getLayer(id)?.type === 'symbol') {
+        this._symbolLayerIds.add(id)
+      } else {
+        this._symbolLayerIds.delete(id)
+      }
+    })
+    const firstSymbolId = this._getFirstSymbolLayerId()
+    if (!firstSymbolId) {
+      return
+    }
+    layerIds.forEach(id => {
+      if (!this._symbolLayerIds.has(id)) {
+        this._map.moveLayer(id, firstSymbolId)
+      }
+    })
   }
 
   _setDatasetVisibility (datasetId, visibility) {
@@ -307,14 +410,12 @@ export default class MaplibreLayerAdapter {
       })
       return
     }
-    const { fillLayerId, strokeLayerId } = getLayerIds(dataset)
+    const { fillLayerId, strokeLayerId, symbolLayerId } = getLayerIds(dataset)
     const originalFilter = dataset.filter || null
-    if (fillLayerId) {
-      applyExclusionFilter(this._map, fillLayerId, originalFilter, idProperty, excludeIds)
-    }
-    if (strokeLayerId) {
-      applyExclusionFilter(this._map, strokeLayerId, originalFilter, idProperty, excludeIds)
-    }
+    const layerIds = [fillLayerId, strokeLayerId, symbolLayerId].filter(Boolean)
+    layerIds.forEach(layerId => {
+      applyExclusionFilter(this._map, layerId, originalFilter, idProperty, excludeIds)
+    })
   }
 
   _setPaintOpacity (layerId, opacity) {
@@ -322,7 +423,8 @@ export default class MaplibreLayerAdapter {
     if (!layer) {
       return
     }
-    const prop = layer.type === 'line' ? 'line-opacity' : 'fill-opacity'
+    const opacityProps = { line: 'line-opacity', symbol: 'icon-opacity' }
+    const prop = opacityProps[layer.type] || 'fill-opacity'
     this._map.setPaintProperty(layerId, prop, opacity)
   }
 

package/plugins/beta/datasets/src/adapters/maplibre/patternImages.js

@@ -0,0 +1,27 @@
+// Re-export pure pattern utilities from core — no map engine dependency.
+import { hasPattern } from '../../../../../../src/utils/patternUtils.js'
+import { mergeSublayer } from '../../utils/mergeSublayer.js'
+
+export { hasPattern, getPatternInnerContent, getPatternImageId, getKeyPatternPaths, injectColors } from '../../../../../../src/utils/patternUtils.js'
+
+/**
+ * Returns a flat list of datasets and merged sublayers that require pattern images.
+ * Handles sublayer merging so callers (e.g. mapProvider.registerPatterns) receive ready-to-use configs.
+ *
+ * @param {Object[]} datasets
+ * @param {Object} patternRegistry
+ * @returns {Object[]}
+ */
+export const getPatternConfigs = (datasets, patternRegistry) =>
+  datasets.flatMap(dataset => {
+    const configs = hasPattern(dataset) ? [dataset] : []
+    if (dataset.sublayers?.length) {
+      dataset.sublayers.forEach(sublayer => {
+        const merged = mergeSublayer(dataset, sublayer)
+        if (hasPattern(merged)) {
+          configs.push(merged)
+        }
+      })
+    }
+    return configs
+  })

package/plugins/beta/datasets/src/adapters/maplibre/symbolImages.js

@@ -0,0 +1,31 @@
+// Re-export pure symbol resolution utilities from core — no map engine dependency.
+import { hasSymbol } from '../../../../../../src/utils/symbolUtils.js'
+import { mergeSublayer } from '../../utils/mergeSublayer.js'
+
+export { hasSymbol, getSymbolDef, getSymbolStyleColors, getSymbolViewBox, getSymbolAnchor } from '../../../../../../src/utils/symbolUtils.js'
+
+// Re-export MapLibre-specific symbol utilities from the provider.
+// This is the single cross-boundary import in the adapter; in a separate-package
+// setup this would be: '@interactive-map/maplibre-provider/utils/symbolImages'
+export { anchorToMaplibre, getSymbolImageId } from '../../../../../../providers/maplibre/src/utils/symbolImages.js'
+
+/**
+ * Returns a flat list of datasets and merged sublayers that require symbol images.
+ * Handles sublayer merging so callers (e.g. mapProvider.registerSymbols) receive ready-to-use configs.
+ *
+ * @param {Object[]} datasets
+ * @returns {Object[]}
+ */
+export const getSymbolConfigs = (datasets) =>
+  datasets.flatMap(dataset => {
+    const configs = hasSymbol(dataset) ? [dataset] : []
+    if (dataset.sublayers?.length) {
+      dataset.sublayers.forEach(sublayer => {
+        const merged = mergeSublayer(dataset, sublayer)
+        if (hasSymbol(merged)) {
+          configs.push(merged)
+        }
+      })
+    }
+    return configs
+  })

package/plugins/beta/datasets/src/api/addDataset.js

@@ -1,6 +1,6 @@
 import { datasetDefaults } from '../defaults.js'
 
 export const addDataset = ({ pluginState, mapState }, dataset) => {
-  pluginState.layerAdapter?.addDataset({ ...datasetDefaults, ...dataset }, mapState.mapStyle.id)
+  pluginState.layerAdapter?.addDataset({ ...datasetDefaults, ...dataset }, mapState.mapStyle)
   pluginState.dispatch({ type: 'ADD_DATASET', payload: { dataset, datasetDefaults } })
 }

package/plugins/beta/datasets/src/api/setData.js

@@ -1,7 +1,9 @@
-export const setData = ({ pluginState, services }, geojson, { datasetId }) => {
+import { logger } from '../../../../../src/services/logger.js'
+
+export const setData = ({ pluginState }, geojson, { datasetId }) => {
   const dataset = pluginState.datasets?.find(d => d.id === datasetId)
   if (dataset?.tiles) {
-    services.logger.warn(`setData called on vector tile dataset "${datasetId}" — has no effect`)
+    logger.warn(`setData called on vector tile dataset "${datasetId}" — has no effect`)
     return
   }
   pluginState.layerAdapter?.setData(datasetId, geojson)

package/plugins/beta/datasets/src/api/setStyle.js

@@ -12,11 +12,11 @@ export const setStyle = ({ pluginState, mapState }, style, { datasetId, sublayer
         sublayer.id === sublayerId ? { ...sublayer, style: { ...sublayer.style, ...style } } : sublayer
       )
     }
-    pluginState.layerAdapter?.setSublayerStyle(updatedSublayerDataset, sublayerId, mapState.mapStyle.id)
+    pluginState.layerAdapter?.setSublayerStyle(updatedSublayerDataset, sublayerId, mapState.mapStyle)
     return
   }
 
   pluginState.dispatch({ type: 'SET_DATASET_STYLE', payload: { datasetId, styleChanges: style } })
   const updatedDataset = { ...dataset, ...style }
-  pluginState.layerAdapter?.setStyle(updatedDataset, mapState.mapStyle.id)
+  pluginState.layerAdapter?.setStyle(updatedDataset, mapState.mapStyle)
 }