@defra/interactive-map 0.0.37-alpha → 0.0.39-alpha

package/plugins/draw/src/adapters/openlayers/edit/vertexLayer.js

@@ -0,0 +1,49 @@
+import VectorSource from 'ol/source/Vector.js'
+import VectorLayer from 'ol/layer/Vector.js'
+import Feature from 'ol/Feature.js'
+import Point from 'ol/geom/Point.js'
+import { getCoords } from '../utils/geometryHelpers.js'
+
+/**
+ * Always-visible vertex handle layer for edit mode.
+ * OL Modify's built-in vertex handles only appear on hover; this layer
+ * keeps circles visible at all times. The selected vertex is rendered by
+ * the separate active-selection layer in EditMode (zIndex 103).
+ */
+export const createVertexLayer = (map, vertexStyle) => {
+  let currentStyle = vertexStyle
+  let selectedIndex = -1
+  const source = new VectorSource()
+  const layer = new VectorLayer({
+    source,
+    style: (feature) => feature.get('vertexIndex') === selectedIndex ? null : [currentStyle],
+    zIndex: 102
+  })
+  map.addLayer(layer)
+
+  return {
+    update (geom) {
+      source.clear()
+      getCoords(geom).forEach((coord, i) => {
+        const f = new Feature({ geometry: new Point(coord) })
+        f.set('vertexIndex', i)
+        source.addFeature(f)
+      })
+    },
+
+    setSelected (index) {
+      selectedIndex = index
+      source.changed()
+    },
+
+    updateStyle (newVertexStyle) {
+      currentStyle = newVertexStyle
+      source.changed()
+    },
+
+    remove () {
+      source.clear()
+      map.removeLayer(layer)
+    }
+  }
+}

package/plugins/draw/src/adapters/openlayers/edit/vertexLayer.test.js

@@ -0,0 +1,42 @@
+import Style from 'ol/style/Style.js'
+import { createVertexLayer } from './vertexLayer.js'
+import { createFakeMap } from '../__helpers__/harness.js'
+
+const GEOM = { type: 'Polygon', coordinates: [[[0, 0], [10, 0], [10, 10], [0, 0]]] }
+
+const setup = () => {
+  const map = createFakeMap()
+  const style = new Style({})
+  const handles = createVertexLayer(map, style)
+  const layer = map.layers[0]
+  return { map, style, handles, layer, source: layer.getSource() }
+}
+
+test('update renders one handle per editable vertex, indexed', () => {
+  const { handles, source } = setup()
+  handles.update(GEOM)
+  expect(source.getFeatures()).toHaveLength(3)
+  expect(source.getFeatures().map(f => f.get('vertexIndex')).sort()).toEqual([0, 1, 2])
+})
+
+test('the selected vertex is hidden here (the active layer draws it) and styles hot-swap', () => {
+  const { handles, layer, style, source } = setup()
+  handles.update(GEOM)
+  handles.setSelected(1)
+  const styleFn = layer.getStyle()
+  const featureAt = (i) => source.getFeatures().find(f => f.get('vertexIndex') === i)
+  expect(styleFn(featureAt(1))).toBeNull()
+  expect(styleFn(featureAt(0))).toEqual([style])
+
+  const newStyle = new Style({})
+  handles.updateStyle(newStyle)
+  expect(styleFn(featureAt(0))).toEqual([newStyle])
+})
+
+test('remove clears and detaches the layer', () => {
+  const { map, handles, source } = setup()
+  handles.update(GEOM)
+  handles.remove()
+  expect(source.getFeatures()).toHaveLength(0)
+  expect(map.layers).toHaveLength(0)
+})

package/plugins/draw/src/adapters/openlayers/edit/vertexOps.js

