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

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

@@ -0,0 +1,180 @@
+import { registerPatterns } from './patternImages.js'
+
+const OUTDOOR = 'outdoor'
+
+const SVG_CONTENT = '<path d="M0 0 L8 8"/>'
+
+beforeAll(() => {
+  globalThis.URL.createObjectURL = jest.fn(() => 'blob:mock')
+  globalThis.URL.revokeObjectURL = jest.fn()
+
+  HTMLCanvasElement.prototype.getContext = jest.fn(() => ({
+    drawImage: jest.fn(),
+    getImageData: jest.fn((_x, _y, w, h) => ({ width: w, height: h }))
+  }))
+
+  globalThis.Image = class {
+    constructor (w, h) {
+      this.width = w
+      this.height = h
+      this._src = ''
+    }
+
+    get src () { return this._src }
+    set src (val) { this._src = val; this.onload?.() }
+  }
+})
+
+const makeMap = (existingIds = []) => ({
+  hasImage: jest.fn((id) => existingIds.includes(id)),
+  addImage: jest.fn()
+})
+
+const makePatternRegistry = (id = 'stripes', content = SVG_CONTENT) => ({
+  get: jest.fn((name) => name === id ? { svgContent: content } : undefined)
+})
+
+// ─── registerPatterns ─────────────────────────────────────────────────────────
+
+describe('registerPatterns — registration', () => {
+  it('returns early and does not touch map for empty configs', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    await registerPatterns(map, [], OUTDOOR, registry)
+    expect(map.hasImage).not.toHaveBeenCalled()
+    expect(map.addImage).not.toHaveBeenCalled()
+  })
+
+  it('calls addImage with pixelRatio 2 for a named pattern', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    const config = { fillPattern: 'stripes' }
+    await registerPatterns(map, [config], OUTDOOR, registry)
+    expect(map.addImage).toHaveBeenCalledTimes(1)
+    expect(map.addImage).toHaveBeenCalledWith(
+      expect.stringMatching(/^pattern-[a-z0-9]+$/),
+      expect.any(Object),
+      { pixelRatio: 2 }
+    )
+  })
+
+  it('calls addImage for an inline fillPatternSvgContent config', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    const config = { fillPatternSvgContent: SVG_CONTENT }
+    await registerPatterns(map, [config], OUTDOOR, registry)
+    expect(map.addImage).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips addImage when image is already registered', async () => {
+    const registry = makePatternRegistry()
+    const config = { fillPattern: 'stripes' }
+    const { getPatternImageId } = await import('../../../../src/utils/patternUtils.js')
+    const existingId = getPatternImageId(config, OUTDOOR, registry)
+    const map = makeMap([existingId])
+    await registerPatterns(map, [config], OUTDOOR, registry)
+    expect(map.addImage).not.toHaveBeenCalled()
+  })
+
+  it('skips config when pattern has no inner content', async () => {
+    const map = makeMap()
+    const emptyRegistry = { get: jest.fn(() => undefined) }
+    await registerPatterns(map, [{ fillPattern: 'unknown' }], OUTDOOR, emptyRegistry)
+    expect(map.addImage).not.toHaveBeenCalled()
+  })
+
+  it('skips config when neither fillPattern nor fillPatternSvgContent is set', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    await registerPatterns(map, [{ fillColor: '#ff0000' }], OUTDOOR, registry)
+    expect(map.addImage).not.toHaveBeenCalled()
+  })
+
+  it('processes multiple configs in parallel', async () => {
+    const map = makeMap()
+    const registry = {
+      get: jest.fn((name) => {
+        if (name === 'stripes') { return { svgContent: '<path d="M0 0"/>' } }
+        if (name === 'dots') { return { svgContent: '<circle cx="8" cy="8" r="4"/>' } }
+        return undefined
+      })
+    }
+    await registerPatterns(map, [{ fillPattern: 'stripes' }, { fillPattern: 'dots' }], OUTDOOR, registry)
+    expect(map.addImage).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('registerPatterns — color resolution and caching', () => {
+  it('applies foreground and background colors when resolving the SVG', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    const getContextSpy = HTMLCanvasElement.prototype.getContext
+    await registerPatterns(
+      map,
+      [{ fillPattern: 'stripes', fillPatternForegroundColor: '#aabbcc', fillPatternBackgroundColor: '#112233' }],
+      OUTDOOR,
+      registry
+    )
+    expect(map.addImage).toHaveBeenCalledTimes(1)
+    expect(getContextSpy).toHaveBeenCalled()
+  })
+
+  it('resolves style-keyed foreground color for the given mapStyleId', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    const config = {
+      fillPattern: 'stripes',
+      fillPatternForegroundColor: { outdoor: '#aabbcc', dark: '#112233' }
+    }
+    await registerPatterns(map, [config], OUTDOOR, registry)
+    const map2 = makeMap()
+    await registerPatterns(map2, [config], 'dark', registry)
+    const [idOutdoor] = map.addImage.mock.calls[0]
+    const [idDark] = map2.addImage.mock.calls[0]
+    expect(idOutdoor).not.toBe(idDark)
+  })
+
+  it('uses cached ImageData on second call with identical config', async () => {
+    const map = makeMap()
+    const registry = makePatternRegistry()
+    const config = { fillPattern: 'stripes', fillPatternForegroundColor: '#unique1' }
+    await registerPatterns(map, [config], OUTDOOR, registry)
+    const { getPatternImageId } = await import('../../../../src/utils/patternUtils.js')
+    const imageId = getPatternImageId(config, OUTDOOR, registry)
+    const map2 = makeMap([imageId])
+    await registerPatterns(map2, [config], OUTDOOR, registry)
+    expect(map2.addImage).not.toHaveBeenCalled()
+  })
+})
+
+describe('registerPatterns — null results', () => {
+  it('does not call addImage when innerContent becomes unavailable inside rasterisePattern', async () => {
+    // registry.get returns content on the first call (for getPatternImageId in registerPatterns)
+    // but undefined on the second call (for getPatternInnerContent inside rasterisePattern)
+    const registry = {
+      get: jest.fn()
+        .mockReturnValueOnce({ svgContent: SVG_CONTENT })
+        .mockReturnValueOnce(undefined)
+    }
+    const map = makeMap()
+    await registerPatterns(map, [{ fillPattern: 'stripes' }], OUTDOOR, registry)
+    expect(map.addImage).not.toHaveBeenCalled()
+  })
+
+  it('does not call addImage when imageId becomes unavailable inside rasterisePattern', async () => {
+    // Three consecutive calls to registry.get:
+    //   1. getPatternImageId in registerPatterns → returns content → imageId is truthy
+    //   2. getPatternInnerContent directly in rasterisePattern → returns content → passes innerContent guard
+    //   3. getPatternInnerContent inside getPatternImageId in rasterisePattern → returns undefined
+    //      → getPatternImageId returns null → hits the imageId null guard
+    const registry = {
+      get: jest.fn()
+        .mockReturnValueOnce({ svgContent: SVG_CONTENT })
+        .mockReturnValueOnce({ svgContent: SVG_CONTENT })
+        .mockReturnValueOnce(undefined)
+    }
+    const map = makeMap()
+    await registerPatterns(map, [{ fillPattern: 'stripes' }], OUTDOOR, registry)
+    expect(map.addImage).not.toHaveBeenCalled()
+  })
+})

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

