@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/map/useMapDraw.ts

@@ -0,0 +1,776 @@
+// Drawing on the map — author a boundary and hand back GeoJSON.
+//
+//   const tool = ref<DrawTool>('off')
+//   const draw = useMapDraw(map, () => ({ tool: tool.value }))
+//   <FMapDrawTools v-model:tool="tool" :drafting="!!draw.draft.value" @finish="draw.finish" @cancel="draw.cancel" />
+//
+// ★ IT OWNS THE FEATURES IT DRAWS, and it paints them. `features` is the source of truth while the
+// editor is open, which means a surface that also paints those polygons — a zone overlay, say — hands
+// them over with `load()` and stops painting them itself for as long as it is editing. Two pipelines
+// over one set of polygons is how a shape ends up drawn twice in two colours, one of them stale.
+//
+// ★ THE SHAPE IS PAINTED IN THE DRAW COLOUR, NOT ITS OWN. A ring under the cursor has no kind yet, and
+// the ones beside it are being compared against it, so authoring is a MODE the whole set is in rather
+// than a property of one feature. What a zone means is decided after it exists.
+//
+// ★ EVERY DRAW LAYER IS UNSLOTTED, so it paints above every layer in the style. Handles a mark can
+// cover are handles a reader cannot grab. The globe caveat on MARK_CLAIMS_SPACE applies — an unslotted
+// layer lands below the labels under the globe projection — and a city map never reaches those zooms.
+//
+// ★ THE GESTURE DISCIPLINE IS REGION SELECT'S, measured against the same GL JS. An armed tool holds
+// dragPan, boxZoom, dragRotate and doubleClickZoom off for as long as it is armed rather than for the
+// duration of a drag, pointer capture keeps a drag alive when it leaves the canvas, and the click a
+// completed drag emits is swallowed before GL JS can turn it into a map click. See useRegionSelect for
+// what each of those cost to learn.
+import { computed, onScopeDispose, ref, shallowRef, watch, type ShallowRef } from 'vue';
+import booleanPointInPolygon from '@turf/boolean-point-in-polygon';
+import { point as turfPoint, polygon as turfPolygon } from '@turf/helpers';
+import type { Map as MapboxMap } from 'mapbox-gl';
+import { token, useMapOverlay, type OverlayLayer } from './useMapOverlay';
+import type { LngLat } from './coordinates';
+import type { ScreenPoint } from './regionSelect';
+import {
+  boxCorners,
+  closeRing,
+  drawFeatureToGeoJSON,
+  geodesicRing,
+  historyOf,
+  insertVertex,
+  metresBetween,
+  midpoints,
+  moveVertex,
+  pushHistory,
+  redoHistory,
+  removeVertex,
+  ringProblem,
+  nearestWithin,
+  snapVertices,
+  undoHistory,
+  worthDrawing,
+  type DrawFeature,
+  type DrawHistory,
+  type DrawProblem,
+  type DrawRing,
+  type DrawTool,
+} from './draw';
+
+export interface MapDrawOptions {
+  /** what a drag does. `off` pans the map, and is the only tool that does */
+  tool?: DrawTool;
+  /** land a new vertex exactly on an existing one when it is within reach. Default true */
+  snap?: boolean;
+  /** a hard stop for a read-only map — no tool draws, whatever is armed */
+  disabled?: boolean;
+  /** fires on every committed change, with the whole set. Persistence is the caller's business */
+  onChange?: (features: DrawFeature[]) => void;
+}
+
+/**
+ * How near the pointer has to be to a handle to grab it, in px.
+ *
+ * Wider than the handle is drawn (5px radius) and wider than the snap radius, because grabbing is the
+ * one interaction with no second chance: a miss does not select the vertex behind, it starts a
+ * different gesture entirely — on a body drag, it moves the whole shape.
+ */
+const HANDLE_HIT_PX = 12;
+
+/** A double click, as this module measures one: two presses close together in time and in space. */
+const DOUBLE_CLICK_MS = 350;
+const DOUBLE_CLICK_PX = 8;
+
+const SOURCE_SHAPE = 'forest-draw-shape';
+const SOURCE_HANDLE = 'forest-draw-handle';
+
+/** Ids are sequential rather than random so a test can predict them and a diff can be read. */
+let sequence = 0;
+const nextId = () => `draw-${++sequence}`;
+
+type Drag =
+  | { kind: 'box'; from: ScreenPoint }
+  | { kind: 'circle'; centre: ScreenPoint }
+  | { kind: 'vertex'; id: string; index: number }
+  | { kind: 'body'; id: string; from: LngLat }
+  | null;
+
+export function useMapDraw(map: ShallowRef<MapboxMap | null>, options: () => MapDrawOptions) {
+  const features = shallowRef<DrawFeature[]>([]);
+  /** the ring being placed a vertex at a time, before it closes */
+  const draft = shallowRef<DrawRing | null>(null);
+  /** where the pointer is, so an open draft can rubber-band to it. Null on touch, which never hovers */
+  const cursor = shallowRef<LngLat | null>(null);
+  /** the shape a rectangle or circle drag is describing right now */
+  const preview = shallowRef<DrawRing | null>(null);
+  const selectedId = ref<string | null>(null);
+  /** a circle drag's ground radius, so a control can say how big it is */
+  const radius = ref<number | null>(null);
+
+  let history: DrawHistory<DrawFeature[]> = historyOf<DrawFeature[]>([]);
+  const canUndo = ref(false);
+  const canRedo = ref(false);
+  const syncHistoryFlags = () => {
+    canUndo.value = history.past.length > 0 || !!draft.value;
+    canRedo.value = history.future.length > 0;
+  };
+
+  let drag: Drag = null;
+  let pressedAt: ScreenPoint | null = null;
+  let lastPress = { at: [0, 0] as ScreenPoint, time: 0 };
+
+  const tool = () => options().tool ?? 'off';
+  const armed = () => !options().disabled && tool() !== 'off';
+
+  /** The ring under the cursor: a draft, a live preview, or the selected feature in edit. */
+  const activeRing = computed<DrawRing | null>(() => {
+    if (draft.value) return draft.value;
+    if (preview.value) return preview.value;
+    const id = selectedId.value;
+    return id ? (features.value.find((f) => f.id === id)?.ring ?? null) : null;
+  });
+
+  /**
+   * Why the shape under the cursor cannot be committed, or null.
+   *
+   * ★ A draft of two vertices is not a problem, it is an unfinished sentence. `too-few` only reads as
+   * an error once the reader asks to finish, so an open draft below three vertices reports nothing and
+   * `finish()` is what refuses.
+   */
+  const problem = computed<DrawProblem | null>(() => {
+    const ring = activeRing.value;
+    if (!ring) return null;
+    if (draft.value && ring.length < 3) return null;
+    return ringProblem(ring);
+  });
+
+  const invalid = computed(() => problem.value !== null);
+
+  function emit(next: DrawFeature[]) {
+    features.value = next;
+    options().onChange?.(next);
+  }
+
+  /** Commit a change to the set, with an undo step. Every mutation that outlives a drag goes here. */
+  function commit(next: DrawFeature[]) {
+    history = pushHistory(history, next);
+    syncHistoryFlags();
+    emit(next);
+  }
+
+  function replaceRing(id: string, ring: DrawRing) {
+    emit(features.value.map((f) => (f.id === id ? { ...f, ring } : f)));
+  }
+
+  function addFeature(ring: DrawRing) {
+    if (ringProblem(ring)) return null;
+    const feature: DrawFeature = { id: nextId(), ring };
+    commit([...features.value, feature]);
+    selectedId.value = feature.id;
+    return feature;
+  }
+
+  // ── geometry ⇄ screen ────────────────────────────────────────────────────────────────────────────
+  const canvasPoint = (m: MapboxMap, e: PointerEvent): ScreenPoint => {
+    const r = m.getCanvas().getBoundingClientRect();
+    return [e.clientX - r.left, e.clientY - r.top];
+  };
+  const toLngLat = (m: MapboxMap, p: ScreenPoint): LngLat => {
+    const { lng, lat } = m.unproject(p);
+    return [lng, lat];
+  };
+  const toScreen = (m: MapboxMap, p: LngLat): ScreenPoint => {
+    const { x, y } = m.project(p);
+    return [x, y];
+  };
+
+  /**
+   * Every vertex a corner may land on, projected — the other features', and the draft's own.
+   *
+   * ★ Recomputed per call, which on a vertex drag means once per pointermove. That is a `project()`
+   * per candidate vertex per frame, and `project()` is a matrix multiply: a console with fifty zones
+   * of twenty corners costs a thousand of them, well under a frame. It stops being free at an order
+   * of magnitude more, and the fix then is a spatial index rather than a cache, since the whole set
+   * reprojects on every camera move anyway.
+   */
+  function snapCandidates(m: MapboxMap, exclude?: string): { at: ScreenPoint; lngLat: LngLat }[] {
+    const out = snapVertices(features.value, exclude).map((v) => ({ at: toScreen(m, v), lngLat: v }));
+    for (const v of draft.value ?? []) out.push({ at: toScreen(m, v), lngLat: v });
+    return out;
+  }
+
+  /**
+   * Where a corner actually lands — used for both placing one and dragging one.
+   *
+   * ★ Snapping is to an EXISTING POSITION, not to a rounded one. Two zones that share a boundary must
+   * share the coordinates of it exactly, or they leave a hairline gap that no one sees on the map and
+   * a point-in-polygon test finds every time.
+   *
+   * ★ AND IT HAS TO COVER THE DRAG, not just the click. Placing a corner on a neighbour is the tidy
+   * case; the one an operator actually reaches for is picking up a corner that is nearly right and
+   * putting it on its neighbour. A snap that only fired while drawing would leave the commonest path
+   * to a shared boundary as the one path that cannot produce one.
+   */
+  function place(m: MapboxMap, at: ScreenPoint, exclude?: string): LngLat {
+    const raw = toLngLat(m, at);
+    if (options().snap === false) return raw;
+    const candidates = snapCandidates(m, exclude);
+    const hit = nearestWithin(
+      candidates.map((c) => c.at),
+      at,
+    );
+    return hit == null ? raw : candidates[hit].lngLat;
+  }
+
+  // ── the draft ────────────────────────────────────────────────────────────────────────────────────
+  const apart = (a: ScreenPoint, b: ScreenPoint): number => Math.hypot(a[0] - b[0], a[1] - b[1]);
+
+  function placeVertex(m: MapboxMap, at: ScreenPoint) {
+    const ring = draft.value;
+    const next = place(m, at);
+    if (!ring) {
+      draft.value = [next];
+      syncHistoryFlags();
+      return;
+    }
+    // Clicking the first vertex closes the ring — the gesture every drawing tool has, and the reason
+    // the draft's own vertices are snap candidates.
+    if (ring.length >= 3 && apart(toScreen(m, ring[0]), at) <= HANDLE_HIT_PX) {
+      finish();
+      return;
+    }
+    draft.value = [...ring, next];
+    syncHistoryFlags();
+  }
+
+  function dropLastVertex() {
+    const ring = draft.value;
+    if (!ring) return;
+    const next = ring.slice(0, -1);
+    draft.value = next.length ? next : null;
+    syncHistoryFlags();
+  }
+
+  /** Close the draft into a feature. Refuses a ring that is not a polygon, and says so by doing nothing. */
+  function finish() {
+    const ring = draft.value;
+    if (!ring || ringProblem(ring)) return;
+    draft.value = null;
+    cursor.value = null;
+    addFeature(ring);
+  }
+
+  /** Escape's job: abandon the draft first, and only then let go of the selection. */
+  function cancel() {
+    if (draft.value) {
+      draft.value = null;
+      cursor.value = null;
+      syncHistoryFlags();
+      return;
+    }
+    selectedId.value = null;
+  }
+
+  function remove(id: string) {
+    if (selectedId.value === id) selectedId.value = null;
+    commit(features.value.filter((f) => f.id !== id));
+  }
+
+  /**
+   * ★ UNDO MEANS "TAKE BACK THE LAST THING I DID", and during a draft that is the last vertex — not the
+   * whole shape that existed before the draft started. Sending an open draft through the feature
+   * history would throw away a dozen placed vertices for one keystroke.
+   */
+  function undo() {
+    if (draft.value) {
+      dropLastVertex();
+      return;
+    }
+    history = undoHistory(history);
+    syncHistoryFlags();
+    emit(history.present);
+  }
+
+  function redo() {
+    history = redoHistory(history);
+    syncHistoryFlags();
+    emit(history.present);
+  }
+
+  /** Seed the editor, without an undo step — there is nothing yet to undo back to. */
+  function load(next: DrawFeature[]) {
+    history = historyOf(next);
+    syncHistoryFlags();
+    features.value = next;
+  }
+
+  // ── hit testing ──────────────────────────────────────────────────────────────────────────────────
+  function handleAt(m: MapboxMap, at: ScreenPoint) {
+    const id = selectedId.value;
+    const ring = id ? features.value.find((f) => f.id === id)?.ring : null;
+    if (!id || !ring) return null;
+
+    const vertex = nearestWithin(ring.map((v) => toScreen(m, v)), at, HANDLE_HIT_PX);
+    if (vertex != null) return { kind: 'vertex' as const, id, index: vertex };
+
+    const mid = nearestWithin(midpoints(ring).map((v) => toScreen(m, v)), at, HANDLE_HIT_PX);
+    if (mid != null) return { kind: 'midpoint' as const, id, index: mid };
+
+    return null;
+  }
+
+  /** The topmost feature under a point. Last drawn wins, which is what paints on top. */
+  function featureAt(m: MapboxMap, at: ScreenPoint): DrawFeature | null {
+    const p = turfPoint(toLngLat(m, at));
+    for (let i = features.value.length - 1; i >= 0; i--) {
+      const f = features.value[i];
+      if (f.ring.length < 3) continue;
+      if (booleanPointInPolygon(p, turfPolygon([closeRing(f.ring)]))) return f;
+    }
+    return null;
+  }
+
+  // ── the gesture ──────────────────────────────────────────────────────────────────────────────────
+  /**
+   * Eat the click a completed drag is about to emit. Lifted from useRegionSelect, where the comment
+   * explaining why lives: capture phase on the canvas CONTAINER, and a timer as well as `once`,
+   * because a drag that ends outside the canvas emits no click at all.
+   */
+  function swallowNextClick(m: MapboxMap) {
+    const el = m.getCanvasContainer();
+    const eat = (ev: Event) => {
+      ev.stopPropagation();
+      cancelEat();
+    };
+    const cancelEat = () => {
+      clearTimeout(timer);
+      el.removeEventListener('click', eat, true);
+    };
+    let timer: ReturnType<typeof setTimeout>;
+    el.addEventListener('click', eat, true);
+    timer = setTimeout(cancelEat, 300);
+  }
+
+  function onDown(e: PointerEvent) {
+    const m = map.value;
+    if (!m || !armed() || e.button !== 0) return;
+    const at = canvasPoint(m, e);
+    pressedAt = at;
+    m.getCanvas().setPointerCapture?.(e.pointerId);
+
+    if (tool() === 'rectangle') drag = { kind: 'box', from: at };
+    else if (tool() === 'circle') drag = { kind: 'circle', centre: at };
+    else if (tool() === 'edit') {
+      const handle = handleAt(m, at);
+      if (handle?.kind === 'vertex') {
+        drag = { kind: 'vertex', id: handle.id, index: handle.index };
+      } else if (handle?.kind === 'midpoint') {
+        // ★ Dragging a midpoint INSERTS, then drags what it inserted. Placing a vertex and then having
+        // to grab it again is two gestures for one intention, and the second one has to find a handle
+        // that was not there when the reader started moving.
+        const f = features.value.find((x) => x.id === handle.id);
+        if (f) {
+          const mid = midpoints(f.ring)[handle.index];
+          replaceRing(handle.id, insertVertex(f.ring, handle.index, mid));
+          drag = { kind: 'vertex', id: handle.id, index: handle.index + 1 };
+        }
+      } else {
+        const hit = featureAt(m, at);
+        selectedId.value = hit?.id ?? null;
+        if (hit) drag = { kind: 'body', id: hit.id, from: toLngLat(m, at) };
+      }
+    }
+    e.preventDefault();
+  }
+
+  function onMove(e: PointerEvent) {
+    const m = map.value;
+    if (!m || !armed()) return;
+    const at = canvasPoint(m, e);
+
+    if (!drag) {
+      // An open draft rubber-bands to the pointer, so the edge about to be committed is visible before
+      // it is. Nothing else needs to know where the pointer is.
+      if (tool() === 'polygon' && draft.value) cursor.value = toLngLat(m, at);
+      return;
+    }
+
+    if (drag.kind === 'box') {
+      preview.value = boxCorners(drag.from, at).map((p) => toLngLat(m, p));
+    } else if (drag.kind === 'circle') {
+      const centre = toLngLat(m, drag.centre);
+      const metres = metresBetween(centre, toLngLat(m, at));
+      radius.value = metres;
+      preview.value = metres > 0 ? geodesicRing(centre, metres) : null;
+    } else if (drag.kind === 'vertex') {
+      // Held in a const: `drag` is a mutable outer binding, so its narrowing does not survive into the
+      // callback below.
+      const held = drag;
+      const f = features.value.find((x) => x.id === held.id);
+      // Excluding the dragged feature is load-bearing — see snapVertices. Its own corners are the
+      // nearest candidates to the one in hand, and the handle would weld itself in place.
+      if (f) replaceRing(f.id, moveVertex(f.ring, held.index, place(m, at, held.id)));
+    } else if (drag.kind === 'body') {
+      const held = drag;
+      const to = toLngLat(m, at);
+      const dLng = to[0] - held.from[0];
+      const dLat = to[1] - held.from[1];
+      const f = features.value.find((x) => x.id === held.id);
+      if (f) {
+        replaceRing(f.id, f.ring.map(([lng, lat]) => [lng + dLng, lat + dLat] as LngLat));
+        // The anchor moves with the pointer, so the next frame measures its own delta rather than
+        // re-applying the whole drag from where it started.
+        held.from = to;
+      }
+    }
+  }
+
+  function onUp(e: PointerEvent) {
+    const m = map.value;
+    if (!m || !armed()) return;
+    const at = canvasPoint(m, e);
+    const from = pressedAt;
+    const current = drag;
+    m.getCanvas().releasePointerCapture?.(e.pointerId);
+    drag = null;
+    pressedAt = null;
+
+    // A press that never travelled is a click, whatever tool is armed.
+    const isClick = !from || !worthDrawing(from, at);
+    const doubled =
+      isClick &&
+      e.timeStamp - lastPress.time < DOUBLE_CLICK_MS &&
+      apart(at, lastPress.at) < DOUBLE_CLICK_PX;
+    if (isClick) lastPress = { at, time: e.timeStamp };
+
+    if (current?.kind === 'box' || current?.kind === 'circle') {
+      const ring = preview.value;
+      preview.value = null;
+      radius.value = null;
+      if (!isClick && ring) {
+        swallowNextClick(m);
+        addFeature(ring);
+      }
+      return;
+    }
+
+    if (current?.kind === 'vertex' || current?.kind === 'body') {
+      // ★ A double click ON A VERTEX removes it — the counterpart to dragging a midpoint, which is how
+      // one arrives. Delete would be the other spelling, but it is already spoken for by the feature,
+      // and a reader who has just grabbed a handle is holding a pointer rather than the keyboard.
+      if (doubled && current.kind === 'vertex') {
+        const f = features.value.find((x) => x.id === current.id);
+        // removeVertex refuses below three and says so by returning the ring untouched; committing the
+        // same ring back would then spend an undo step on nothing.
+        const next = f ? removeVertex(f.ring, current.index) : null;
+        if (f && next && next !== f.ring) {
+          commit(features.value.map((x) => (x.id === f.id ? { ...x, ring: next } : x)));
+        }
+        return;
+      }
+      // The drag mutated the ring on every move so the reader could see it; the undo step is the whole
+      // drag, taken once here rather than sixty times on the way.
+      if (!isClick) {
+        swallowNextClick(m);
+        commit(features.value);
+      }
+      return;
+    }
+
+    if (tool() === 'polygon' && isClick) {
+      // ★ The second click of a double click has already placed its vertex. Closing without dropping it
+      // would leave a duplicate of the previous position in the ring — invisible on the map, and a
+      // zero-length edge in the payload.
+      if (doubled) {
+        dropLastVertex();
+        finish();
+        return;
+      }
+      placeVertex(m, at);
+    }
+  }
+
+  /**
+   * Controls that own the keys this composable also wants.
+   *
+   * `closest`, not a tag test, so a keystroke landing on a span inside a button still counts as the
+   * button's.
+   */
+  const OWNS_ITS_KEYS =
+    'input, textarea, select, button, a[href], [contenteditable=""], [contenteditable="true"], [role="button"], [role="textbox"]';
+
+  /**
+   * ★ A KEY TYPED INTO A FIELD IS NOT A MAP SHORTCUT.
+   *
+   * The listener is on the window, and it has to be: a shortcut must work wherever the reader's focus
+   * happens to sit, and there is no one element to hang it on. The cost of that reach is this guard.
+   * A surface puts <FMapSearch> on the same canvas; an armed tool outlives the reader's trip to the
+   * search field; and without the check Backspace deletes a ZONE instead of a letter — with
+   * preventDefault stopping the field from ever seeing the key it was given. Enter and ⌘Z fail the
+   * same way, quietly, on the surface this component was built for.
+   *
+   * ★ BUTTONS ARE IN THE LIST TOO, and not for symmetry. <FMapDrawTools> puts finish and discard a tab
+   * apart: focus discard, press Enter, and the browser's click is suppressed by this handler's
+   * preventDefault while the handler runs FINISH. The reader asks to throw the shape away and it is
+   * committed instead — the worst available outcome from one keystroke.
+   */
+  function ownsItsKeys(e: KeyboardEvent): boolean {
+    const el = e.target as Element | null;
+    return !!el && typeof el.closest === 'function' && !!el.closest(OWNS_ITS_KEYS);
+  }
+
+  function onKey(e: KeyboardEvent) {
+    if (!armed() || ownsItsKeys(e)) return;
+    const meta = e.metaKey || e.ctrlKey;
+    if (meta && e.key.toLowerCase() === 'z') {
+      e.preventDefault();
+      if (e.shiftKey) redo();
+      else undo();
+      return;
+    }
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      cancel();
+      return;
+    }
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      finish();
+      return;
+    }
+    if (e.key === 'Backspace' || e.key === 'Delete') {
+      e.preventDefault();
+      if (draft.value) dropLastVertex();
+      else if (selectedId.value) remove(selectedId.value);
+    }
+  }
+
+  // ── paint ────────────────────────────────────────────────────────────────────────────────────────
+  /**
+   * One source for shapes, one for handles.
+   *
+   * The draft goes in as a LineString until it has three vertices — a fill layer draws polygons and a
+   * line layer draws both, so an unfinished ring paints as the open path it is and starts filling the
+   * moment it could close.
+   */
+  const shapeData = computed<GeoJSON.FeatureCollection>(() => {
+    const out: GeoJSON.Feature[] = features.value.map((f) => ({
+      ...drawFeatureToGeoJSON(f),
+      properties: {
+        ...(f.properties ?? {}),
+        draft: false,
+        selected: f.id === selectedId.value,
+        invalid: f.id === selectedId.value && invalid.value,
+      },
+    }));
+
+    const ring = draft.value ?? preview.value;
+    if (ring?.length) {
+      // The rubber band is part of the draft's own path, not a second feature: one line, so the join at
+      // the last placed vertex is a join rather than two ends meeting.
+      const withCursor = draft.value && cursor.value ? [...ring, cursor.value] : ring;
+      const props = { draft: true, selected: true, invalid: invalid.value };
+      out.push(
+        withCursor.length >= 3
+          ? {
+              type: 'Feature',
+              properties: props,
+              geometry: { type: 'Polygon', coordinates: [closeRing(withCursor)] },
+            }
+          : {
+              type: 'Feature',
+              properties: props,
+              geometry: { type: 'LineString', coordinates: withCursor },
+            },
+      );
+    }
+    return { type: 'FeatureCollection', features: out };
+  });
+
+  /**
+   * Handles for the ring under the cursor, and only that one.
+   *
+   * ★ A draft shows its vertices but no midpoints. There is nothing to insert BETWEEN yet — the ring is
+   * still being extended at its end — and drawing insertion handles on an open path invites a reader to
+   * grab one mid-sentence.
+   *
+   * ★ AND HANDLES ONLY APPEAR WHERE THEY CAN BE GRABBED. A shape stays selected after it is drawn, but
+   * only the edit tool moves a vertex — so painting handles under the polygon tool would offer a grip
+   * that does nothing, which is worse than no grip at all.
+   */
+  const handleData = computed<GeoJSON.FeatureCollection>(() => {
+    const editing = tool() === 'edit' && selectedId.value;
+    const ring = draft.value ?? (editing ? activeRing.value : null);
+    if (!ring?.length || preview.value) return { type: 'FeatureCollection', features: [] };
+
+    const vertices: GeoJSON.Feature[] = ring.map((at, index) => ({
+      type: 'Feature',
+      properties: { kind: 'vertex', index, invalid: invalid.value },
+      geometry: { type: 'Point', coordinates: at },
+    }));
+    if (draft.value) return { type: 'FeatureCollection', features: vertices };
+
+    const mids: GeoJSON.Feature[] = midpoints(ring).map((at, index) => ({
+      type: 'Feature',
+      properties: { kind: 'midpoint', index, invalid: invalid.value },
+      geometry: { type: 'Point', coordinates: at },
+    }));
+    return { type: 'FeatureCollection', features: [...vertices, ...mids] };
+  });
+
+  /** invalid paints in the error colour, everything else in the draw colour */
+  const drawColour = ['case', ['get', 'invalid'], token('--forest-map-draw-invalid'), token('--forest-map-draw')];
+
+  const layers = computed<OverlayLayer[]>(() => [
+    {
+      id: 'forest-draw-fill',
+      type: 'fill',
+      source: SOURCE_SHAPE,
+      filter: ['==', ['geometry-type'], 'Polygon'],
+      paint: { 'fill-color': drawColour, 'fill-opacity': 0.12 },
+    },
+    {
+      // Solid: a committed boundary. Dashes are not data-driven in mapbox, so the two states are two
+      // layers — the same reason zoneLayers() draws one line layer per kind.
+      id: 'forest-draw-line',
+      type: 'line',
+      source: SOURCE_SHAPE,
+      filter: ['!', ['get', 'draft']],
+      paint: {
+        'line-color': drawColour,
+        'line-width': ['case', ['get', 'selected'], 2.5, 1.5],
+      },
+    },
+    {
+      id: 'forest-draw-draft-line',
+      type: 'line',
+      source: SOURCE_SHAPE,
+      filter: ['get', 'draft'],
+      paint: { 'line-color': drawColour, 'line-width': 2, 'line-dasharray': [2, 1.5] },
+    },
+    {
+      id: 'forest-draw-midpoint',
+      type: 'circle',
+      source: SOURCE_HANDLE,
+      filter: ['==', ['get', 'kind'], 'midpoint'],
+      paint: {
+        'circle-radius': 3.5,
+        'circle-color': token('--forest-map-draw-handle'),
+        'circle-opacity': 0.85,
+        'circle-stroke-width': 1.5,
+        'circle-stroke-color': drawColour,
+        // A midpoint is an offer, not a vertex. Half-strength stroke is what keeps the two legible as
+        // different kinds of handle at a glance, without a second shape to learn.
+        'circle-stroke-opacity': 0.55,
+      },
+    },
+    {
+      id: 'forest-draw-vertex',
+      type: 'circle',
+      source: SOURCE_HANDLE,
+      filter: ['==', ['get', 'kind'], 'vertex'],
+      paint: {
+        'circle-radius': 5,
+        'circle-color': token('--forest-map-draw-handle'),
+        'circle-stroke-width': 2,
+        'circle-stroke-color': drawColour,
+      },
+    },
+  ]);
+
+  useMapOverlay(map, () => ({
+    sources: {
+      [SOURCE_SHAPE]: { type: 'geojson', data: shapeData.value },
+      [SOURCE_HANDLE]: { type: 'geojson', data: handleData.value },
+    },
+    layers: layers.value,
+  }));
+
+  // ── wiring ───────────────────────────────────────────────────────────────────────────────────────
+  watch(
+    map,
+    (m, _old, onCleanup) => {
+      if (!m) return;
+      const el = m.getCanvasContainer();
+      el.addEventListener('pointerdown', onDown);
+      // move/up on the window: a gesture that leaves the canvas mid-drag must still finish.
+      window.addEventListener('pointermove', onMove);
+      window.addEventListener('pointerup', onUp);
+      window.addEventListener('keydown', onKey);
+      onCleanup(() => {
+        el.removeEventListener('pointerdown', onDown);
+        window.removeEventListener('pointermove', onMove);
+        window.removeEventListener('pointerup', onUp);
+        window.removeEventListener('keydown', onKey);
+      });
+    },
+    { immediate: true },
+  );
+
+  /**
+   * ★ THE MAP'S OWN GESTURES STAND DOWN FOR AS LONG AS A TOOL IS ARMED, not for the duration of a drag.
+   * Disabling inside pointerdown is a race that cannot be won: GL JS drives dragPan from `mousedown`,
+   * which a real press fires alongside `pointerdown`, and preventDefault on a pointer event does not
+   * reliably suppress the mouse event behind it.
+   *
+   * doubleClickZoom joins the three region select disables, because a polygon closes on a double click
+   * and zooming the map at the same moment moves every vertex under the reader's cursor.
+   */
+  watch(
+    [map, armed],
+    ([m, on]) => {
+      if (!m) return;
+      for (const h of [m.dragPan, m.boxZoom, m.dragRotate, m.doubleClickZoom]) {
+        if (on) h.disable();
+        else h.enable();
+      }
+      m.getCanvas().style.cursor = on ? 'crosshair' : '';
+    },
+    { immediate: true },
+  );
+
+  // Putting the tool down abandons what was in flight. Leaving a half-drawn ring on the map while the
+  // reader pans would promise an editor that is no longer listening.
+  watch(armed, (on) => {
+    if (on) return;
+    draft.value = null;
+    preview.value = null;
+    cursor.value = null;
+  });
+
+  onScopeDispose(() => {
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', onUp);
+    window.removeEventListener('keydown', onKey);
+    const m = map.value;
+    if (!m) return;
+    for (const h of [m.dragPan, m.boxZoom, m.dragRotate, m.doubleClickZoom]) h.enable();
+    m.getCanvas().style.cursor = '';
+  });
+
+  return {
+    /** every shape the editor holds — the source of truth while it is open */
+    features,
+    /** the ring being placed, before it closes */
+    draft,
+    /** the shape a rectangle or circle drag is describing */
+    preview,
+    /** a circle drag's ground radius in metres, for a control that reports it */
+    radius,
+    selectedId,
+    /** why the shape under the cursor cannot be committed, or null */
+    problem,
+    invalid,
+    canUndo,
+    canRedo,
+    /** seed the editor. No undo step — there is nothing to go back to yet */
+    load,
+    finish,
+    cancel,
+    remove,
+    undo,
+    redo,
+    /** the set as GeoJSON, which is what a surface persists */
+    toGeoJSON: (): GeoJSON.FeatureCollection => ({
+      type: 'FeatureCollection',
+      features: features.value.map(drawFeatureToGeoJSON),
+    }),
+  };
+}