@@ -0,0 +1,100 @@
+import {
+  getCoords,
+  getRingSegments,
+  getSegmentForIndex,
+  getModifiableCoords
+} from '../utils/geometryHelpers.js'
+import { MIN_VERTICES } from '../../../validation/rules.js'
+
+/**
+ * Delete the vertex at `selectedIndex` from the OL feature's geometry.
+ * Respects minimum vertex counts (MIN_VERTICES — validation/rules.js).
+ *
+ * @returns {{ deletedIndex: number, deletedCoord: number[] } | null} undo payload, or null if not deleted
+ */
+export const deleteVertex = (olFeature, selectedIndex) => {
+  const geom = olFeature.getGeometry()
+  const geojsonGeom = { type: geom.getType(), coordinates: geom.getCoordinates() }
+  const coords = getCoords(geojsonGeom)
+  const segments = getRingSegments(geojsonGeom)
+  const result = getSegmentForIndex(segments, selectedIndex)
+  if (!result) {
+    return null
+  }
+
+  const { segment } = result
+  const minVertices = segment.closed ? MIN_VERTICES.Polygon : MIN_VERTICES.LineString
+  if (segment.length <= minVertices) {
+    return null
+  }
+
+  const deletedCoord = [...coords[selectedIndex]]
+  const ring = getModifiableCoords(geojsonGeom, segment.path)
+  ring.splice(result.localIdx, 1)
+  if (segment.closed) {
+    ring[ring.length - 1] = [...ring[0]]
+  }
+
+  geom.setCoordinates(geojsonGeom.coordinates)
+  return { deletedIndex: selectedIndex, deletedCoord }
+}
+
+/**
+ * Insert a vertex after `afterIndex` in the OL feature's geometry.
+ * Used when the user activates a midpoint (touch tap or keyboard insert).
+ *
+ * @param {number[][]} midpoints - current midpoint array (from midpointLayer)
+ * @param {number} midpointFlatIndex - flat index (vertexCount + midpointOffset)
+ * @param {number} vertexCount - number of actual vertices
+ * @param {number[][]} vertices - current vertex array
+ * @returns {{ insertedIndex: number } | null}
+ */
+export const insertAtMidpoint = (olFeature, midpoints, midpointFlatIndex, vertexCount) => {
+  const midpointLocalIdx = midpointFlatIndex - vertexCount
+  const midCoord = midpoints[midpointLocalIdx]
+  if (!midCoord) {
+    return null
+  }
+
+  const geom = olFeature.getGeometry()
+  const geojsonGeom = { type: geom.getType(), coordinates: geom.getCoordinates() }
+  const segments = getRingSegments(geojsonGeom)
+
+  // Map midpoint local index to insertion position in the coordinate array
+  let midpointCounter = 0
+  for (const seg of segments) {
+    const segMidpoints = seg.closed ? seg.length : seg.length - 1
+    if (midpointLocalIdx < midpointCounter + segMidpoints) {
+      const localMidIdx = midpointLocalIdx - midpointCounter
+      const insertLocalIdx = localMidIdx + 1
+      const insertGlobalIdx = seg.start + insertLocalIdx
+      const ring = getModifiableCoords(geojsonGeom, seg.path)
+      ring.splice(insertLocalIdx, 0, [...midCoord])
+      geom.setCoordinates(geojsonGeom.coordinates)
+      return { insertedIndex: insertGlobalIdx }
+    }
+    midpointCounter += segMidpoints
+  }
+
+  return null
+}
+
+/**
+ * Move vertex at `index` to `newCoord` in the OL feature's geometry.
+ */
+export const moveVertex = (olFeature, index, newCoord) => {
+  const geom = olFeature.getGeometry()
+  const geojsonGeom = { type: geom.getType(), coordinates: geom.getCoordinates() }
+  const segments = getRingSegments(geojsonGeom)
+  const result = getSegmentForIndex(segments, index)
+  if (!result) {
+    return
+  }
+
+  const ring = getModifiableCoords(geojsonGeom, result.segment.path)
+  ring[result.localIdx] = [...newCoord]
+  if (result.segment.closed && result.localIdx === 0) {
+    ring[ring.length - 1] = [...newCoord]
+  }
+  geom.setCoordinates(geojsonGeom.coordinates)
+}

package/plugins/draw/src/adapters/openlayers/edit/vertexOps.test.js

