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

package/plugins/draw/src/validation/rules.js

@@ -0,0 +1,186 @@
+import turfArea from '@turf/area'
+
+/**
+ * Engine-agnostic geometry validation.
+ *
+ * A rule is a pure `(feature, context) => { valid, reason }`. Two classes:
+ *   - SOFT_RULES gate the Done button (geometryValid) — the change is always
+ *     kept, so a shape can pass through interim invalid states while being
+ *     built or reshaped.
+ *   - HARD_RULES gate vertex placement — a failure rejects the placement and
+ *     the vertex never appears (used for unrecoverable states, e.g. a vertex
+ *     that would force the drawn path to cross itself).
+ *
+ * `context` is `{ phase, vertexIndex, mode }` (phase: import('../adapterEvents.js').GeometryChangePhase)
+ * so rules can vary by phase or mode.
+ * Add a rule by appending it to SOFT_RULES or HARD_RULES.
+ */
+
+// Minimum vertices for a finishable shape — the single source for every
+// threshold check (rules, live gating, adapter finish conditions).
+export const MIN_VERTICES = { Polygon: 3, LineString: 2 }
+const MIN_INTERSECT_VERTICES = 4 // need 4+ vertices for two non-adjacent edges to exist
+
+const getGeometry = (feature) => feature?.geometry ?? feature
+const getPolygon = (feature) => {
+  const geometry = getGeometry(feature)
+  return geometry?.type === 'Polygon' ? geometry : null
+}
+
+// Distinct outer-ring vertices. Drops consecutive duplicates (zero-length edges —
+// e.g. the rubber band sitting on the just-placed vertex) which would otherwise
+// read as false intersections, then any explicit closing point so open
+// (in-progress) and closed (finished) rings are handled the same way.
+const getRingVertices = (geometry) => {
+  const raw = geometry.coordinates?.[0] ?? []
+  const ring = raw.filter((v, i) => i === 0 || v[0] !== raw[i - 1][0] || v[1] !== raw[i - 1][1])
+  while (ring.length > 1 &&
+    ring[0][0] === ring[ring.length - 1][0] &&
+    ring[0][1] === ring[ring.length - 1][1]) {
+    ring.pop()
+  }
+  return ring
+}
+
+const closeRing = (vertices) => [...vertices, vertices[0]]
+
+// Signed area of the triangle (o, a, b); sign gives orientation, zero = collinear.
+const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+
+// True when collinear point q lies within the bounding box of segment p→r.
+const onSegment = (p, q, r) =>
+  Math.min(p[0], r[0]) <= q[0] && q[0] <= Math.max(p[0], r[0]) &&
+  Math.min(p[1], r[1]) <= q[1] && q[1] <= Math.max(p[1], r[1])
+
+// True when d1 and d2 lie on opposite sides (one strictly positive, one strictly negative).
+const straddles = (d1, d2) => (d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)
+
+// True when p is collinear with the segment (d === 0) and lies on it.
+const collinearHit = (d, a, p, b) => d === 0 && onSegment(a, p, b)
+
+// True when segments (p1,p2) and (p3,p4) intersect (including collinear overlap).
+const segmentsIntersect = (p1, p2, p3, p4) => {
+  const d1 = cross(p3, p4, p1)
+  const d2 = cross(p3, p4, p2)
+  const d3 = cross(p1, p2, p3)
+  const d4 = cross(p1, p2, p4)
+
+  if (straddles(d1, d2) && straddles(d3, d4)) { return true }
+
+  return collinearHit(d1, p3, p1, p4) || collinearHit(d2, p3, p2, p4) ||
+    collinearHit(d3, p1, p3, p2) || collinearHit(d4, p1, p4, p2)
+}
+
+// Do any two non-adjacent edges cross? When `closed`, the implicit closing edge
+// (last vertex back to the first) is included; when open, only the drawn edges are
+// tested (used to reject a self-crossing vertex placement while drawing).
+const edgesSelfIntersect = (vertices, closed) => {
+  const n = vertices.length
+  const edgeCount = closed ? n : n - 1
+  for (let i = 0; i < edgeCount; i++) {
+    for (let j = i + 1; j < edgeCount; j++) {
+      const adjacent = j === i + 1 || (closed && i === 0 && j === edgeCount - 1)
+      if (adjacent) { continue }
+      if (segmentsIntersect(vertices[i], vertices[(i + 1) % n], vertices[j], vertices[(j + 1) % n])) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * HARD (draw placement): would the open drawn path cross itself? Run against the
+ * candidate path (placed vertices + the point about to be placed) — a failure
+ * rejects the placement so the vertex never appears and a genuine self-intersection
+ * can't be drawn forward.
+ */
+const pathSelfIntersects = (feature) => {
+  const geometry = getPolygon(feature)
+  if (!geometry) { return false }
+  const vertices = getRingVertices(geometry)
+  if (vertices.length < MIN_INTERSECT_VERTICES) { return false }
+  return edgesSelfIntersect(vertices, false)
+}
+
+/** Rule-shaped wrapper for pathSelfIntersects (see HARD_RULES). */
+export const noPathSelfIntersection = (feature) =>
+  pathSelfIntersects(feature)
+    ? { valid: false, reason: 'Shape must not intersect itself' }
+    : { valid: true }
+
+/**
+ * A polygon must not self-intersect. Gates Done while drawing (a would-be-crossing
+ * closing edge disables Done) and while editing.
+ */
+export const noSelfIntersection = (feature) => {
+  const geometry = getPolygon(feature)
+  if (!geometry) { return { valid: true } }
+  const vertices = getRingVertices(geometry)
+  if (vertices.length < MIN_INTERSECT_VERTICES) { return { valid: true } }
+  return edgesSelfIntersect(vertices, true)
+    ? { valid: false, reason: 'Shape must not intersect itself' }
+    : { valid: true }
+}
+
+/**
+ * A polygon must enclose a non-zero area (rejects collinear / degenerate rings).
+ */
+export const nonZeroArea = (feature) => {
+  const geometry = getPolygon(feature)
+  if (!geometry) { return { valid: true } }
+
+  const vertices = getRingVertices(geometry)
+  if (vertices.length < MIN_VERTICES.Polygon) { return { valid: true } }
+
+  let area = 0
+  try {
+    area = turfArea({ type: 'Feature', geometry: { type: 'Polygon', coordinates: [closeRing(vertices)] }, properties: {} })
+  } catch {
+    return { valid: true }
+  }
+
+  return area > 0 ? { valid: true } : { valid: false, reason: 'Shape must enclose an area' }
+}
+
+// minVertices' own reason strings, exported so callers (events.js's hint toast)
+// can recognise "still being built" as distinct from a genuine rule violation —
+// unlike self-intersection/zero-area/a custom onGeometryChange veto, an
+// incomplete shape isn't a mistake worth interrupting the user over.
+export const MIN_VERTICES_REASONS = {
+  Polygon: 'Shape needs at least 3 points',
+  LineString: 'Line needs at least 2 points'
+}
+
+/**
+ * A shape needs enough vertices to be finishable (3 for a polygon, 2 for a line).
+ */
+export const minVertices = (feature) => {
+  const geometry = getGeometry(feature)
+  if (geometry?.type === 'Polygon') {
+    return getRingVertices(geometry).length >= MIN_VERTICES.Polygon
+      ? { valid: true }
+      : { valid: false, reason: MIN_VERTICES_REASONS.Polygon }
+  }
+  if (geometry?.type === 'LineString') {
+    return (geometry.coordinates?.length ?? 0) >= MIN_VERTICES.LineString
+      ? { valid: true }
+      : { valid: false, reason: MIN_VERTICES_REASONS.LineString }
+  }
+  return { valid: true }
+}
+
+// Validation rules. A failure disables the Done button (geometryValid).
+// Order sets which reason surfaces first.
+export const SOFT_RULES = [noSelfIntersection, nonZeroArea, minVertices]
+
+// Rules that drive the live invalid stroke while drawing, run against the displayed
+// geometry (placed vertices + cursor) on every rubber-band move. Everything soft
+// EXCEPT minVertices — an incomplete shape is "part-drawn", not invalid.
+// validateDisplayedGeometry applies the minimum-placed-vertex threshold instead.
+export const LIVE_RULES = [noSelfIntersection, nonZeroArea]
+
+// Placement rules. Run by validatePlacement against the candidate geometry
+// (placed vertices + the point about to be placed); a failure rejects the
+// placement outright — the vertex never appears.
+export const HARD_RULES = [noPathSelfIntersection]

package/plugins/draw/src/validation/rules.test.js

@@ -0,0 +1,120 @@
+import { noSelfIntersection, nonZeroArea, minVertices, noPathSelfIntersection, SOFT_RULES, HARD_RULES, MIN_VERTICES_REASONS } from './rules.js'
+
+const poly = (coordinates) => ({ type: 'Feature', geometry: { type: 'Polygon', coordinates: [coordinates] } })
+const line = (coordinates) => ({ type: 'Feature', geometry: { type: 'LineString', coordinates } })
+
+describe('noSelfIntersection', () => {
+  test('rejects a closed self-intersecting polygon', () => {
+    expect(noSelfIntersection(poly([[0, 0], [1, 1], [1, 0], [0, 1], [0, 0]])).valid).toBe(false)
+  })
+
+  test('rejects a shape whose closing edge crosses another edge', () => {
+    expect(noSelfIntersection(poly([[0, 0], [2, 0], [0, 2], [2, 2]])).valid).toBe(false)
+  })
+
+  test('detects a T-touch (collinear) crossing', () => {
+    // Edge (1,0)-(1,2) starts on the earlier edge (0,0)-(3,0): a collinear/touch hit.
+    expect(noSelfIntersection(poly([[0, 0], [3, 0], [1, 0], [1, 2]])).valid).toBe(false)
+  })
+
+  test('accepts a simple polygon', () => {
+    expect(noSelfIntersection(poly([[0, 0], [2, 0], [2, 2], [0, 2], [0, 0]]))).toEqual({ valid: true })
+  })
+
+  test('skips non-polygons and short rings', () => {
+    expect(noSelfIntersection(line([[0, 0], [1, 1]]))).toEqual({ valid: true })
+    expect(noSelfIntersection(poly([[0, 0], [1, 1], [1, 0]]))).toEqual({ valid: true })
+  })
+})
+
+describe('nonZeroArea (soft)', () => {
+  test('rejects a collinear (zero-area) ring', () => {
+    const result = nonZeroArea(poly([[0, 0], [1, 0], [2, 0]]))
+    expect(result.valid).toBe(false)
+    expect(result.reason).toMatch(/area/i)
+  })
+
+  test('accepts a ring with area', () => {
+    expect(nonZeroArea(poly([[0, 0], [1, 0], [1, 1]]))).toEqual({ valid: true })
+  })
+
+  test('skips non-polygons and rings under three vertices', () => {
+    expect(nonZeroArea(line([[0, 0], [1, 1]]))).toEqual({ valid: true })
+    expect(nonZeroArea(poly([[0, 0], [1, 0]]))).toEqual({ valid: true })
+  })
+  // The defensive catch (a turf failure → skip) is covered in rules.areaError.test.js,
+  // which needs a file-level @turf/area mock that must not affect the real-area tests here.
+})
+
+describe('minVertices (soft)', () => {
+  test('requires three points for a polygon', () => {
+    expect(minVertices(poly([[0, 0], [1, 0]])).valid).toBe(false)
+    expect(minVertices(poly([[0, 0], [1, 0], [1, 1]]))).toEqual({ valid: true })
+  })
+
+  // events.js's hint toast recognises MIN_VERTICES_REASONS to skip hinting on an
+  // incomplete (still-being-drawn) shape — these must stay the actual reasons used.
+  test('uses the exported MIN_VERTICES_REASONS text', () => {
+    expect(minVertices(poly([[0, 0], [1, 0]])).reason).toBe(MIN_VERTICES_REASONS.Polygon)
+    expect(minVertices(line([[0, 0]])).reason).toBe(MIN_VERTICES_REASONS.LineString)
+  })
+
+  test('counts a closed ring by its distinct vertices', () => {
+    expect(minVertices(poly([[0, 0], [1, 0], [1, 1], [0, 0]]))).toEqual({ valid: true })
+  })
+
+  test('requires two points for a line', () => {
+    expect(minVertices(line([[0, 0]])).valid).toBe(false)
+    expect(minVertices(line([[0, 0], [1, 1]]))).toEqual({ valid: true })
+  })
+
+  test('skips geometry that is neither a polygon nor a line', () => {
+    expect(minVertices({ geometry: { type: 'Point', coordinates: [0, 0] } })).toEqual({ valid: true })
+  })
+})
+
+describe('noPathSelfIntersection (hard, draw placement)', () => {
+  test('rejects a self-crossing open drawn path with a reason', () => {
+    expect(noPathSelfIntersection(poly([[0, 0], [2, 2], [2, 0], [0, 2]])))
+      .toEqual({ valid: false, reason: expect.stringMatching(/intersect/i) })
+  })
+
+  test('accepts an open path that only closes into a crossing', () => {
+    // A bow-tie only crosses via its closing edge, which the open-path check ignores.
+    expect(noPathSelfIntersection(poly([[0, 0], [2, 0], [0, 2], [2, 2]]))).toEqual({ valid: true })
+  })
+
+  test('accepts a simple open path', () => {
+    expect(noPathSelfIntersection(poly([[0, 0], [2, 0], [2, 2], [0, 2]]))).toEqual({ valid: true })
+  })
+
+  test('skips non-polygons and paths under four vertices', () => {
+    expect(noPathSelfIntersection(line([[0, 0], [1, 1]]))).toEqual({ valid: true })
+    expect(noPathSelfIntersection(poly([[0, 0], [1, 0], [1, 1]]))).toEqual({ valid: true })
+  })
+})
+
+describe('consecutive duplicate vertices (zero-length edges)', () => {
+  test('a rubber band sitting on the just-placed vertex is not an intersection', () => {
+    // 3 placed + duplicate rubber-band coord + closing point — the in-progress
+    // ring layout the instant after a vertex is placed.
+    expect(noSelfIntersection(poly([[0, 0], [10, 0], [10, 10], [10, 10], [0, 0]])))
+      .toEqual({ valid: true })
+  })
+
+  test('a real crossing is still detected when a duplicate vertex is present', () => {
+    expect(noSelfIntersection(poly([[0, 0], [1, 1], [1, 1], [1, 0], [0, 1], [0, 0]])).valid).toBe(false)
+  })
+})
+
+describe('SOFT_RULES', () => {
+  test('are the gating rules in reason-priority order', () => {
+    expect(SOFT_RULES).toEqual([noSelfIntersection, nonZeroArea, minVertices])
+  })
+})
+
+describe('HARD_RULES', () => {
+  test('are the placement-veto rules', () => {
+    expect(HARD_RULES).toEqual([noPathSelfIntersection])
+  })
+})

package/plugins/draw/src/validation/validateGeometry.js

@@ -0,0 +1,119 @@
+import { SOFT_RULES, HARD_RULES, LIVE_RULES, MIN_VERTICES } from './rules.js'
+
+/**
+ * Normalise a rule / callback result into `{ valid, reason }`.
+ *
+ * Supports three return shapes so a user `onGeometryChange` callback can stay
+ * terse:
+ *   - `true`  / `undefined`  → valid
+ *   - `false`                → invalid (no reason)
+ *   - `{ valid, reason }`    → passed through
+ */
+const normaliseResult = (result) => {
+  if (result === undefined || result === true) { return { valid: true } }
+  if (result === false) { return { valid: false, reason: null } }
+  return { valid: result.valid !== false, reason: result.reason }
+}
+
+/**
+ * Validate an in-progress geometry against the default rules and an optional user
+ * callback. Rules run first and short-circuit on the first failure; the callback
+ * runs last. Gates the Done button only — never reverts a vertex change.
+ *
+ * @param {object} feature - current GeoJSON feature
+ * @param {object} context - { phase: import('../adapterEvents.js').GeometryChangePhase, vertexIndex, mode }
+ * @param {object} [config]
+ * @param {Array<Function>} [config.rules] - defaults to DEFAULT_RULES; called as rule(feature, context)
+ * @param {function(import('../adapterEvents.js').GeometryChangeEvent): (boolean|{valid: boolean, reason?: string}|undefined)} [config.onGeometryChange]
+ *   - user callback, called as onGeometryChange({ feature, ...context }) — a single
+ *   event object, unlike the internal rules above, matching the shape of the
+ *   PLACEMENT_BLOCKED adapter event
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export const validateGeometry = (feature, context = {}, config = {}) => {
+  const { rules = SOFT_RULES, onGeometryChange } = config
+
+  for (const rule of rules) {
+    const result = normaliseResult(rule(feature, context))
+    if (!result.valid) { return result }
+  }
+
+  if (typeof onGeometryChange === 'function') {
+    return normaliseResult(onGeometryChange({ feature, ...context }))
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Validate a candidate vertex placement against the hard rules and the same
+ * optional user callback. A failure means the vertex is rejected outright and
+ * never appears. The callback receives `context.phase === 'place'`.
+ *
+ * @param {object} feature - candidate GeoJSON feature (placed vertices + new point)
+ * @param {object} context - { vertexIndex, mode }; phase is forced to 'place'
+ * @param {object} [config]
+ * @param {Array<Function>} [config.rules] - defaults to HARD_RULES
+ * @param {function(import('../adapterEvents.js').GeometryChangeEvent): (boolean|{valid: boolean, reason?: string}|undefined)} [config.onGeometryChange] - user callback
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export const validatePlacement = (feature, context = {}, config = {}) => {
+  const { rules = HARD_RULES, onGeometryChange } = config
+  return validateGeometry(feature, { ...context, phase: 'place' }, { rules, onGeometryChange })
+}
+
+export const MODE_BY_GEOMETRY = { Polygon: 'draw_polygon', LineString: 'draw_line' }
+
+/**
+ * Attempt to place a vertex — shared by both adapters. Builds the candidate
+ * geometry, validates it, and on a veto returns the PLACEMENT_BLOCKED payload
+ * for the caller to emit.
+ *
+ * @param {object} params
+ * @param {Array<Array<number>>} params.placed - committed vertex coordinates
+ * @param {Array<number>} params.point - the coordinate about to be placed
+ * @param {'Polygon'|'LineString'} params.geometryType
+ * @param {function(import('../adapterEvents.js').GeometryChangeEvent): (boolean|{valid: boolean, reason?: string}|undefined)} [params.onGeometryChange] - user callback
+ * @returns {{ valid: true } | { valid: false, blocked: object }}
+ */
+export const attemptPlacement = ({ placed, point, geometryType, onGeometryChange }) => {
+  const candidate = [...placed, point]
+  const geometry = geometryType === 'Polygon'
+    ? { type: 'Polygon', coordinates: [candidate] }
+    : { type: 'LineString', coordinates: candidate }
+  const feature = { type: 'Feature', geometry, properties: {} }
+  const mode = MODE_BY_GEOMETRY[geometryType]
+  const { valid, reason } = validatePlacement(feature, { mode, vertexIndex: placed.length }, { onGeometryChange })
+  if (valid) { return { valid: true } }
+  return { valid: false, blocked: { feature, reason: reason ?? null, phase: 'place', mode, vertexIndex: placed.length } }
+}
+
+/**
+ * Validate the displayed (in-progress) geometry that drives the live invalid
+ * stroke: the placed vertices plus the current cursor point. The built-in live
+ * rules (self-intersection/area) are meaningless below the geometry type's
+ * minimum vertex count — there isn't a real ring/line yet — so they're skipped
+ * entirely until then; a caller's own `onGeometryChange` has no such floor
+ * (numVertices defaults to 0 via `context.numVertices ?? 0`, so it still runs).
+ *
+ * Used directly by edit mode's live-stroke check (there's no Add-point gate to
+ * combine with there, so it's a self-contained call). Draw mode does NOT use
+ * this — see liveDrawChecks.js, which combines this same LIVE_RULES set with a
+ * separate HARD_RULES-based placement check, both driven from a single shared
+ * `onGeometryChange` call rather than one call each.
+ *
+ * @param {object} feature - displayed GeoJSON feature (placed vertices + cursor)
+ * @param {object} context - { mode, numVertices, phase }; phase defaults to 'preview'
+ * @param {object} [config]
+ * @param {Array<Function>} [config.rules] - defaults to LIVE_RULES
+ * @param {function(import('../adapterEvents.js').GeometryChangeEvent): (boolean|{valid: boolean, reason?: string}|undefined)} [config.onGeometryChange] - user callback
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export const validateDisplayedGeometry = (feature, context = {}, config = {}) => {
+  const { rules = LIVE_RULES, onGeometryChange } = config
+  const type = feature?.geometry?.type ?? feature?.type
+  const min = MIN_VERTICES[type] ?? 0
+  const numVertices = context.numVertices ?? 0
+  const effectiveRules = numVertices < min ? [] : rules
+  return validateGeometry(feature, { ...context, phase: context.phase ?? 'preview' }, { rules: effectiveRules, onGeometryChange })
+}

package/plugins/draw/src/validation/validateGeometry.test.js

@@ -0,0 +1,200 @@
+import { validateGeometry, validatePlacement, attemptPlacement, validateDisplayedGeometry } from './validateGeometry.js'
+
+const poly = (coordinates) => ({ type: 'Feature', geometry: { type: 'Polygon', coordinates: [coordinates] } })
+
+const square = poly([[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]])
+const bowtie = poly([[0, 0], [1, 1], [1, 0], [0, 1], [0, 0]])
+const collinear = poly([[0, 0], [1, 0], [2, 0], [0, 0]])
+const twoPoints = poly([[0, 0], [1, 0]])
+
+describe('validateGeometry (soft gating)', () => {
+  test('a valid polygon passes', () => {
+    expect(validateGeometry(square)).toEqual({ valid: true })
+  })
+
+  test('a self-intersecting polygon fails', () => {
+    const result = validateGeometry(bowtie)
+    expect(result.valid).toBe(false)
+    expect(result.reason).toMatch(/intersect/i)
+  })
+
+  test('a zero-area polygon fails', () => {
+    expect(validateGeometry(collinear).reason).toMatch(/area/i)
+  })
+
+  test('too few vertices fails', () => {
+    expect(validateGeometry(twoPoints).reason).toMatch(/points/i)
+  })
+
+  test('short-circuits on the first failing rule', () => {
+    const first = jest.fn(() => ({ valid: false, reason: 'first' }))
+    const second = jest.fn(() => ({ valid: true }))
+    expect(validateGeometry(square, {}, { rules: [first, second] })).toEqual({ valid: false, reason: 'first' })
+    expect(second).not.toHaveBeenCalled()
+  })
+
+  test('passes the context to rules as (feature, context), and to the callback as a single flattened event object', () => {
+    const rule = jest.fn(() => ({ valid: true }))
+    const onGeometryChange = jest.fn(() => ({ valid: true }))
+    const context = { phase: 'commit-move', vertexIndex: 2, mode: 'edit_vertex' }
+    validateGeometry(square, context, { rules: [rule], onGeometryChange })
+    expect(rule).toHaveBeenCalledWith(square, context)
+    expect(onGeometryChange).toHaveBeenCalledWith({ feature: square, ...context })
+  })
+
+  test('runs the user callback after the rules pass', () => {
+    expect(validateGeometry(square, {}, { rules: [], onGeometryChange: () => false }))
+      .toEqual({ valid: false, reason: null })
+    expect(validateGeometry(square, {}, { rules: [], onGeometryChange: () => true }))
+      .toEqual({ valid: true })
+    expect(validateGeometry(square, {}, { rules: [], onGeometryChange: () => ({ valid: false, reason: 'too big' }) }))
+      .toEqual({ valid: false, reason: 'too big' })
+  })
+
+  test('does not run the callback when a rule fails', () => {
+    const onGeometryChange = jest.fn()
+    validateGeometry(square, {}, { rules: [() => ({ valid: false })], onGeometryChange })
+    expect(onGeometryChange).not.toHaveBeenCalled()
+  })
+
+  test('is valid with no rules and no callback', () => {
+    expect(validateGeometry(square, {}, { rules: [] })).toEqual({ valid: true })
+  })
+})
+
+describe('attemptPlacement (shared engine gate)', () => {
+  const placedL = [[0, 0], [1, 1], [1, 0]] // adding (0,1) makes the open path cross
+
+  test('a legal placement passes with no payload', () => {
+    expect(attemptPlacement({ placed: [[0, 0], [1, 0], [1, 1]], point: [0, 1], geometryType: 'Polygon' }))
+      .toEqual({ valid: true })
+  })
+
+  test('a self-crossing placement is vetoed with the PLACEMENT_BLOCKED payload', () => {
+    const result = attemptPlacement({ placed: placedL, point: [0, 1], geometryType: 'Polygon' })
+    expect(result.valid).toBe(false)
+    expect(result.blocked).toEqual({
+      feature: expect.objectContaining({ type: 'Feature' }),
+      reason: expect.stringMatching(/intersect/i),
+      phase: 'place',
+      mode: 'draw_polygon',
+      vertexIndex: 3
+    })
+  })
+
+  test('the user callback can veto, with mode derived from the geometry type', () => {
+    const onGeometryChange = jest.fn(() => ({ valid: false, reason: 'outside region' }))
+    const result = attemptPlacement({ placed: [[0, 0]], point: [1, 1], geometryType: 'LineString', onGeometryChange })
+    expect(result.blocked).toEqual(expect.objectContaining({ mode: 'draw_line', reason: 'outside region', vertexIndex: 1 }))
+    expect(onGeometryChange).toHaveBeenCalledWith(expect.objectContaining({ phase: 'place', mode: 'draw_line', vertexIndex: 1 }))
+  })
+
+  test('a veto with no reason falls back to null in the PLACEMENT_BLOCKED payload', () => {
+    const onGeometryChange = jest.fn(() => false) // false → invalid, no reason (see normaliseResult)
+    const result = attemptPlacement({ placed: [[0, 0]], point: [1, 1], geometryType: 'LineString', onGeometryChange })
+    expect(result.blocked.reason).toBeNull()
+  })
+
+  test('attemptPlacement mode is set correctly for Polygon vs LineString', () => {
+    // Both legal and illegal placements should have the correct mode set
+    const polygonLegal = attemptPlacement({ placed: [[0, 0], [1, 0]], point: [1, 1], geometryType: 'Polygon' })
+    expect(polygonLegal).toEqual({ valid: true })
+    // Test a Polygon placement that would cross
+    const polygonCrossing = attemptPlacement({ placed: [[0, 0], [2, 2], [2, 0]], point: [0, 2], geometryType: 'Polygon' })
+    expect(polygonCrossing.blocked?.mode).toBe('draw_polygon')
+  })
+})
+
+describe('validateDisplayedGeometry edge cases', () => {
+  test('handles unknown geometry types with fallback min vertices', () => {
+    const result = validateDisplayedGeometry({ type: 'Feature', geometry: { type: 'Unknown', coordinates: [] } }, { numVertices: 0 })
+    expect(result.valid).toBe(true) // unknown types use MIN_VERTICES fallback of 0, so 0 placed = valid
+  })
+
+  test('feature without geometry type defaults to context.phase', () => {
+    const result = validateDisplayedGeometry({ type: 'Feature', geometry: { coordinates: [[0, 0]] } }, { numVertices: 2, phase: 'custom' })
+    expect(typeof result).toBe('object')
+    expect(result).toHaveProperty('valid')
+  })
+
+  test('context without numVertices defaults to 0 for min-vertex check', () => {
+    const result = validateDisplayedGeometry(poly([[0, 0]]), {})
+    expect(result.valid).toBe(true) // no numVertices = 0, below any min, so valid
+  })
+
+  test('context and config are both optional — called with just a feature', () => {
+    expect(validateDisplayedGeometry(poly([[0, 0]]))).toEqual({ valid: true })
+  })
+
+  test('calls the caller\'s own onGeometryChange once at/above the vertex threshold, with a single flattened event object', () => {
+    const onGeometryChange = jest.fn(() => ({ valid: false, reason: 'too few for my rule' }))
+    // Polygon minimum is 3 placed vertices — this feature/numVertices pair is at it.
+    const feature = poly([[0, 0], [1, 0], [1, 1]])
+
+    const result = validateDisplayedGeometry(feature, { numVertices: 3 }, { onGeometryChange })
+
+    expect(onGeometryChange).toHaveBeenCalledWith(expect.objectContaining({ feature, numVertices: 3, phase: 'preview' }))
+    expect(result).toEqual({ valid: false, reason: 'too few for my rule' })
+  })
+
+  test('skips the built-in rules with zero committed vertices, but still runs the caller\'s onGeometryChange — a location-based rule is meaningful against the very first candidate point', () => {
+    const failingRule = jest.fn(() => ({ valid: false, reason: 'should not run' }))
+    const onGeometryChange = jest.fn(() => ({ valid: false, reason: 'outside region' }))
+    const feature = poly([[0, 0]])
+
+    const result = validateDisplayedGeometry(feature, { numVertices: 0 }, { rules: [failingRule], onGeometryChange })
+
+    expect(failingRule).not.toHaveBeenCalled()
+    expect(onGeometryChange).toHaveBeenCalledWith(expect.objectContaining({ feature, numVertices: 0, phase: 'preview' }))
+    expect(result).toEqual({ valid: false, reason: 'outside region' })
+  })
+
+  test('runs the caller\'s onGeometryChange from the first committed vertex, even while the built-in rules are still skipped', () => {
+    const failingRule = jest.fn(() => ({ valid: false, reason: 'should not run' }))
+    // A single committed vertex — well below the Polygon minimum of 3 — so the
+    // built-in self-intersection/area rules stay skipped, but a per-point user
+    // rule (e.g. "is this inside a region?") is meaningful and should still run.
+    const onGeometryChange = jest.fn(() => ({ valid: false, reason: 'outside region' }))
+    const feature = poly([[0, 0], [1, 1]])
+
+    const result = validateDisplayedGeometry(feature, { numVertices: 1 }, { rules: [failingRule], onGeometryChange })
+
+    expect(failingRule).not.toHaveBeenCalled()
+    expect(onGeometryChange).toHaveBeenCalledWith(expect.objectContaining({ feature, numVertices: 1, phase: 'preview' }))
+    expect(result).toEqual({ valid: false, reason: 'outside region' })
+  })
+})
+
+describe('validatePlacement (hard gating)', () => {
+  // The candidate is the open drawn path plus the point about to be placed.
+  const crossingPath = poly([[0, 0], [1, 1], [1, 0], [0, 1]])
+  const simplePath = poly([[0, 0], [1, 0], [1, 1], [0, 1]])
+
+  test('rejects a candidate whose open path self-crosses, with a reason', () => {
+    const result = validatePlacement(crossingPath)
+    expect(result.valid).toBe(false)
+    expect(result.reason).toMatch(/intersect/i)
+  })
+
+  test('passes a simple candidate', () => {
+    expect(validatePlacement(simplePath)).toEqual({ valid: true })
+  })
+
+  test('forces phase "place" into the rule and callback context', () => {
+    const onGeometryChange = jest.fn(() => true)
+    validatePlacement(simplePath, { mode: 'draw_polygon', vertexIndex: 4 }, { onGeometryChange })
+    expect(onGeometryChange).toHaveBeenCalledWith({ feature: simplePath, phase: 'place', mode: 'draw_polygon', vertexIndex: 4 })
+  })
+
+  test('the user callback can veto a placement with a reason', () => {
+    const onGeometryChange = () => ({ valid: false, reason: 'outside region' })
+    expect(validatePlacement(simplePath, {}, { onGeometryChange }))
+      .toEqual({ valid: false, reason: 'outside region' })
+  })
+
+  test('hard rules run before the user callback', () => {
+    const onGeometryChange = jest.fn()
+    validatePlacement(crossingPath, {}, { onGeometryChange })
+    expect(onGeometryChange).not.toHaveBeenCalled()
+  })
+})