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

package/plugins/draw/src/adapters/maplibre/mapboxDraw.test.js

@@ -6,12 +6,19 @@ import { setupTouchClickWorkaround } from './utils/touchClickWorkaround.js'
 import { applyTouchVertexColors } from './modes/editVertexMode/touchHandlers.js'
 import { resolveColors } from '../../utils/resolveColors.js'
 import { TOLERANCES, MAP_SIZE_SCALES } from './defaults.js'
+import { refreshAllPointSymbols } from './pointSymbolImages.js'
 import { createMapboxDraw } from './mapboxDraw.js'
 
 jest.mock('@mapbox/mapbox-gl-draw', () => {
   const MockDraw = jest.fn(function () {
     this.modes = {}
     this.changeMode = jest.fn()
+    // Mirrors mapbox-gl-draw's own index.js: `api.options = options` — the fully-processed
+    // (cold+hot-duplicated) styles array survives on the public instance regardless of any
+    // later map.setStyle() wiping the actual map layers built from it.
+    this.options = { styles: [{ id: 'fill-inactive.cold' }, { id: 'fill-inactive.hot' }] }
+    this.set = jest.fn()
+    this.getAll = jest.fn(() => ({ type: 'FeatureCollection', features: [{ type: 'Feature', id: 'f1' }] }))
   })
   MockDraw.constants = { classes: {} }
   MockDraw.modes = { existing_mode: { id: 'existing' } }
@@ -22,6 +29,8 @@ jest.mock('./modes/disabledMode.js', () => ({ DisabledMode: { id: 'disabled' } }
 jest.mock('./modes/editVertexMode.js', () => ({ EditVertexMode: { id: 'edit_vertex' } }))
 jest.mock('./modes/drawPolygonMode.js', () => ({ DrawPolygonMode: { id: 'draw_polygon' } }))
 jest.mock('./modes/drawLineMode.js', () => ({ DrawLineMode: { id: 'draw_line' } }))
+jest.mock('./modes/drawPointMode.js', () => ({ DrawPointMode: { id: 'draw_point' } }))
+jest.mock('./pointSymbolImages.js', () => ({ refreshAllPointSymbols: jest.fn(() => Promise.resolve()) }))
 jest.mock('./styles.js', () => ({
   createDrawStyles: jest.fn(() => ['style']),
   updateDrawStyles: jest.fn()
@@ -38,21 +47,25 @@ jest.mock('./defaults.js', () => ({
   MAP_SIZE_SCALES: { medium: 1.5 }
 }))
 
-const EVENTS = { MAP_SET_STYLE: 'map:setstyle', MAP_SET_SIZE: 'map:setsize' }
+const EVENTS = { MAP_SET_STYLE: 'map:setstyle', MAP_STYLE_CHANGE: 'map:stylechange', MAP_SET_SIZE: 'map:setsize', MAP_SET_PIXEL_RATIO: 'map:setpixelratio', MAP_DATA_CHANGE: 'map:datachange' }
 
 const handlerFor = (mockFn, eventName) =>
   mockFn.mock.calls.find(([name]) => name === eventName)?.[1]
 
-const createMap = () => ({
+const createMap = ({ hasDrawSource = true } = {}) => ({
   addControl: jest.fn(),
   once: jest.fn(),
   on: jest.fn(),
   off: jest.fn(),
-  fire: jest.fn()
+  fire: jest.fn(),
+  getSource: jest.fn(() => (hasDrawSource ? {} : undefined)),
+  addSource: jest.fn(),
+  addLayer: jest.fn(),
+  triggerRepaint: jest.fn()
 })
 
-const setup = ({ existingDraw, existingUndoStack, pluginConfig } = {}) => {
-  const map = createMap()
+const setup = ({ existingDraw, existingUndoStack, pluginConfig, hasDrawSource } = {}) => {
+  const map = createMap({ hasDrawSource })
   const mapProvider = {
     map,
     _mapboxDrawInstance: existingDraw,
@@ -201,36 +214,153 @@ describe('createMapboxDraw – setup side effects', () => {
 })
 
 describe('createMapboxDraw – event handlers', () => {
-  test('MAP_SET_STYLE updates the current style and restyles on idle', () => {
+  // MAP_SET_STYLE fires the instant a style change is *requested* — before map.setStyle()
+  // has necessarily even been called. Registering the idle/re-add work directly off it risks
+  // catching the map still idle from the *previous* style, no-opping, and consuming itself
+  // before the real wipe even happens. Only MAP_STYLE_CHANGE (which MapLibre only ever emits
+  // off the native 'style.load' event, i.e. strictly after setStyle() was actually called)
+  // should trigger the settle/idle work — this is the split under test throughout this block.
+  test('MAP_SET_STYLE alone only stashes the style — no idle listener registered yet', () => {
     const { map, eventBus } = setup()
 
-    const styleHandler = handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)
-    map._drawEditContainer = { querySelector: jest.fn(() => 'svg-el') }
-    styleHandler('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
 
     expect(map._drawCurrentMapStyle).toBe('dark')
+    expect(map.once).not.toHaveBeenCalled()
+  })
+
+  test('MAP_STYLE_CHANGE updates the current style and restyles on idle', () => {
+    const { map, eventBus, mapProvider, result } = setup()
+
+    map._drawEditContainer = { querySelector: jest.fn(() => 'svg-el') }
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
 
     const idleCallback = handlerFor(map.once, 'idle')
     idleCallback()
     expect(updateDrawStyles).toHaveBeenCalledWith(map, 'dark', {})
     expect(map._drawEditContainer.querySelector).toHaveBeenCalledWith('[data-im-draw-touch-target]')
     expect(applyTouchVertexColors).toHaveBeenCalledWith('svg-el', 'dark', {})
+    expect(refreshAllPointSymbols).toHaveBeenCalledWith({ draw: result.draw, mapProvider, map })
   })
 
-  test('MAP_SET_STYLE idle handler tolerates a missing edit container', () => {
+  // MAP_STYLE_CHANGE genuinely fires twice per style change (mapEvents.js's permanent
+  // 'style.load' listener alongside appEvents.js's one-shot listener, both bound to the same
+  // native event) — without a dedupe guard the expensive settle work (idle-wait, re-rasterise
+  // every point, one full source rewrite) runs twice back to back, and the second cycle's
+  // completion can land after useHighlightSync's settle window has already closed.
+  test('MAP_STYLE_CHANGE fired twice in a row (both listeners reacting to the same style.load) only settles once', async () => {
     const { map, eventBus } = setup()
 
     handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+
+    expect(map.once).toHaveBeenCalledTimes(1)
+
+    handlerFor(map.once, 'idle')()
+    await Promise.resolve()
+    expect(refreshAllPointSymbols).toHaveBeenCalledTimes(1)
+    expect(eventBus.emit).toHaveBeenCalledTimes(1)
+
+    // Once the in-flight settle has fully completed (onDone fired), a genuinely new style
+    // change is free to trigger another one — the guard isn't stuck permanently latched.
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+    expect(map.once).toHaveBeenCalledTimes(2)
+  })
+
+  // MapLibre's own setStyle() discards the entire previous Style — including every
+  // programmatically-added source/layer, draw's included — and mapbox-gl-draw has no
+  // listener of its own to restore them. Without this, every drawn feature (not just a
+  // selected point) goes invisible and unqueryable after a style reload.
+  //
+  // draw.set() is asserted only after refreshAllPointSymbols resolves, not right after the
+  // idle callback fires: mapbox-gl-draw's own store.render() is requestAnimationFrame-
+  // debounced and bails out silently if the source doesn't exist yet, so pushing draw.getAll()
+  // back in *before* every point's image ids have been re-resolved for the new style would
+  // schedule a deferred render using the previous (already-wiped) style's ids — racing a
+  // still-in-flight worker tile parse of that stale data against the correct one moments
+  // later. Exactly one write, with final data, after refreshAllPointSymbols settles.
+  test('re-creates the sources and layers, then re-pushes every feature (only once symbols have re-resolved), when the draw source is missing after settling', async () => {
+    const { map, eventBus, result } = setup({ hasDrawSource: false })
+
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+    handlerFor(map.once, 'idle')()
+
+    expect(map.addSource).toHaveBeenCalledWith('mapbox-gl-draw-cold', { data: { type: 'FeatureCollection', features: [] }, type: 'geojson' })
+    expect(map.addSource).toHaveBeenCalledWith('mapbox-gl-draw-hot', { data: { type: 'FeatureCollection', features: [] }, type: 'geojson' })
+    // draw.options.styles (mirrors mapbox-gl-draw's own api.options = options) — the fully
+    // processed cold+hot layer pairs from construction time, not re-derived from scratch.
+    expect(map.addLayer).toHaveBeenCalledWith({ id: 'fill-inactive.cold' })
+    expect(map.addLayer).toHaveBeenCalledWith({ id: 'fill-inactive.hot' })
+    // Not yet — refreshAllPointSymbols (mocked as a pending promise below) hasn't resolved.
+    expect(result.draw.set).not.toHaveBeenCalled()
+
+    await Promise.resolve() // flush the refreshAllPointSymbols().then(...) microtask
+    // Sources start empty — every feature the draw control still holds (map-independent, in
+    // its own JS store) is pushed back through the public API to force a full render, now
+    // with every point's image ids already resolved for the new style.
+    expect(result.draw.set).toHaveBeenCalledWith(result.draw.getAll())
+  })
+
+  test('does nothing when the draw source survived the style reload', async () => {
+    const { map, eventBus, result } = setup({ hasDrawSource: true })
+
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+    handlerFor(map.once, 'idle')()
+    await Promise.resolve()
+
+    expect(map.addSource).not.toHaveBeenCalled()
+    expect(map.addLayer).not.toHaveBeenCalled()
+    expect(result.draw.set).not.toHaveBeenCalled()
+  })
+
+  // A selected point's highlight ring (plugins/interact's useHighlightSync) only re-applies
+  // on MAP_DATA_CHANGE — this nudges it explicitly once refreshAllPointSymbols has actually
+  // finished, rather than relying on 'styledata'/'sourcedata' firing it as a side effect.
+  test('emits MAP_DATA_CHANGE once point symbols have actually finished re-resolving after a style change', async () => {
+    const { map, eventBus } = setup()
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+    handlerFor(map.once, 'idle')()
+    await Promise.resolve() // flush the refreshAllPointSymbols().then(...) microtask
+    expect(eventBus.emit).toHaveBeenCalledWith(EVENTS.MAP_DATA_CHANGE)
+  })
+
+  // The highlight ring is a standalone layer added from outside mapbox-gl-draw's own render
+  // cycle (unlike a vertex's active ring, which is just a filter on a layer mapbox-gl-draw
+  // itself always keeps painted) — nothing guarantees MapLibre schedules a real paint pass to
+  // pick it up right after settling. Confirmed by repro: the ring, and separately this app's
+  // own queryRenderedFeatures-based hover cursor (same painted-tile-buffer dependency), stayed
+  // stale until an unrelated map drag forced a render.
+  test('triggers a repaint once point symbols have finished re-resolving after a style change', async () => {
+    const { map, eventBus } = setup()
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
+    handlerFor(map.once, 'idle')()
+    expect(map.triggerRepaint).not.toHaveBeenCalled()
+    await Promise.resolve()
+    expect(map.triggerRepaint).toHaveBeenCalled()
+  })
+
+  test('MAP_STYLE_CHANGE idle handler tolerates a missing edit container', () => {
+    const { map, eventBus } = setup()
+
+    handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
     handlerFor(map.once, 'idle')()
 
     expect(applyTouchVertexColors).toHaveBeenCalledWith(undefined, 'dark', {})
   })
 
-  test('MAP_SET_STYLE passes pluginConfig through to restyling and touch colours', () => {
+  test('MAP_STYLE_CHANGE passes pluginConfig through to restyling and touch colours', () => {
     const pluginConfig = { editStroke: '#custom' }
     const { map, eventBus } = setup({ pluginConfig })
 
     handlerFor(eventBus.on, EVENTS.MAP_SET_STYLE)('dark')
+    handlerFor(eventBus.on, EVENTS.MAP_STYLE_CHANGE)()
     handlerFor(map.once, 'idle')()
 
     expect(updateDrawStyles).toHaveBeenCalledWith(map, 'dark', pluginConfig)
@@ -249,6 +379,37 @@ describe('createMapboxDraw – event handlers', () => {
 
     expect(map.fire).toHaveBeenCalledWith('draw.scalechange', { scale: MAP_SIZE_SCALES.medium })
   })
+
+  // map.getPixelRatio() never updates itself from a plain map-size change — nothing in this
+  // app calls map.setPixelRatio() off MAP_SET_SIZE alone, so a point-symbol refresh here
+  // would run before the map actually knows about the new size. MAP_SET_PIXEL_RATIO (fired
+  // separately, after MAP_SET_SIZE, carrying the freshly computed value) owns that instead.
+  test('MAP_SET_SIZE does not refresh point symbols — MAP_SET_PIXEL_RATIO owns that', () => {
+    const { eventBus } = setup()
+    handlerFor(eventBus.on, EVENTS.MAP_SET_SIZE)('medium')
+    expect(refreshAllPointSymbols).not.toHaveBeenCalled()
+  })
+
+  test('MAP_SET_PIXEL_RATIO refreshes point symbols with the freshly computed pixel ratio', () => {
+    const { map, eventBus, mapProvider, result } = setup()
+    handlerFor(eventBus.on, EVENTS.MAP_SET_PIXEL_RATIO)(3)
+    expect(refreshAllPointSymbols).toHaveBeenCalledWith({ draw: result.draw, mapProvider, map, pixelRatioOverride: 3 })
+  })
+
+  test('MAP_SET_PIXEL_RATIO emits MAP_DATA_CHANGE once point symbols have actually finished re-resolving', async () => {
+    const { eventBus } = setup()
+    handlerFor(eventBus.on, EVENTS.MAP_SET_PIXEL_RATIO)(3)
+    await Promise.resolve()
+    expect(eventBus.emit).toHaveBeenCalledWith(EVENTS.MAP_DATA_CHANGE)
+  })
+
+  test('MAP_SET_PIXEL_RATIO triggers a repaint once point symbols have finished re-resolving', async () => {
+    const { map, eventBus } = setup()
+    handlerFor(eventBus.on, EVENTS.MAP_SET_PIXEL_RATIO)(3)
+    expect(map.triggerRepaint).not.toHaveBeenCalled()
+    await Promise.resolve()
+    expect(map.triggerRepaint).toHaveBeenCalled()
+  })
 })
 
 describe('createMapboxDraw – cleanup', () => {
@@ -260,7 +421,9 @@ describe('createMapboxDraw – cleanup', () => {
 
     expect(removeWorkaround).toHaveBeenCalledTimes(1)
     expect(eventBus.off).toHaveBeenCalledWith(EVENTS.MAP_SET_STYLE, expect.any(Function))
+    expect(eventBus.off).toHaveBeenCalledWith(EVENTS.MAP_STYLE_CHANGE, expect.any(Function))
     expect(eventBus.off).toHaveBeenCalledWith(EVENTS.MAP_SET_SIZE, expect.any(Function))
+    expect(eventBus.off).toHaveBeenCalledWith(EVENTS.MAP_SET_PIXEL_RATIO, expect.any(Function))
     expect(draw.changeMode).toHaveBeenCalledWith('disabled')
     expect(mapProvider.draw).toBeNull()
     expect(mapProvider._mapboxDrawInstance).toBe(draw)

package/plugins/draw/src/adapters/maplibre/modes/drawMode/clickHandlers.test.js

@@ -229,6 +229,18 @@ describe('line mode mouse interactions', () => {
   })
 })
 
+describe('_canPlaceVertex guard', () => {
+  test('allows placement when there is no sketch feature yet (nothing to validate against)', () => {
+    const { ctx, state } = setup(DrawPolygonMode)
+    expect(ctx._canPlaceVertex({ ...state, polygon: null }, [1, 2])).toBe(true)
+  })
+
+  test('allows placement when there is no candidate point yet', () => {
+    const { ctx, state } = setup(DrawPolygonMode)
+    expect(ctx._canPlaceVertex(state, null)).toBe(true)
+  })
+})
+
 describe('onCreate (draw.create re-id)', () => {
   test('re-ids the created feature to the requested featureId', () => {
     const { ctx } = setup(DrawPolygonMode)

package/plugins/draw/src/adapters/maplibre/modes/drawMode/lifecycle.js

@@ -70,7 +70,15 @@ export const createLifecycle = ({ ParentMode, featureProp, excludeFeatureIdFromS
   onStop (state) {
     ParentMode.onStop.call(this, state)
     this._listeners.forEach(([t, e, h]) => t.removeEventListener ? t.removeEventListener(e, h) : t.off(e, h))
-    this._hideCrossHair(state)
+    // A touch/keyboard session leaving draw mode is about to land in interact mode, which
+    // needs the same crosshair to select the just-placed feature — only a mouse session (which
+    // selects by direct click) has no further use for it. onCreate's mode change to 'disabled'
+    // is itself setTimeout-deferred, landing after interactPlugin's own re-enable has already
+    // re-shown the crosshair for touch/keyboard — hiding it here unconditionally would win that
+    // race and undo it.
+    if (!['touch', 'keyboard'].includes(state.interfaceType)) {
+      this._hideCrossHair(state)
+    }
     // Sync the final interfaceType from draw mode back to app state so crosshair
     // visibility is correct when exiting draw mode (e.g., if user switched from mouse to keyboard)
     this.map.fire('draw.interfacetypechange', { interfaceType: state.interfaceType })

package/plugins/draw/src/adapters/maplibre/modes/drawMode/lifecycle.test.js

@@ -33,11 +33,11 @@ describe('setup and crosshair', () => {
 })
 
 describe('onStop', () => {
-  test('removes listeners, hides the crosshair and reports the final interface type', () => {
-    const { ctx, state, marker, container } = setup(DrawPolygonMode, { interfaceType: 'keyboard' })
+  test('mouse session: removes listeners, hides the crosshair and reports the final interface type', () => {
+    const { ctx, state, marker, container } = setup(DrawPolygonMode, { interfaceType: 'mouse' })
     ctx.onStop(state)
     expect(marker.style.display).toBe('none')
-    expect(firedWith(ctx.map, 'draw.interfacetypechange')).toEqual([{ interfaceType: 'keyboard' }])
+    expect(firedWith(ctx.map, 'draw.interfacetypechange')).toEqual([{ interfaceType: 'mouse' }])
 
     // Window/container/map listeners are gone: keydown no longer shows the crosshair
     container.focus()
@@ -45,4 +45,25 @@ describe('onStop', () => {
     expect(marker.style.display).toBe('none')
     expect(ctx.map.off).toHaveBeenCalledWith('draw.create', ctx.createHandler)
   })
+
+  // A touch/keyboard session leaving draw mode lands in interact mode, which needs the same
+  // crosshair to select the just-placed feature — unlike mouse, onStop must leave it visible.
+  test('keyboard session: still removes listeners and reports interface type, but leaves the crosshair visible', () => {
+    const { ctx, state, marker, container } = setup(DrawPolygonMode, { interfaceType: 'keyboard' })
+    ctx.onStop(state)
+    expect(marker.style.display).toBe('block')
+    expect(firedWith(ctx.map, 'draw.interfacetypechange')).toEqual([{ interfaceType: 'keyboard' }])
+    expect(ctx.map.off).toHaveBeenCalledWith('draw.create', ctx.createHandler)
+
+    container.focus()
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+    expect(marker.style.display).toBe('block')
+  })
+
+  test('touch session: leaves the crosshair visible too', () => {
+    const crossHair = { show: jest.fn(), hide: jest.fn() }
+    const { ctx, state } = setup(DrawPolygonMode, { interfaceType: 'touch', crossHair })
+    ctx.onStop(state)
+    expect(crossHair.hide).not.toHaveBeenCalled()
+  })
 })

package/plugins/draw/src/adapters/maplibre/modes/drawMode/pointerHandlers.js

@@ -17,7 +17,7 @@ export const createPointerHandlers = ({ ParentMode, getFeature, getCoords }) =>
     this.onMove(state, e)
   },
 
-  // The global interface type (e.g. switching to touch and panning via MoveControl)
+  // The global interface type (e.g. switching to touch and panning via MoveControls)
   // can change mid-session without any touch/pointer/key event ever landing on the
   // map container, so this can't rely on onTouchStart/onPointerdown alone — refresh
   // the rubber band immediately rather than waiting for the next incidental 'move'.

package/plugins/draw/src/adapters/maplibre/modes/drawMode/pointerHandlers.test.js

@@ -44,7 +44,7 @@ describe('touch and pointer interface', () => {
     expect(marker.style.display).toBe('none')
   })
 
-  test('draw.interfacetypechange (e.g. switching to touch and panning via MoveControl mid-session) updates the interface and refreshes the rubber band immediately', () => {
+  test('draw.interfacetypechange (e.g. switching to touch and panning via MoveControls mid-session) updates the interface and refreshes the rubber band immediately', () => {
     const { ctx, state } = setup(DrawPolygonMode)
     clickAt(ctx, state, 0, 0)
     ctx.map.fire('draw.interfacetypechange', { interfaceType: 'touch' })

package/plugins/draw/src/adapters/maplibre/modes/drawPointMode.js

@@ -0,0 +1,194 @@
+import MapboxDraw from '@mapbox/mapbox-gl-draw'
+import { createLifecycle } from './drawMode/lifecycle.js'
+import { validatePlacement } from '../../../validation/validateGeometry.js'
+import {
+  getSnapInstance, isSnapEnabled, isSnapActive, getSnapLngLat, triggerSnapAtPoint, triggerSnapAtCenter
+} from '../utils/snapHelpers.js'
+
+const MODE = 'draw_point'
+
+// Only these keys signal a switch to keyboard drawing (matches drawMode/createDrawMode.js's
+// INTERFACE_KEYS) — modifier keys and shortcut chords like cmd+z must not show the crosshair.
+const INTERFACE_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Enter'])
+
+// A point has no ring/rubber-band to build a candidate from — just the coordinate about to be
+// placed. Mirrors validateGeometry.js's attemptPlacement, but that helper hardcodes
+// Polygon/LineString via MODE_BY_GEOMETRY, so a Point candidate is built and validated directly.
+const canPlace = (map, coord) => {
+  const candidate = { type: 'Feature', geometry: { type: 'Point', coordinates: coord }, properties: {} }
+  const { valid, reason } = validatePlacement(
+    candidate,
+    { mode: MODE, vertexIndex: 0 },
+    { onGeometryChange: map._drawGeometryValidator }
+  )
+  if (!valid) {
+    map.fire('draw.placementblocked', { feature: candidate, reason: reason ?? null, phase: 'place', mode: MODE, vertexIndex: 0 })
+  }
+  return valid
+}
+
+const ParentMode = MapboxDraw.modes.draw_point
+
+// createLifecycle is the one createDrawMode cluster that IS reused here — its onSetup/onStop
+// are genuinely geometry-agnostic (event binding/teardown, crosshair show/hide), not coupled
+// to the ring-of-vertices shape the other clusters (clickHandlers, keyboardHandlers,
+// pointerHandlers, undoHandlers, renderHelpers) are built around. See the mode's own handlers
+// below for why those aren't reused.
+const lifecycle = createLifecycle({ ParentMode, featureProp: 'point', excludeFeatureIdFromSetup: false })
+
+const pointHandlers = {
+  // Neutralise the built-in's onKeyUp (Escape/Enter both cancel) — this mode's Escape/Enter
+  // handling lives entirely in onKeyup (lowercase, window-level) below, which fires for both
+  // keyboard-focused and mouse/touch sessions alike, so there is nothing left for the
+  // container-scoped capital-U hook to do.
+  onKeyUp () {},
+
+  _showCrossHair (state) {
+    if (state.crossHair) { state.crossHair.show() } else { state.vertexMarker.style.display = 'block' }
+  },
+
+  _hideCrossHair (state) {
+    if (state.crossHair) { state.crossHair.hide() } else { state.vertexMarker.style.display = 'none' }
+  },
+
+  _setInterface (state, type, show = true) {
+    state.interfaceType = type
+    if (show) { this._showCrossHair(state) }
+  },
+
+  // Re-id the freshly created feature to the caller's requested id — mapbox-gl-draw assigns
+  // its own id on creation, and the caller's featureId (passed through changeMode) must win.
+  // Mirrors drawMode/clickHandlers.js's reidCreatedFeature. Symbol-image resolution runs
+  // after the re-id (not before) so it writes to the feature under its final id — the
+  // resolver itself is injected by the adapter via changeMode's options so this mode has
+  // no direct dependency on symbolRegistry/mapProvider.
+  onCreate (state, e) {
+    const feature = e.features[0]
+    this._ctx.api.delete(feature.id)
+    feature.id = state.featureId
+    this._ctx.api.add(feature, { userProperties: true })
+    state.resolvePointSymbol?.(state.featureId, feature.properties)
+  },
+
+  onUndo () {}, // Nothing to undo before a single-click commit — satisfies createLifecycle's bind contract.
+  onPointerup () {}, // No vertex count to report — ditto.
+
+  // Keeps the snap indicator live at the crosshair as the map pans underneath it — the
+  // point-mode equivalent of drawMode/pointerHandlers.js's onMove, minus the rubber-band
+  // update (nothing to rubber-band for a single coordinate). Bound to MapLibre's own 'move'
+  // event by createLifecycle, so this fires continuously while panning; also called
+  // explicitly below wherever the interface type switches to touch/keyboard, so the
+  // indicator appears immediately rather than waiting for the first pan.
+  onMove (state) {
+    if (['touch', 'keyboard'].includes(state.interfaceType) && isSnapEnabled(state)) {
+      triggerSnapAtCenter(getSnapInstance(this.map), this.map)
+    }
+  },
+
+  onBlur (state, e) {
+    if (e.target !== state.container) { this._hideCrossHair(state) }
+  },
+
+  onPointerdown (state, e) {
+    if (e.pointerType !== 'touch') { this._setInterface(state, 'mouse', false) }
+  },
+
+  onPointermove (state, e) {
+    if (e.pointerType !== 'touch') { this._hideCrossHair(state) }
+  },
+
+  onTouchStart (state) { this._setInterface(state, 'touch'); this.onMove(state) },
+  onTouchEnd (state) { this._setInterface(state, 'touch'); this.onMove(state) },
+
+  onInterfaceTypeChange (state, e) {
+    this._setInterface(state, e.interfaceType, ['touch', 'keyboard'].includes(e.interfaceType))
+    this.onMove(state)
+  },
+
+  // Continuously track a snap candidate under the real cursor (mouse only — touch/keyboard
+  // placement tracks the crosshair instead, triggered once at commit time in _placeAtCrossHair).
+  onMouseMove (state, e) {
+    if (isSnapEnabled(state)) {
+      triggerSnapAtPoint(getSnapInstance(this.map), this.map, e.point)
+    }
+  },
+
+  onVertexButtonClick (state, e) {
+    if (state.addVertexButtonId && !this.map._undoInProgress && e.target.closest(`#${state.addVertexButtonId}`)) {
+      this._placeAtCrossHair(state)
+    }
+  },
+
+  onKeydown (state, e) {
+    if (document.activeElement !== state.container) { return }
+    if (e.key === 'Escape') { e.preventDefault(); return }
+    if (e.key === 'Enter') { state.isActive = true }
+    if (!INTERFACE_KEYS.has(e.key)) { return }
+    this._setInterface(state, 'keyboard')
+    this.onMove(state)
+  },
+
+  // Window-level: fires regardless of which element has focus, so mouse/touch users can
+  // Escape a pending placement without ever focusing the map, and keyboard users placing via
+  // crosshair can commit with Enter. A point has no partial ring to reinitialize the way
+  // line/polygon's Escape does, so Escape always routes to draw.cancel, keyboard-focused or not.
+  onKeyup (state, e) {
+    if (e.key === 'Escape') {
+      this.map.fire('draw.cancel')
+      return
+    }
+    if (document.activeElement !== state.container) { return }
+    if (!INTERFACE_KEYS.has(e.key)) { return }
+    this._setInterface(state, 'keyboard')
+    this.onMove(state)
+    if (e.key === 'Enter' && state.isActive) { this._placeAtCrossHair(state) }
+  },
+
+  onClick (state, e) {
+    if (e.originalEvent.button > 0 || e.originalEvent.target !== this.map.getCanvas()) { return }
+    const snap = getSnapInstance(this.map)
+    const snapped = isSnapEnabled(state) && isSnapActive(snap) ? getSnapLngLat(snap) : null
+    this._commit(state, snapped || e.lngLat)
+  },
+
+  onTap (state, e) { this.onClick(state, e) },
+
+  // Touch "Add point" button and keyboard Enter both place at the crosshair (map centre),
+  // snapping to a candidate under it if one exists. Deliberately bypasses onClick — its
+  // button/canvas-target guards are real-mouse-click-only and would reject a synthetic commit,
+  // the same reason drawMode/clickHandlers.js's doClick calls ParentMode.onClick directly
+  // rather than going through its own wrapped onClick.
+  _placeAtCrossHair (state) {
+    const snap = getSnapInstance(this.map)
+    if (isSnapEnabled(state)) { triggerSnapAtCenter(snap, this.map) }
+    const snapped = isSnapEnabled(state) && isSnapActive(snap) ? getSnapLngLat(snap) : null
+    this._commit(state, snapped || this.map.getCenter())
+    // Unlike a real click (dispatched through mapbox-gl-draw's own mode-handler loop, which
+    // re-renders automatically after every call), this runs from our own window/container
+    // listeners outside that loop, so the render has to be requested explicitly.
+    this._ctx.store.render()
+  },
+
+  // Hard gate: a vetoed placement never appears, mirroring drawMode/clickHandlers.js's
+  // _canPlaceVertex. Shared by both the real-click and crosshair-commit paths.
+  _commit (state, lngLat) {
+    if (!canPlace(this.map, [lngLat.lng, lngLat.lat])) { return }
+    state.point.updateCoordinate('', lngLat.lng, lngLat.lat)
+    this.map.fire('draw.create', { features: [state.point.toGeoJSON()] })
+  }
+}
+
+/**
+ * Draw mode for placing a single point: mouse click, or crosshair + Enter/"Add point" button
+ * for touch/keyboard. Commits immediately on the first placement — unlike draw_line/draw_polygon,
+ * there is no rubber band, no multi-vertex undo, and no "Done" step; the mode self-exits via
+ * events.js's onCreate handler once mapbox-gl-draw fires 'draw.create'.
+ *
+ * Wraps mapbox-gl-draw's own built-in draw_point mode (MapboxDraw.modes.draw_point) for
+ * onSetup/onStop/toDisplayFeatures/onTrash — it already creates and tracks the in-progress
+ * point feature, and cleans up an uncommitted one on stop. Its onClick/onTap/onKeyUp are
+ * overridden outright: the built-in has no placement-veto hook, and treats both Escape and
+ * Enter as "abandon and revert to simple_select" — this app needs Enter to place, and a
+ * cancel path that goes through draw.cancel like every other mode's does.
+ */
+export const DrawPointMode = { ...ParentMode, ...lifecycle, ...pointHandlers }