@@ -0,0 +1,80 @@
+import Feature from 'ol/Feature.js'
+import Polygon from 'ol/geom/Polygon.js'
+import { deleteVertex, insertAtMidpoint, moveVertex } from './vertexOps.js'
+import { polygonFeature, lineFeature } from '../__helpers__/harness.js'
+
+const SQUARE = [[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]
+const HOLE = [[2, 2], [4, 2], [4, 4], [2, 2]]
+const ring = (feature, i = 0) => feature.getGeometry().getCoordinates()[i]
+
+describe('deleteVertex', () => {
+  test('removes the vertex and keeps the ring closed', () => {
+    const feature = polygonFeature(SQUARE)
+    expect(deleteVertex(feature, 1)).toEqual({ deletedIndex: 1, deletedCoord: [10, 0] })
+    expect(ring(feature)).toEqual([[0, 0], [10, 10], [0, 10], [0, 0]])
+  })
+
+  test('deleting ring vertex 0 syncs the closing coordinate', () => {
+    const feature = polygonFeature(SQUARE)
+    deleteVertex(feature, 0)
+    expect(ring(feature)).toEqual([[10, 0], [10, 10], [0, 10], [10, 0]])
+  })
+
+  test('deleting from an open line needs no closing-coordinate sync', () => {
+    const feature = lineFeature([[0, 0], [10, 0], [20, 0]])
+    expect(deleteVertex(feature, 1)).toEqual({ deletedIndex: 1, deletedCoord: [10, 0] })
+    expect(feature.getGeometry().getCoordinates()).toEqual([[0, 0], [20, 0]])
+  })
+
+  test('refuses to shrink below the minimum (3 for rings, 2 for lines) or for bad indices', () => {
+    expect(deleteVertex(polygonFeature([[0, 0], [10, 0], [10, 10], [0, 0]]), 1)).toBeNull()
+    expect(deleteVertex(lineFeature([[0, 0], [10, 0]]), 0)).toBeNull()
+    expect(deleteVertex(polygonFeature(SQUARE), 99)).toBeNull()
+  })
+})
+
+describe('insertAtMidpoint', () => {
+  test('inserts after the midpoint position in the first ring', () => {
+    const feature = polygonFeature(SQUARE) // 4 vertices; midpoint 0 sits between v0 and v1
+    expect(insertAtMidpoint(feature, [[5, 0]], 4, 4)).toEqual({ insertedIndex: 1 })
+    expect(ring(feature)[1]).toEqual([5, 0])
+  })
+
+  test('maps midpoints in later rings to their global insert position', () => {
+    const feature = new Feature(new Polygon([SQUARE, HOLE]))
+    // 7 vertices; outer ring owns midpoints 0-3, hole owns 4-6. Hole midpoint 1 = between hole v1 and v2.
+    const midpoints = [[5, 0], [10, 5], [5, 10], [0, 5], [3, 2], [4, 3], [3, 3]]
+    expect(insertAtMidpoint(feature, midpoints, 7 + 5, 7)).toEqual({ insertedIndex: 6 })
+    expect(ring(feature, 1)[2]).toEqual([4, 3])
+  })
+
+  test('unknown midpoints are a no-op', () => {
+    expect(insertAtMidpoint(polygonFeature(SQUARE), [[5, 0]], 99, 4)).toBeNull()
+    // A midpoint index past every segment's midpoints (stale midpoint array) is also refused
+    const extra = [[5, 0], [10, 5], [5, 10], [0, 5], [9, 9]]
+    expect(insertAtMidpoint(polygonFeature(SQUARE), extra, 4 + 4, 4)).toBeNull()
+  })
+
+  test('inserts a midpoint into an open line segment', () => {
+    const feature = lineFeature([[0, 0], [10, 0]]) // 2 vertices, 1 midpoint at flat index 2
+    expect(insertAtMidpoint(feature, [[5, 0]], 2, 2)).toEqual({ insertedIndex: 1 })
+    expect(feature.getGeometry().getCoordinates()).toEqual([[0, 0], [5, 0], [10, 0]])
+  })
+})
+
+describe('moveVertex', () => {
+  test('moves the vertex, syncing the closing coordinate for ring vertex 0', () => {
+    const feature = polygonFeature(SQUARE)
+    moveVertex(feature, 0, [1, 1])
+    expect(ring(feature)[0]).toEqual([1, 1])
+    expect(ring(feature).at(-1)).toEqual([1, 1])
+    moveVertex(feature, 2, [20, 20])
+    expect(ring(feature)[2]).toEqual([20, 20])
+  })
+
+  test('an invalid index leaves the geometry untouched', () => {
+    const feature = polygonFeature(SQUARE)
+    moveVertex(feature, 99, [1, 1])
+    expect(ring(feature)).toEqual(SQUARE)
+  })
+})

package/plugins/draw/src/adapters/openlayers/olDraw.js

@@ -0,0 +1,40 @@
+import { OLDrawManager } from './core/OLDrawManager.js'
+import { MAP_SIZE_SCALES } from './defaults.js'
+
+/**
+ * Creates the OLDrawManager, attaches it to mapProvider, and wires
+ * app-level events (MAP_SET_SIZE for scale-aware touch targets,
+ * MAP_SET_STYLE for dynamic color updates).
+ *
+ * @returns {{ manager: OLDrawManager, remove: () => void }}
+ */
+export const createOLDraw = ({ mapProvider, events, eventBus, pluginConfig = {}, mapStyle = null }) => {
+  const { map } = mapProvider
+  const manager = new OLDrawManager(map, pluginConfig)
+
+  if (mapStyle) {
+    manager.setMapStyle(mapStyle)
+  }
+
+  mapProvider.draw = manager
+
+  const handleSetMapSize = (size) => {
+    mapProvider.drawScale = MAP_SIZE_SCALES[size] ?? 1
+  }
+  eventBus.on(events.MAP_SET_SIZE, handleSetMapSize)
+
+  const handleSetMapStyle = (newMapStyle) => {
+    manager.setMapStyle(newMapStyle)
+  }
+  eventBus.on(events.MAP_SET_STYLE, handleSetMapStyle)
+
+  return {
+    manager,
+    remove () {
+      eventBus.off(events.MAP_SET_SIZE, handleSetMapSize)
+      eventBus.off(events.MAP_SET_STYLE, handleSetMapStyle)
+      manager.remove()
+      mapProvider.draw = null
+    }
+  }
+}

package/plugins/draw/src/adapters/openlayers/olDraw.test.js

@@ -0,0 +1,70 @@
+import { createOLDraw } from './olDraw.js'
+import { OLDrawManager } from './core/OLDrawManager.js'
+import { MAP_SIZE_SCALES } from './defaults.js'
+
+jest.mock('./core/OLDrawManager.js', () => ({
+  OLDrawManager: jest.fn(function () {
+    this.setMapStyle = jest.fn()
+    this.remove = jest.fn()
+  })
+}))
+
+const events = { MAP_SET_SIZE: 'app:size', MAP_SET_STYLE: 'app:style' }
+
+const setup = (mapStyle = null) => {
+  const listeners = {}
+  const eventBus = {
+    on: jest.fn((type, handler) => { listeners[type] = handler }),
+    off: jest.fn(),
+    emit: (type, payload) => listeners[type]?.(payload)
+  }
+  const mapProvider = { map: { id: 'ol-map' } }
+  const olDraw = createOLDraw({ mapProvider, events, eventBus, pluginConfig: { snapRadius: 5 }, mapStyle })
+  const manager = OLDrawManager.mock.instances.at(-1)
+  return { eventBus, mapProvider, olDraw, manager }
+}
+
+afterEach(() => jest.clearAllMocks())
+
+test('creates the manager for the map, exposes it as mapProvider.draw and applies an initial style', () => {
+  const { mapProvider, manager } = setup({ id: 'dark' })
+  expect(OLDrawManager).toHaveBeenCalledWith(mapProvider.map, { snapRadius: 5 })
+  expect(mapProvider.draw).toBe(manager)
+  expect(manager.setMapStyle).toHaveBeenCalledWith({ id: 'dark' })
+
+  expect(setup().manager.setMapStyle).not.toHaveBeenCalled() // no initial style
+})
+
+test('map size changes update the draw UI scale, defaulting to 1 for unknown sizes', () => {
+  const { eventBus, mapProvider } = setup()
+  eventBus.emit(events.MAP_SET_SIZE, 'large')
+  expect(mapProvider.drawScale).toBe(MAP_SIZE_SCALES.large)
+  eventBus.emit(events.MAP_SET_SIZE, 'enormous')
+  expect(mapProvider.drawScale).toBe(1)
+})
+
+test('pluginConfig and mapStyle are optional, defaulting to {} and no initial style', () => {
+  const eventBus = { on: jest.fn(), off: jest.fn() }
+  const mapProvider = { map: { id: 'ol-map' } }
+  const olDraw = createOLDraw({ mapProvider, events, eventBus }) // no pluginConfig, no mapStyle
+  const manager = OLDrawManager.mock.instances.at(-1)
+  expect(OLDrawManager).toHaveBeenCalledWith(mapProvider.map, {})
+  expect(manager.setMapStyle).not.toHaveBeenCalled()
+  expect(mapProvider.draw).toBe(manager)
+  olDraw.remove()
+})
+
+test('map style changes are forwarded to the manager', () => {
+  const { eventBus, manager } = setup()
+  eventBus.emit(events.MAP_SET_STYLE, { id: 'dark' })
+  expect(manager.setMapStyle).toHaveBeenCalledWith({ id: 'dark' })
+})
+
+test('remove unsubscribes, destroys the manager and clears mapProvider.draw', () => {
+  const { eventBus, mapProvider, olDraw, manager } = setup()
+  olDraw.remove()
+  expect(eventBus.off).toHaveBeenCalledWith(events.MAP_SET_SIZE, expect.any(Function))
+  expect(eventBus.off).toHaveBeenCalledWith(events.MAP_SET_STYLE, expect.any(Function))
+  expect(manager.remove).toHaveBeenCalled()
+  expect(mapProvider.draw).toBeNull()
+})

package/plugins/draw/src/adapters/openlayers/snap/snapEngine.js

@@ -0,0 +1,220 @@
+import { transform as projTransform } from 'ol/proj.js'
+import VectorLayer from 'ol/layer/Vector.js'
+import VectorTileLayer from 'ol/layer/VectorTile.js'
+import { testOLFeature, testRenderFeature, bestOf } from './snapGeometry.js'
+
+// VectorTile geometry is clipped to a rectangle (tile extent + buffer), producing fake
+// axis-aligned segments — and fake vertices where the clip cut the ring — that don't
+// exist in the real data and mustn't be snap targets. They are detected by orientation:
+// clip segments are exactly axis-aligned in tile space AND sit near a tile edge, a
+// combination real boundaries essentially never produce. This works without knowing
+// the exact buffer size the tiler used. Standard MVT buffer is 128/4096 tile units.
+const MVT_BUFFER_UNITS = 128
+const MVT_TILE_EXTENT = 4096
+
+const buildTileBoundaryState = (layer, map) => {
+  const source = layer.getSource()
+  const tileGrid = source?.getTileGrid()
+  if (!tileGrid) { return null }
+  const viewProj = map.getView().getProjection()
+  const sourceProj = source.getProjection() ?? viewProj
+  const zoom = tileGrid.getZForResolution(map.getView().getResolution(), 0)
+  return { tileGrid, viewProj, sourceProj, zoom }
+}
+
+// Per-candidate context: the candidate's tile extent plus the two tolerances,
+// computed once so both adjacent segments of a vertex reuse it.
+const getClipContext = (state, coord) => {
+  if (!state) { return null }
+  const { tileGrid, viewProj, sourceProj, zoom } = state
+  const toSource = (c) => c ? projTransform(c, viewProj, sourceProj) : null
+  const anchor = toSource(coord)
+  const tileCoord = tileGrid.getTileCoordForCoordAndZ(anchor, zoom)
+  const extent = tileGrid.getTileCoordExtent(tileCoord)
+  const tileWidth = extent[2] - extent[0]
+  return {
+    toSource,
+    anchor,
+    extent,
+    // Coarse gate: within twice the standard MVT buffer of a tile edge. Generous on
+    // purpose (the axis-alignment test does the real discrimination) so tilers with
+    // a non-standard buffer size are still covered. Relative to tile width, so it is
+    // projection-unit independent.
+    band: tileWidth * (2 * MVT_BUFFER_UNITS / MVT_TILE_EXTENT),
+    // MVT coordinates are quantized to 1/4096 of the tile extent; two quantization
+    // steps of tolerance decides whether a segment is exactly axis-aligned.
+    eps: 2 * (tileWidth / MVT_TILE_EXTENT)
+  }
+}
+
+const isArtefactSegment = (ctx, pa, pb) => {
+  if (!pa || !pb) { return false }
+  const [minX, minY, maxX, maxY] = ctx.extent
+  const nearEdge = (v, lo, hi) => Math.min(Math.abs(v - lo), Math.abs(v - hi)) <= ctx.band
+  const vertical = Math.abs(pa[0] - pb[0]) <= ctx.eps && nearEdge(pa[0], minX, maxX)
+  const horizontal = Math.abs(pa[1] - pb[1]) <= ctx.eps && nearEdge(pa[1], minY, maxY)
+  return vertical || horizontal
+}
+
+// Edges: artefact when the snapped segment itself is an axis-aligned boundary segment.
+// Vertices: fake vertices are the points where clipping cut the ring, i.e. endpoints
+// of artefact segments — test both adjacent segments.
+const isClipArtefact = (state, candidate) => {
+  const ctx = getClipContext(state, candidate.coord)
+  if (!ctx) { return false }
+  if (candidate.type === 'edge') {
+    const [a, b] = candidate.seg
+    return isArtefactSegment(ctx, ctx.toSource(a), ctx.toSource(b))
+  }
+  const [prev, next] = candidate.adjacent ?? []
+  return isArtefactSegment(ctx, ctx.anchor, ctx.toSource(prev)) ||
+         isArtefactSegment(ctx, ctx.anchor, ctx.toSource(next))
+}
+
+// Read at call time so it can be toggled from the console at any point: window.DEBUG_SNAP_VISIBILITY = true
+const isDebugEnabled = () => globalThis.DEBUG_SNAP_VISIBILITY === true
+
+// Two same-style fill polygons share an invisible boundary — snapping to it is confusing.
+// Detect this by projecting a test point slightly past the snap position (away from the cursor)
+// and checking whether the same fill layer covers that side too.
+// If it does → same-style invisible boundary → skip.
+// If not (empty space, road, different layer) → visible outer edge → include.
+const INVISIBLE_FILL_MIN_DIST_SQ = 1 // (1m)² — below this, cursor is on the edge, skip direction check
+
+const isInvisibleFillBoundary = (edgeCoord, cursorCoord, layerId, map, vtLayers, resolution) => {
+  const dx = edgeCoord[0] - cursorCoord[0]
+  const dy = edgeCoord[1] - cursorCoord[1]
+  const distSq = dx * dx + dy * dy
+  if (distSq < INVISIBLE_FILL_MIN_DIST_SQ) { return false }
+  const dist = Math.sqrt(distSq)
+  const step = resolution * 4
+  const testCoord = [edgeCoord[0] + (dx / dist) * step, edgeCoord[1] + (dy / dist) * step]
+  const testPixel = map.getPixelFromCoordinate(testCoord)
+  if (!testPixel) { return false }
+  return !!map.forEachFeatureAtPixel(
+    testPixel,
+    (f) => f.get('mapbox-layer')?.id === layerId,
+    { hitTolerance: 2, layerFilter: (l) => vtLayers.includes(l) }
+  )
+}
+
+const logCandidate = (candidate, mapboxLayer) => {
+  if (!isDebugEnabled()) { return }
+  console.log('[snap-candidate-found]', {
+    type: candidate.type,
+    layerId: mapboxLayer?.id,
+    layerType: mapboxLayer?.type,
+    coord: [candidate.coord[0].toFixed(2), candidate.coord[1].toFixed(2)],
+    distSq: candidate.distSq.toFixed(2)
+  })
+}
+
+// Returns true when the candidate is a rendering artefact rather than a visible
+// snap target: either a tile clip artefact, or an invisible same-fill boundary.
+const shouldFilterCandidate = ({ candidate, cursorCoord, mapboxLayer, boundaryState, map, vtLayers, resolution }) => {
+  if (isClipArtefact(boundaryState, candidate)) {
+    if (isDebugEnabled()) { console.log('[snap-filtered] tile clip artefact', candidate.type) }
+    return true
+  }
+  if (candidate.type === 'edge' && mapboxLayer?.type === 'fill' &&
+      isInvisibleFillBoundary(candidate.coord, cursorCoord, mapboxLayer.id, map, vtLayers, resolution)) {
+    if (isDebugEnabled()) { console.log('[snap-filtered] invisible fill boundary') }
+    return true
+  }
+  return false
+}
+
+// Folds a feature's candidates into the current best, skipping rendering artefacts
+const pickVisibleCandidates = (best, candidates, context) => {
+  let result = best
+  for (const candidate of candidates) {
+    logCandidate(candidate, context.mapboxLayer)
+    if (!shouldFilterCandidate({ candidate, ...context })) {
+      result = bestOf(result, candidate)
+    }
+  }
+  return result
+}
+
+// Collected on each query — VectorTileLayers are replaced when the map style changes
+const getVTLayers = (map) => {
+  const layers = []
+  map.getLayers().forEach(l => {
+    if (l instanceof VectorTileLayer) { layers.push(l) }
+  })
+  return layers
+}
+
+export const createSnapEngine = (map, snapLayers = []) => {
+  let vtLayerNames = new Set()
+  let olLayers = []
+
+  const setLayers = (layers) => {
+    vtLayerNames = new Set()
+    olLayers = []
+    for (const entry of layers ?? []) {
+      if (typeof entry === 'string') {
+        vtLayerNames.add(entry)
+      } else if (entry instanceof VectorLayer) {
+        olLayers.push(entry)
+      } else {
+        // unsupported layer type — skip
+      }
+    }
+  }
+
+  setLayers(snapLayers)
+
+  const query = (coord, radiusPx) => {
+    if (isDebugEnabled()) {
+      console.log('[snap-query]', { coord: [coord[0].toFixed(2), coord[1].toFixed(2)], radiusPx, vtLayerCount: vtLayerNames.size, olLayerCount: olLayers.length })
+    }
+    const resolution = map.getView().getResolution()
+    if (!resolution) { return null }
+    const toleranceMapUnits = radiusPx * resolution
+    const toleranceSq = toleranceMapUnits * toleranceMapUnits
+    const ext = [
+      coord[0] - toleranceMapUnits,
+      coord[1] - toleranceMapUnits,
+      coord[0] + toleranceMapUnits,
+      coord[1] + toleranceMapUnits
+    ]
+
+    let best = null
+
+    for (const layer of olLayers) {
+      const source = layer.getSource()
+      if (!source) { continue }
+      for (const feature of source.getFeaturesInExtent(ext)) {
+        best = bestOf(best, testOLFeature(feature, coord, toleranceSq))
+      }
+    }
+
+    if (vtLayerNames.size > 0) {
+      const vtLayers = getVTLayers(map)
+      const pixel = vtLayers.length > 0 ? map.getPixelFromCoordinate(coord) : null
+      if (pixel) {
+        const tileBoundaryStates = new Map()
+        map.forEachFeatureAtPixel(
+          pixel,
+          (feature, layer) => {
+            const mapboxLayer = feature.get('mapbox-layer')
+            if (!vtLayerNames.has(mapboxLayer?.id)) { return }
+            const candidates = testRenderFeature(feature, coord, toleranceSq)
+            if (!candidates.length) { return }
+            if (!tileBoundaryStates.has(layer)) {
+              tileBoundaryStates.set(layer, buildTileBoundaryState(layer, map))
+            }
+            const boundaryState = tileBoundaryStates.get(layer)
+            best = pickVisibleCandidates(best, candidates, { cursorCoord: coord, mapboxLayer, boundaryState, map, vtLayers, resolution })
+          },
+          { hitTolerance: radiusPx, layerFilter: (l) => vtLayers.includes(l) }
+        )
+      }
+    }
+
+    return best ? { type: best.type, coord: best.coord } : null
+  }
+
+  return { query, setLayers }
+}