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

package/providers/maplibre/src/utils/highlightFeatures.test.js

@@ -1,133 +1,190 @@
 import { updateHighlightedFeatures } from './highlightFeatures.js'
 
-describe('Highlighting Utils', () => {
+function lngLatBounds () {
+  this.coords = []
+  this.extend = (c) => this.coords.push(c)
+  this.getWest = () => Math.min(...this.coords.map(c => c[0]))
+  this.getSouth = () => Math.min(...this.coords.map(c => c[1]))
+  this.getEast = () => Math.max(...this.coords.map(c => c[0]))
+  this.getNorth = () => Math.max(...this.coords.map(c => c[1]))
+}
+
+const EMPTY_FILTER = ['==', 'id', '']
+const STALE_SYMBOL_LAYER = 'highlight-stale-symbol'
+
+const makeMap = (overrides = {}) => ({
+  _highlightedSources: new Set(),
+  getLayer: jest.fn(),
+  addLayer: jest.fn(),
+  moveLayer: jest.fn(),
+  setFilter: jest.fn(),
+  setPaintProperty: jest.fn(),
+  setLayoutProperty: jest.fn(),
+  getLayoutProperty: jest.fn(),
+  queryRenderedFeatures: jest.fn().mockReturnValue([]),
+  ...overrides
+})
+
+describe('Highlighting Utils — fill and line', () => {
   let map
-  const LngLatBounds = function () {
-    this.coords = []
-    this.extend = (c) => this.coords.push(c)
-    this.getWest = () => Math.min(...this.coords.map(c => c[0]))
-    this.getSouth = () => Math.min(...this.coords.map(c => c[1]))
-    this.getEast = () => Math.max(...this.coords.map(c => c[0]))
-    this.getNorth = () => Math.max(...this.coords.map(c => c[1]))
-  }
+
+  const ALL_BRANCHES_FEATURES = [
+    { featureId: 1, layerId: 'l1', geometry: { type: 'Polygon' } },
+    { featureId: 2, layerId: 'l1', geometry: { type: 'MultiPolygon' } },
+    { featureId: 3, layerId: 'invalid' },
+    { featureId: 4, layerId: 'l2', idProperty: 'customId', geometry: { type: 'Point' } }
+  ]
+
+  const ALL_BRANCHES_STYLES = { l1: { stroke: 'red', fill: 'blue' }, l2: { stroke: 'green' } }
 
   beforeEach(() => {
-    map = {
-      _highlightedSources: new Set(['stale']),
-      getLayer: jest.fn(),
-      addLayer: jest.fn(),
-      moveLayer: jest.fn(),
-      setFilter: jest.fn(),
-      setPaintProperty: jest.fn(),
-      queryRenderedFeatures: jest.fn()
-    }
+    map = makeMap({ _highlightedSources: new Set(['stale']) })
   })
 
   test('All branches', () => {
-    // Coverage for Line 93: Null map check
     expect(updateHighlightedFeatures({ map: null })).toBeNull()
 
-    map.getLayer.mockImplementation((id) => {
-      if (id.includes('stale')) return true // Coverage for Line 49
-      if (id === 'l1') return { source: 's1', type: 'fill' }
-      if (id === 'l2') return { source: 's2', type: 'line' }
-      if (id === 'highlight-s2-fill') return true // Coverage for Line 124
-      return null // Coverage for Line 13
+    map.getLayer.mockImplementation((id) => { // NOSONAR
+      if (id.includes('stale')) { return {} }
+      if (id === 'l1') { return { source: 's1', type: 'fill' } }
+      if (id === 'l2') { return { source: 's2', type: 'line' } }
+      if (id === 'highlight-s2-fill') { return {} }
+      return null
     })
 
-    const selectedFeatures = [
-      // Coverage for Lines 37-40: Polygon & MultiPolygon checks
-      { featureId: 1, layerId: 'l1', geometry: { type: 'Polygon' } },
-      { featureId: 2, layerId: 'l1', geometry: { type: 'MultiPolygon' } },
-      // Coverage for Line 13: Invalid layer
-      { featureId: 3, layerId: 'invalid' },
-      // Coverage for Line 116: idProperty exists
-      { featureId: 4, layerId: 'l2', idProperty: 'customId', geometry: { type: 'Point' } }
-    ]
-
-    const stylesMap = {
-      l1: { stroke: 'red', fill: 'blue' },
-      l2: { stroke: 'green' }
-    }
-
-    // Coverage for Lines 78-80: Recursive coordinate handling (numbers vs arrays)
+    const coordMax = 10
+    const coordMid = 5
     map.queryRenderedFeatures.mockReturnValue([
-      { id: 1, geometry: { coordinates: [10, 10] } }, // Simple point
-      { id: 2, properties: { customId: 4 }, geometry: { coordinates: [[0, 0], [5, 5]] } } // Nested
+      { id: 1, geometry: { coordinates: [coordMax, coordMax] } },
+      { id: 2, properties: { customId: 4 }, geometry: { coordinates: [[0, 0], [coordMid, coordMid]] } }
     ])
 
-    const bounds = updateHighlightedFeatures({ LngLatBounds, map, selectedFeatures, stylesMap })
-
-    // Line 13 verify: map.getLayer returned null and function returned early
-    // Line 49-50 verify: Stale sources filtered out
-    expect(map.setFilter).toHaveBeenCalledWith('highlight-stale-fill', ['==', 'id', ''])
+    const bounds = updateHighlightedFeatures({ LngLatBounds: lngLatBounds, map, selectedFeatures: ALL_BRANCHES_FEATURES, stylesMap: ALL_BRANCHES_STYLES })
 
-    // Line 124 verify: Clear fill highlight when switching to line geometry
-    expect(map.setFilter).toHaveBeenCalledWith('highlight-s2-fill', ['==', 'id', ''])
-
-    // Line 116 verify: Using ['get', idProperty]
+    expect(map.setFilter).toHaveBeenCalledWith('highlight-stale-fill', EMPTY_FILTER)
+    expect(map.setFilter).toHaveBeenCalledWith(STALE_SYMBOL_LAYER, EMPTY_FILTER)
+    expect(map.setFilter).toHaveBeenCalledWith('highlight-s2-fill', EMPTY_FILTER)
     expect(map.setFilter).toHaveBeenCalledWith('highlight-s2-line', expect.arrayContaining([['get', 'customId']]))
-
-    // Line 80-82 verify: Recursive LngLatBounds logic
     expect(bounds).toEqual([0, 0, 10, 10])
   })
 
-  test('undefined _highlightedSources falls back to empty set; line geom skips absent fill layer', () => {
-    // line 93: || new Set() fallback; line 124 false: no pre-existing fill to clear
-    map._highlightedSources = undefined
-    map.getLayer.mockImplementation(id => id === 'l1' ? { source: 's1', type: 'line' } : null)
-    map.queryRenderedFeatures.mockReturnValue([])
-    updateHighlightedFeatures({
-      LngLatBounds,
-      map,
-      selectedFeatures: [{ featureId: 1, layerId: 'l1' }],
-      stylesMap: { l1: { stroke: 'red' } }
-    })
+  test('null _highlightedSources falls back to empty set; line geom skips absent fill layer', () => {
+    map._highlightedSources = null
+    map.getLayer.mockImplementation(id => id === 'l1' ? { source: 's1', type: 'line' } : null) // NOSONAR
+    updateHighlightedFeatures({ LngLatBounds: lngLatBounds, map, selectedFeatures: [{ featureId: 1, layerId: 'l1' }], stylesMap: { l1: { stroke: 'red' } } })
     expect(map.setFilter).not.toHaveBeenCalledWith('highlight-s1-fill', expect.anything())
   })
 
   test('persistent source skips cleanup; missing stale layers skip setFilter', () => {
-    // line 37 false: src IS in currentSources; line 41 false: getLayer returns null for stale layers
     map._highlightedSources = new Set(['stale', 's1'])
-    map.getLayer.mockImplementation(id => id === 'l1' ? { source: 's1', type: 'line' } : null)
-    map.queryRenderedFeatures.mockReturnValue([])
-    updateHighlightedFeatures({
-      LngLatBounds,
-      map,
-      selectedFeatures: [{ featureId: 1, layerId: 'l1' }],
-      stylesMap: { l1: { stroke: 'red' } }
-    })
+    map.getLayer.mockImplementation(id => id === 'l1' ? { source: 's1', type: 'line' } : null) // NOSONAR
+    updateHighlightedFeatures({ LngLatBounds: lngLatBounds, map, selectedFeatures: [{ featureId: 1, layerId: 'l1' }], stylesMap: { l1: { stroke: 'red' } } })
     expect(map.setFilter).not.toHaveBeenCalledWith(expect.stringContaining('stale'), expect.anything())
   })
+})
+
+describe('Highlighting Utils — layer management', () => {
+  let map
+
+  beforeEach(() => {
+    map = makeMap({ _highlightedSources: new Set(['stale']) })
+  })
 
   test('reuses existing highlight layer; new layer spreads sourceLayer', () => {
-    // line 50 false: getLayer truthy → skip addLayer for s1
-    // line 55: srcLayer truthy → 'source-layer' spread in addLayer for s2
-    map.getLayer.mockImplementation(id => {
-      if (id === 'l1') return { source: 's1', type: 'line' }
-      if (id === 'l2') return { source: 's2', type: 'line', sourceLayer: 'tiles' }
-      if (id === 'highlight-s1-line') return true
+    map.getLayer.mockImplementation(id => { // NOSONAR
+      if (id === 'l1') { return { source: 's1', type: 'line' } }
+      if (id === 'l2') { return { source: 's2', type: 'line', sourceLayer: 'tiles' } }
+      if (id === 'highlight-s1-line') { return {} }
       return null
     })
-    map.queryRenderedFeatures.mockReturnValue([])
-    updateHighlightedFeatures({
-      LngLatBounds,
-      map,
-      selectedFeatures: [
-        { featureId: 1, layerId: 'l1' },
-        { featureId: 2, layerId: 'l2' }
-      ],
-      stylesMap: { l1: { stroke: 'blue' }, l2: { stroke: 'green' } }
-    })
+    updateHighlightedFeatures({ LngLatBounds: lngLatBounds, map, selectedFeatures: [{ featureId: 1, layerId: 'l1' }, { featureId: 2, layerId: 'l2' }], stylesMap: { l1: { stroke: 'blue' }, l2: { stroke: 'green' } } })
     expect(map.addLayer).toHaveBeenCalledTimes(1)
     expect(map.addLayer).toHaveBeenCalledWith(expect.objectContaining({ 'source-layer': 'tiles' }))
   })
 
-  test('Empty features coverage', () => {
-    // Coverage for Line 72: empty renderedFeatures
-    map.getLayer.mockReturnValue({ source: 's1', type: 'line' })
-    map.queryRenderedFeatures.mockReturnValue([])
-    const res = updateHighlightedFeatures({ LngLatBounds, map, selectedFeatures: [], stylesMap: {} })
-    expect(res).toBeNull()
+  test('returns null when no rendered features match', () => {
+    expect(updateHighlightedFeatures({ LngLatBounds: lngLatBounds, map, selectedFeatures: [], stylesMap: {} })).toBeNull()
+  })
+})
+
+describe('Highlighting Utils — symbol layers', () => {
+  const SYMBOL_IMAGE = 'symbol-abc123'
+  const SELECTED_IMAGE = 'symbol-sel-abc123'
+  const HIGHLIGHT_LAYER = 'highlight-s1-symbol'
+  const ICON_IMAGE = 'icon-image'
+  const ICON_ANCHOR = 'icon-anchor'
+  const POINT_FEATURE = { featureId: 1, layerId: 'l1', geometry: { type: 'Point' } }
+
+  let map
+
+  beforeEach(() => {
+    map = makeMap()
+    map._symbolImageMap = { [SYMBOL_IMAGE]: SELECTED_IMAGE }
+    map.getLayer.mockImplementation(id => id === 'l1' ? { source: 's1', type: 'symbol' } : null) // NOSONAR
+    map.getLayoutProperty.mockReturnValue(SYMBOL_IMAGE)
+  })
+
+  const run = (selectedFeatures = [POINT_FEATURE]) =>
+    updateHighlightedFeatures({ LngLatBounds: lngLatBounds, map, selectedFeatures, stylesMap: { l1: {} } })
+
+  test('creates symbol highlight layer with selected image variant', () => {
+    run()
+    expect(map.addLayer).toHaveBeenCalledWith(expect.objectContaining({
+      id: HIGHLIGHT_LAYER,
+      type: 'symbol',
+      layout: expect.objectContaining({ [ICON_IMAGE]: SELECTED_IMAGE })
+    }))
+    expect(map.setLayoutProperty).toHaveBeenCalledWith(HIGHLIGHT_LAYER, ICON_IMAGE, SELECTED_IMAGE)
+  })
+
+  test('reads icon-anchor from original layer', () => {
+    map.getLayoutProperty.mockImplementation((_id, prop) => { // NOSONAR
+      if (prop === ICON_IMAGE) { return SYMBOL_IMAGE }
+      if (prop === ICON_ANCHOR) { return 'bottom' }
+      return null
+    })
+    run()
+    expect(map.addLayer).toHaveBeenCalledWith(expect.objectContaining({
+      layout: expect.objectContaining({ [ICON_ANCHOR]: 'bottom' })
+    }))
+  })
+
+  test('falls back to center anchor when icon-anchor is not set on original layer', () => {
+    map.getLayoutProperty.mockImplementation((_id, prop) => prop === ICON_IMAGE ? SYMBOL_IMAGE : null) // NOSONAR
+    run()
+    expect(map.addLayer).toHaveBeenCalledWith(expect.objectContaining({
+      layout: expect.objectContaining({ [ICON_ANCHOR]: 'center' })
+    }))
+  })
+
+  test('spreads source-layer into symbol highlight layer for vector tile source', () => {
+    map.getLayer.mockImplementation(id => id === 'l1' ? { source: 's1', type: 'symbol', sourceLayer: 'points' } : null) // NOSONAR
+    run()
+    expect(map.addLayer).toHaveBeenCalledWith(expect.objectContaining({ 'source-layer': 'points' }))
+  })
+
+  test('reuses existing symbol highlight layer without re-adding', () => {
+    map.getLayer.mockImplementation(id => { // NOSONAR
+      if (id === 'l1') { return { source: 's1', type: 'symbol' } }
+      if (id === HIGHLIGHT_LAYER) { return { source: 's1', type: 'symbol' } }
+      return null
+    })
+    run()
+    expect(map.addLayer).not.toHaveBeenCalled()
+    expect(map.setLayoutProperty).toHaveBeenCalledWith(HIGHLIGHT_LAYER, ICON_IMAGE, SELECTED_IMAGE)
+  })
+
+  test('skips highlight when icon-image has no entry in _symbolImageMap', () => {
+    map.getLayoutProperty.mockReturnValue('symbol-abc123')
+    map._symbolImageMap = {} // no mapping registered
+    run()
+    expect(map.addLayer).not.toHaveBeenCalled()
+  })
+
+  test('cleans up stale symbol highlight layer', () => {
+    map._highlightedSources = new Set(['stale'])
+    map.getLayer.mockImplementation(id => id === STALE_SYMBOL_LAYER ? { type: 'symbol' } : null) // NOSONAR
+    run([])
+    expect(map.setFilter).toHaveBeenCalledWith(STALE_SYMBOL_LAYER, EMPTY_FILTER)
   })
 })

package/providers/maplibre/src/utils/hoverCursor.js

@@ -0,0 +1,61 @@
+/**
+ * Attaches a mousemove listener that changes the map cursor to a pointer when
+ * hovering over any of the specified layers.
+ *
+ * Line layers use a 10px tolerance bbox. Stroke layers that have a companion
+ * fill layer are skipped — the fill handles hover. Fill and symbol layers use
+ * exact point hit-testing.
+ *
+ * @param {Object} map - MapLibre map instance
+ * @param {string[]} layerIds - Layer IDs to watch
+ * @param {Function|null} prevHandler - Previous mousemove handler to remove
+ * @returns {Function|null} The new handler, or null if layerIds is empty
+ */
+const splitLayers = (map, layerIds) => {
+  const lineLayers = []
+  const otherLayers = []
+  for (const id of layerIds) {
+    const type = map.getLayer(id).type
+    if (type === 'line') {
+      const fillId = id.endsWith('-stroke') ? id.slice(0, -7) : null // NOSONAR
+      const hasFillCompanion = fillId !== null && layerIds.includes(fillId)
+      if (!hasFillCompanion) {
+        lineLayers.push(id)
+      }
+    } else {
+      otherLayers.push(id)
+    }
+  }
+  return { lineLayers, otherLayers }
+}
+
+export const setupHoverCursor = (map, layerIds, prevHandler) => {
+  const canvas = map.getCanvas()
+
+  if (prevHandler) {
+    map.off('mousemove', prevHandler)
+  }
+
+  if (!layerIds?.length) {
+    canvas.style.cursor = ''
+    return null
+  }
+
+  const handler = (e) => {
+    const existingLayers = layerIds.filter(id => map.getLayer(id))
+    if (existingLayers.length === 0) {
+      canvas.style.cursor = ''
+      return
+    }
+
+    const { lineLayers, otherLayers } = splitLayers(map, existingLayers)
+    const { x, y } = e.point
+    const bbox = [[x - 10, y - 10], [x + 10, y + 10]]
+    const lineHit = lineLayers.length > 0 && map.queryRenderedFeatures(bbox, { layers: lineLayers }).length > 0
+    const otherHit = otherLayers.length > 0 && map.queryRenderedFeatures(e.point, { layers: otherLayers }).length > 0
+    canvas.style.cursor = (lineHit || otherHit) ? 'pointer' : ''
+  }
+
+  map.on('mousemove', handler)
+  return handler
+}

package/providers/maplibre/src/utils/hoverCursor.test.js

@@ -0,0 +1,130 @@
+import { setupHoverCursor } from './hoverCursor.js'
+
+const makeMap = (layerTypes = {}, queryResults = []) => ({
+  getCanvas: () => ({ style: { cursor: '' } }),
+  getLayer: (id) => layerTypes[id] ? { type: layerTypes[id] } : undefined,
+  queryRenderedFeatures: jest.fn(() => queryResults),
+  on: jest.fn(),
+  off: jest.fn()
+})
+
+const move = (handler, x = 10, y = 10) =>
+  handler({ point: { x, y } })
+
+describe('setupHoverCursor', () => {
+  /* ------------------------------------------------------------------ */
+  /* Setup / teardown                                                   */
+  /* ------------------------------------------------------------------ */
+
+  it('returns null and clears cursor when layerIds is empty', () => {
+    const map = makeMap()
+    const result = setupHoverCursor(map, [], null)
+    expect(result).toBeNull()
+    expect(map.getCanvas().style.cursor).toBe('')
+    expect(map.on).not.toHaveBeenCalled()
+  })
+
+  it('returns null and clears cursor when layerIds is null', () => {
+    const map = makeMap()
+    const result = setupHoverCursor(map, null, null)
+    expect(result).toBeNull()
+    expect(map.getCanvas().style.cursor).toBe('')
+  })
+
+  it('removes previous handler before attaching a new one', () => {
+    const map = makeMap({ 'layer-a': 'fill' })
+    const prev = jest.fn()
+    setupHoverCursor(map, ['layer-a'], prev)
+    expect(map.off).toHaveBeenCalledWith('mousemove', prev)
+  })
+
+  it('removes previous handler when clearing layers', () => {
+    const map = makeMap()
+    const prev = jest.fn()
+    setupHoverCursor(map, [], prev)
+    expect(map.off).toHaveBeenCalledWith('mousemove', prev)
+  })
+
+  it('attaches a mousemove listener and returns the handler', () => {
+    const map = makeMap({ 'layer-a': 'fill' })
+    const handler = setupHoverCursor(map, ['layer-a'], null)
+    expect(typeof handler).toBe('function')
+    expect(map.on).toHaveBeenCalledWith('mousemove', handler)
+  })
+
+  /* ------------------------------------------------------------------ */
+  /* Mousemove — cursor state                                           */
+  /* ------------------------------------------------------------------ */
+
+  it('sets pointer cursor when a fill layer is hit', () => {
+    const canvas = { style: { cursor: '' } }
+    const map = { ...makeMap({ 'fill-layer': 'fill' }, [{ id: 'f1' }]), getCanvas: () => canvas }
+    const handler = setupHoverCursor(map, ['fill-layer'], null)
+    move(handler)
+    expect(canvas.style.cursor).toBe('pointer')
+  })
+
+  it('clears cursor when no layers are hit', () => {
+    const canvas = { style: { cursor: 'pointer' } }
+    const map = { ...makeMap({ 'fill-layer': 'fill' }, []), getCanvas: () => canvas }
+    const handler = setupHoverCursor(map, ['fill-layer'], null)
+    move(handler)
+    expect(canvas.style.cursor).toBe('')
+  })
+
+  it('clears cursor when no registered layers exist on the map', () => {
+    const canvas = { style: { cursor: 'pointer' } }
+    const map = { ...makeMap({}, []), getCanvas: () => canvas }
+    const handler = setupHoverCursor(map, ['missing-layer'], null)
+    move(handler)
+    expect(canvas.style.cursor).toBe('')
+  })
+
+  /* ------------------------------------------------------------------ */
+  /* Line layer tolerance                                               */
+  /* ------------------------------------------------------------------ */
+
+  it('uses bbox query for a pure line layer', () => {
+    const map = makeMap({ hedge: 'line' }, [{ id: 'f1' }])
+    const handler = setupHoverCursor(map, ['hedge'], null)
+    move(handler, 50, 50)
+    expect(map.queryRenderedFeatures).toHaveBeenCalledWith(
+      [[40, 40], [60, 60]],
+      { layers: ['hedge'] }
+    )
+  })
+
+  it('sets pointer when line layer is hit via bbox', () => {
+    const canvas = { style: { cursor: '' } }
+    const map = { ...makeMap({ hedge: 'line' }, [{ id: 'f1' }]), getCanvas: () => canvas }
+    const handler = setupHoverCursor(map, ['hedge'], null)
+    move(handler)
+    expect(canvas.style.cursor).toBe('pointer')
+  })
+
+  /* ------------------------------------------------------------------ */
+  /* Stroke + fill companion                                            */
+  /* ------------------------------------------------------------------ */
+
+  it('skips stroke layer when a companion fill layer exists', () => {
+    const map = makeMap({ poly: 'fill', 'poly-stroke': 'line' }, [])
+    const handler = setupHoverCursor(map, ['poly', 'poly-stroke'], null)
+    move(handler)
+    // Only the fill layer should be queried (exact point), not the stroke
+    expect(map.queryRenderedFeatures).toHaveBeenCalledTimes(1)
+    expect(map.queryRenderedFeatures).toHaveBeenCalledWith(
+      expect.objectContaining({ x: 10, y: 10 }),
+      { layers: ['poly'] }
+    )
+  })
+
+  it('does not skip a stroke layer that has no companion fill', () => {
+    const map = makeMap({ 'hedge-stroke': 'line' }, [])
+    const handler = setupHoverCursor(map, ['hedge-stroke'], null)
+    move(handler)
+    expect(map.queryRenderedFeatures).toHaveBeenCalledWith(
+      expect.any(Array),
+      { layers: ['hedge-stroke'] }
+    )
+  })
+})

package/providers/maplibre/src/utils/patternImages.js

@@ -0,0 +1,70 @@
+import { getPatternInnerContent, getPatternImageId, injectColors } from '../../../../src/utils/patternUtils.js'
+import { getValueForStyle } from '../../../../src/utils/getValueForStyle.js'
+import { rasteriseToImageData } from './rasteriseToImageData.js'
+
+// Module-level cache: imageId → ImageData. Avoids re-rasterising identical patterns.
+const imageDataCache = new Map()
+
+/**
+ * Rasterises a dataset's pattern SVG to ImageData, using an in-memory cache
+ * to avoid re-rasterising identical patterns.
+ *
+ * @param {Object} dataset
+ * @param {string} mapStyleId
+ * @param {Object} patternRegistry
+ * @returns {Promise<{ imageId: string, imageData: ImageData }|null>}
+ */
+const rasterisePattern = async (dataset, mapStyleId, patternRegistry) => {
+  const innerContent = getPatternInnerContent(dataset, patternRegistry)
+  if (!innerContent) {
+    return null
+  }
+
+  const imageId = getPatternImageId(dataset, mapStyleId, patternRegistry)
+  if (!imageId) {
+    return null
+  }
+
+  let imageData = imageDataCache.get(imageId)
+  if (!imageData) {
+    const fg = getValueForStyle(dataset.fillPatternForegroundColor, mapStyleId) || 'black'
+    const bg = getValueForStyle(dataset.fillPatternBackgroundColor, mapStyleId) || 'transparent'
+    const colored = injectColors(innerContent, fg, bg)
+    const bgRect = `<rect width="16" height="16" fill="${bg}"/>`
+    // pixelRatio: 2 means the map treats this as an 8×8 logical tile — crisp on retina screens.
+    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">${bgRect}${colored}</svg>`
+    imageData = await rasteriseToImageData(svgString, 16, 16)
+    imageDataCache.set(imageId, imageData)
+  }
+
+  return { imageId, imageData }
+}
+
+/**
+ * Register pattern images for the given pre-resolved pattern configs.
+ * Skips images that are already registered (safe to call on style change).
+ * Callers are responsible for sublayer merging before passing configs here
+ * (see `getPatternConfigs` in the datasets plugin adapter).
+ *
+ * @param {Object} map - MapLibre map instance
+ * @param {Object[]} patternConfigs - Flat list of datasets/merged-sublayers with a pattern config
+ * @param {string} mapStyleId
+ * @param {Object} patternRegistry
+ * @returns {Promise<void>}
+ */
+export const registerPatterns = async (map, patternConfigs, mapStyleId, patternRegistry) => {
+  if (!patternConfigs.length) {
+    return
+  }
+
+  await Promise.all(patternConfigs.map(async (config) => {
+    const imageId = getPatternImageId(config, mapStyleId, patternRegistry)
+    if (!imageId || map.hasImage(imageId)) {
+      return
+    }
+    const result = await rasterisePattern(config, mapStyleId, patternRegistry)
+    if (result) {
+      map.addImage(result.imageId, result.imageData, { pixelRatio: 2 })
+    }
+  }))
+}