@@ -83,12 +83,23 @@ const getMinDistToGeometry = (map, point, geometry) => {
  */
 export const queryFeatures = (map, point, options = {}) => {
   const { radius = 10 } = options
-  const queryArea = [[point.x - radius, point.y - radius], [point.x + radius, point.y + radius]]
-  const rawFeatures = map.queryRenderedFeatures(queryArea)
+
+  const bbox = [[point.x - radius, point.y - radius], [point.x + radius, point.y + radius]]
+  const rawFeatures = map.queryRenderedFeatures(bbox)
   if (rawFeatures.length === 0) {
     return []
   }
 
+  // For symbol/point features, tolerance must not apply — selection should only
+  // fire when the click lands within the rendered icon bounds. An exact point
+  // query uses MapLibre's own icon hit-testing, mirroring the hover cursor behaviour.
+  const exactFeatureKeys = new Set(
+    map.queryRenderedFeatures([point.x, point.y]).map(f => {
+      const rawId = f.id === undefined ? JSON.stringify(f.properties) : f.id
+      return `${f.layer?.source}:${rawId}`
+    })
+  )
+
   // Identify layer visual hierarchy
   const layerStack = []
   rawFeatures.forEach(f => {
@@ -97,12 +108,15 @@ export const queryFeatures = (map, point, options = {}) => {
     }
   })
 
-  // Deduplicate Bottom-Up to favor data layers over highlight layers
+  // Deduplicate Bottom-Up to favor data layers over highlight layers.
+  // Key includes source ID to prevent collisions between features from different
+  // sources that share the same numeric ID (e.g. generateId: true resets per source).
   const seenIds = new Set()
   const uniqueFeatures = []
   for (let i = rawFeatures.length - 1; i >= 0; i--) {
     const f = rawFeatures[i]
-    const featureId = f.id === undefined ? JSON.stringify(f.properties) : f.id
+    const rawId = f.id === undefined ? JSON.stringify(f.properties) : f.id
+    const featureId = `${f.layer?.source}:${rawId}`
     if (seenIds.has(featureId) === false) {
       seenIds.add(featureId)
       uniqueFeatures.push(f)
@@ -112,7 +126,24 @@ export const queryFeatures = (map, point, options = {}) => {
   const clickLngLat = map.unproject(point)
   const clickPt = [clickLngLat.lng, clickLngLat.lat]
 
-  return uniqueFeatures
+  // Discard features where tolerance should not apply:
+  // - Polygons: only include if click is geometrically inside
+  // - Points/symbols: only include if under the exact click point (respects icon bounds)
+  // - Lines: allowed through — tolerance bbox is intentional for them
+  const candidates = uniqueFeatures.filter((f) => {
+    const type = f.geometry.type
+    if (type.includes('Polygon')) {
+      const polys = type === 'Polygon' ? [f.geometry.coordinates] : f.geometry.coordinates
+      return polys.some((ring) => isPointInPolygon(clickPt, ring[0]))
+    }
+    if (type === 'Point' || type === 'MultiPoint') {
+      const rawId = f.id === undefined ? JSON.stringify(f.properties) : f.id
+      return exactFeatureKeys.has(`${f.layer?.source}:${rawId}`)
+    }
+    return true
+  })
+
+  return candidates
     .map((f) => {
       let score = 0
       const type = f.geometry.type
@@ -122,18 +153,9 @@ export const queryFeatures = (map, point, options = {}) => {
       const layerRank = layerStack.indexOf(f.layer.id)
       score += (layerRank * 1000000)
 
-      // PRIORITY 2: CONTAINMENT (Polygon Special Treatment)
+      // PRIORITY 2: POLYGON BOOST (already filtered to inside-only)
       if (type.includes('Polygon')) {
-        const polys = type === 'Polygon' ? [f.geometry.coordinates] : f.geometry.coordinates
-        const isInside = polys.some((ring) => isPointInPolygon(clickPt, ring[0]))
-
-        if (isInside === true) {
-          // Massive boost for polygons if we are actually inside them
-          score -= 500000 // NOSONAR - tolerance used only here
-        } else {
-          // If we are outside a polygon, it loses significantly to anything we ARE inside
-          score += 100000 // NOSONAR - tolerance used only here
-        }
+        score -= 500000 // NOSONAR
       }
 
       // PRIORITY 3: DISTANCE (Final Tie-breaker)

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

@@ -20,7 +20,7 @@ describe('queryFeatures coverage', () => {
       { type: 'MultiPoint', coords: [[0, 0], [10, 10]], p: { x: 1, y: 0 } },
       { type: 'MultiLineString', coords: [[[0, 0], [10, 0]]], p: { x: 5, y: 1 } },
       { type: 'Polygon', coords: [[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]], p: { x: 5, y: 5 } }, // Inside
-      { type: 'MultiPolygon', coords: [[[[0, 0], [10, 0], [10, 10], [0, 0]]]], p: { x: 20, y: 20 } }, // Outside
+      { type: 'MultiPolygon', coords: [[[[0, 0], [10, 0], [10, 10], [0, 0]]]], p: { x: 5, y: 3 } }, // Inside
       { type: 'Unknown', coords: [], p: { x: 0, y: 0 } }
     ]
 
@@ -49,12 +49,29 @@ describe('queryFeatures coverage', () => {
     expect(result.length).toBe(2)
     expect(result[0].layer.id).toBe('layer-A') // Sorted by layerStack index
 
-    // 4. Hit ray-casting intersect logic (Line 42 branch)
+    // 4. Hit ray-casting intersect logic — point inside the polygon
     const polyFeat = {
       layer: { id: 'L' },
       geometry: { type: 'Polygon', coordinates: [[[0, 0], [10, 10], [0, 10], [0, 0]]] }
     }
     const rayMap = { ...mockMap, queryRenderedFeatures: () => [polyFeat] }
-    expect(queryFeatures(rayMap, { x: -1, y: 5 }).length).toBe(1)
+    expect(queryFeatures(rayMap, { x: 2, y: 8 }).length).toBe(1)
+
+    // 5. Outside polygon is filtered out (tolerance only applies to lines)
+    const outsideMap = { ...mockMap, queryRenderedFeatures: () => [polyFeat] }
+    expect(queryFeatures(outsideMap, { x: -1, y: 5 }).length).toBe(0)
+
+    // 6. Symbol under exact click point is included
+    const symbolFeat = { id: 'sym', layer: { id: 'S', source: 'src' }, geometry: { type: 'Point', coordinates: [0, 0] } }
+    const symbolMap = { ...mockMap, queryRenderedFeatures: () => [symbolFeat] } // both calls return it
+    expect(queryFeatures(symbolMap, { x: 5, y: 5 }).length).toBe(1)
+
+    // 7. Symbol NOT under exact click point is filtered out
+    let call = 0
+    const symbolMissMap = {
+      ...mockMap,
+      queryRenderedFeatures: () => call++ === 0 ? [symbolFeat] : [] // bbox returns it, exact does not
+    }
+    expect(queryFeatures(symbolMissMap, { x: 5, y: 5 }).length).toBe(0)
   })
 })

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

@@ -0,0 +1,30 @@
+const SVG_ERROR_PREVIEW_LENGTH = 80
+
+/**
+ * Rasterises an SVG string to an ImageData object via a canvas.
+ *
+ * @param {string} svgString - Full SVG markup to render
+ * @param {number} width - Canvas width in pixels
+ * @param {number} height - Canvas height in pixels
+ * @returns {Promise<ImageData>}
+ */
+export const rasteriseToImageData = (svgString, width, height) =>
+  new Promise((resolve, reject) => {
+    const blob = new Blob([svgString], { type: 'image/svg+xml' })
+    const url = URL.createObjectURL(blob)
+    const img = new Image(width, height)
+    img.onload = () => {
+      const canvas = document.createElement('canvas')
+      canvas.width = width
+      canvas.height = height
+      const ctx = canvas.getContext('2d')
+      ctx.drawImage(img, 0, 0, width, height)
+      URL.revokeObjectURL(url)
+      resolve(ctx.getImageData(0, 0, width, height))
+    }
+    img.onerror = () => {
+      URL.revokeObjectURL(url)
+      reject(new Error(`Failed to rasterise SVG: ${svgString.slice(0, SVG_ERROR_PREVIEW_LENGTH)}`))
+    }
+    img.src = url
+  })

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

@@ -0,0 +1,69 @@
+import { rasteriseToImageData } from './rasteriseToImageData.js'
+
+const SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><circle cx="16" cy="16" r="8"/></svg>'
+const WIDTH = 32
+const HEIGHT = 32
+
+// Mirrors SVG_ERROR_PREVIEW_LENGTH in rasteriseToImageData.js
+const ERROR_PREVIEW_LENGTH = 80
+// Length chosen to be well over ERROR_PREVIEW_LENGTH so truncation is exercised
+const LONG_CONTENT_LENGTH = 200
+
+beforeAll(() => {
+  globalThis.URL.createObjectURL = jest.fn(() => 'blob:mock')
+  globalThis.URL.revokeObjectURL = jest.fn()
+
+  HTMLCanvasElement.prototype.getContext = jest.fn(() => ({
+    drawImage: jest.fn(),
+    getImageData: jest.fn((_x, _y, w, h) => ({ width: w, height: h }))
+  }))
+
+  globalThis.Image = class {
+    constructor (w, h) {
+      this.width = w
+      this.height = h
+      this._src = ''
+    }
+
+    get src () { return this._src }
+    set src (val) { this._src = val; this.onload?.() }
+  }
+})
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  globalThis.URL.createObjectURL.mockReturnValue('blob:mock')
+})
+
+describe('rasteriseToImageData', () => {
+  it('resolves with ImageData at the requested dimensions, draws via canvas, and revokes the blob URL', async () => {
+    const getContext = HTMLCanvasElement.prototype.getContext
+    const result = await rasteriseToImageData(SVG, WIDTH, HEIGHT)
+    expect(result).toMatchObject({ width: WIDTH, height: HEIGHT })
+    expect(globalThis.URL.createObjectURL).toHaveBeenCalledWith(expect.any(Blob))
+    expect(globalThis.URL.revokeObjectURL).toHaveBeenCalledWith('blob:mock')
+    const { drawImage, getImageData } = getContext.mock.results[0].value
+    expect(drawImage).toHaveBeenCalledWith(expect.any(Object), 0, 0, WIDTH, HEIGHT)
+    expect(getImageData).toHaveBeenCalledWith(0, 0, WIDTH, HEIGHT)
+  })
+
+  it('rejects with a truncated SVG preview and revokes the blob URL on error', async () => {
+    const originalImage = globalThis.Image
+    globalThis.Image = class {
+      constructor (w, h) { this.width = w; this.height = h; this._src = '' }
+      get src () { return this._src }
+      set src (val) { this._src = val; this.onerror?.() }
+    }
+    try {
+      const longSvg = `<svg>${'x'.repeat(LONG_CONTENT_LENGTH)}</svg>`
+      const error = await rasteriseToImageData(longSvg, WIDTH, HEIGHT).catch(e => e)
+      expect(error.message).toMatch('Failed to rasterise SVG')
+      const preview = error.message.replace('Failed to rasterise SVG: ', '')
+      expect(preview).toHaveLength(ERROR_PREVIEW_LENGTH)
+      expect(preview).toBe(longSvg.slice(0, ERROR_PREVIEW_LENGTH))
+      expect(globalThis.URL.revokeObjectURL).toHaveBeenCalledWith('blob:mock')
+    } finally {
+      globalThis.Image = originalImage
+    }
+  })
+})

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

@@ -0,0 +1,147 @@
+import { getSymbolDef, getSymbolStyleColors, getSymbolViewBox } from '../../../../src/utils/symbolUtils.js'
+import { rasteriseToImageData } from './rasteriseToImageData.js'
+
+const ANCHOR_LOW = 0.25
+const ANCHOR_HIGH = 0.75
+const HASH_BASE = 36
+
+const hashString = (str) => {
+  let hash = 0
+  for (const ch of str) {
+    hash = Math.trunc(((hash << 5) - hash) + ch.codePointAt(0))
+  }
+  return Math.abs(hash).toString(HASH_BASE)
+}
+
+// ─── MapLibre-specific anchor conversion ──────────────────────────────────────
+
+/**
+ * Converts a fractional [ax, ay] anchor to a MapLibre icon-anchor string.
+ * Snaps to the nearest of the 9 standard positions.
+ *
+ * @param {number[]} anchor - [x, y] in 0–1 space
+ * @returns {string} MapLibre icon-anchor value
+ */
+const xAnchor = (ax) => {
+  if (ax <= ANCHOR_LOW) {
+    return 'left'
+  }
+  if (ax >= ANCHOR_HIGH) {
+    return 'right'
+  }
+  return ''
+}
+
+const yAnchor = (ay) => {
+  if (ay <= ANCHOR_LOW) {
+    return 'top'
+  }
+  if (ay >= ANCHOR_HIGH) {
+    return 'bottom'
+  }
+  return ''
+}
+
+export const anchorToMaplibre = ([ax, ay]) => {
+  const x = xAnchor(ax)
+  const y = yAnchor(ay)
+  return (y + (x && y ? '-' : '') + x) || 'center'
+}
+
+// ─── Image IDs ────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a deterministic image ID for a symbol in normal or selected state.
+ * Based on the hash of the fully resolved SVG content and the pixel ratio.
+ *
+ * @param {Object} dataset
+ * @param {Object} mapStyle - Current map style config (provides id, selectedColor, haloColor)
+ * @param {Object} symbolRegistry
+ * @param {boolean} [selected=false]
+ * @param {number} [pixelRatio=2] - Device pixel ratio × map size scale factor
+ * @returns {string|null}
+ */
+export const getSymbolImageId = (dataset, mapStyle, symbolRegistry, selected = false, pixelRatio = 2) => {
+  const symbolDef = getSymbolDef(dataset, symbolRegistry)
+  if (!symbolDef) {
+    return null
+  }
+  const styleColors = getSymbolStyleColors(dataset)
+  const resolved = selected
+    ? symbolRegistry.resolveSelected(symbolDef, styleColors, mapStyle)
+    : symbolRegistry.resolve(symbolDef, styleColors, mapStyle)
+  return `symbol-${selected ? 'sel-' : ''}${hashString(resolved)}-${pixelRatio}x`
+}
+
+// ─── Rasterisation ────────────────────────────────────────────────────────────
+
+// Module-level cache: imageId → ImageData. Avoids re-rasterising identical symbols.
+const imageDataCache = new Map()
+
+const rasteriseSymbolImage = async (dataset, mapStyle, symbolRegistry, selected, pixelRatio) => {
+  const symbolDef = getSymbolDef(dataset, symbolRegistry)
+  if (!symbolDef) {
+    return null
+  }
+  const styleColors = getSymbolStyleColors(dataset)
+  const resolvedContent = selected
+    ? symbolRegistry.resolveSelected(symbolDef, styleColors, mapStyle)
+    : symbolRegistry.resolve(symbolDef, styleColors, mapStyle)
+
+  const imageId = `symbol-${selected ? 'sel-' : ''}${hashString(resolvedContent)}-${pixelRatio}x`
+
+  let imageData = imageDataCache.get(imageId)
+  if (!imageData) {
+    const viewBox = getSymbolViewBox(dataset, symbolDef)
+    const [,, width, height] = viewBox.split(' ').map(Number)
+    // Render at pixelRatio× to keep icons crisp at the current device DPI and map size.
+    // MapLibre receives the matching pixelRatio so the image displays at its original logical size.
+    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="${width * pixelRatio}" height="${height * pixelRatio}" viewBox="${viewBox}">${resolvedContent}</svg>`
+    imageData = await rasteriseToImageData(svgString, width * pixelRatio, height * pixelRatio)
+    imageDataCache.set(imageId, imageData)
+  }
+
+  return { imageId, imageData }
+}
+
+/**
+ * Register normal and selected symbol images for the given pre-resolved symbol configs.
+ * Skips images that are already registered (safe to call on style change).
+ * Updates `map._symbolImageMap` with normal→selected image ID pairs.
+ *
+ * Callers are responsible for resolving sublayers before calling this function
+ * (see `getSymbolConfigs` in the datasets plugin adapter).
+ *
+ * @param {Object} map - MapLibre map instance
+ * @param {Object[]} symbolConfigs - Flat list of datasets/merged-sublayers that have a symbol config
+ * @param {Object} mapStyle - Current map style config (provides id, selectedColor, haloColor)
+ * @param {Object} symbolRegistry
+ * @param {number} [pixelRatio=2] - Device pixel ratio × map size scale factor (computed by caller)
+ * @returns {Promise<void>}
+ */
+export const registerSymbols = async (map, symbolConfigs, mapStyle, symbolRegistry, pixelRatio = 2) => {
+  if (!symbolConfigs.length) {
+    return
+  }
+
+  // Reset the normal→selected image ID lookup so stale entries don't persist after a style change
+  map._symbolImageMap = {}
+
+  await Promise.all(symbolConfigs.flatMap(config => {
+    const normalId = getSymbolImageId(config, mapStyle, symbolRegistry, false, pixelRatio)
+    const selectedId = getSymbolImageId(config, mapStyle, symbolRegistry, true, pixelRatio)
+    if (normalId && selectedId) {
+      map._symbolImageMap[normalId] = selectedId
+    }
+    return [false, true].map(async (selected) => {
+      const imageId = selected ? selectedId : normalId
+      if (!imageId || map.hasImage(imageId)) {
+        return
+      }
+      const result = await rasteriseSymbolImage(config, mapStyle, symbolRegistry, selected, pixelRatio)
+      if (result && !map.hasImage(result.imageId)) {
+        map.addImage(result.imageId, result.imageData, { pixelRatio })
+      }
+    })
+  }))
+}