@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,356 @@
+// The arithmetic behind drawing — rings, the guards that refuse a bad one, snapping and undo.
+//
+// Kept out of the composable so it can be tested in node, where packages/ui's suite runs. What lives
+// here: what a ring IS, what makes one invalid, where a vertex lands when a midpoint is dragged, and
+// what a circle gesture means on the ground. What does not: pointers, GL, and anything that needs a
+// map to project.
+//
+// ★ RINGS ARE STORED OPEN. GeoJSON closes a polygon ring by repeating its first position as its last,
+// and carrying that duplicate through editing is a standing invitation to desync: move vertex 0 and
+// the copy at the end still holds the old position, so the ring silently stops closing. Every
+// operation here works on the open ring and `closeRing` adds the repeat at the boundary, once, where
+// the geometry leaves for GeoJSON.
+//
+// ★ VERTICES ARE GEOGRAPHIC, WHICH IS THE OPPOSITE CALL TO REGION SELECT. A lasso is a transient
+// question about the picture, so `regionSelect.ts` tests in screen space and the catch agrees with the
+// drawn shape under rotation and pitch. A drawn zone is a persisted fact about the ground: it survives
+// panning, zooming and a pause between two vertices, so a vertex is lng/lat from the moment it is
+// placed. The two modules disagree on purpose.
+import type { LngLat } from './coordinates';
+import type { ScreenPoint } from './regionSelect';
+
+/**
+ * Which tool the canvas is holding. The tool is what a DRAG DOES, and `off` is a state a reader
+ * chooses rather than the absence of one.
+ *
+ * ★ Same reasoning as `RegionTool`: a held modifier is unreachable on a phone, so gating drawing
+ * behind one would make authoring desktop-only. An armed tool is what makes a plain drag draw — and
+ * once a plain drag can draw, putting the tool down has to be something a reader can see and pick.
+ */
+export type DrawTool = 'off' | 'polygon' | 'rectangle' | 'circle' | 'edit';
+
+/** An OPEN ring: the first position is not repeated at the end. See the note at the top. */
+export type DrawRing = LngLat[];
+
+export interface DrawFeature {
+  id: string;
+  ring: DrawRing;
+  /** the caller's own payload — a zone kind, a name, whatever it persists */
+  properties?: Record<string, unknown>;
+}
+
+/** Why a ring cannot be committed. `null` is the only shape that means "it can". */
+export type DrawProblem = 'too-few' | 'self-intersects';
+
+/**
+ * Smaller than this on both axes and the gesture is a click, not a shape.
+ *
+ * The same floor region select uses, and for a sibling reason: without it a stray press-and-release
+ * during a rectangle drag commits a zone a few pixels across, which is invisible on the map and very
+ * much present in the payload.
+ */
+export const MIN_DRAW_PX = 4;
+
+/**
+ * How close a pointer has to be to an existing vertex for the new one to land on it exactly.
+ *
+ * 10px rather than the 3px `useFeatureSelect` hit-tests at: that number is for "did you mean to click
+ * this", where a generous radius steals clicks from neighbours. This one is for "did you mean to meet
+ * this", where the cost of missing is a hairline gap between two zones that share a boundary — a gap
+ * nobody sees until a rider is standing in it.
+ */
+export const SNAP_PX = 10;
+
+/**
+ * How many segments a drawn circle becomes.
+ *
+ * 64 puts the chord error under a tenth of a percent of the radius, which is below a pixel for any
+ * radius an operator draws at city zooms, and keeps the payload small enough to read in a diff.
+ */
+export const CIRCLE_SEGMENTS = 64;
+
+const EARTH_RADIUS_M = 6_371_008.8;
+const toRad = (deg: number) => (deg * Math.PI) / 180;
+const toDeg = (rad: number) => (rad * 180) / Math.PI;
+
+/** GeoJSON's closed ring: the open one with its first position repeated at the end. */
+export function closeRing(ring: DrawRing): LngLat[] {
+  if (ring.length < 3) return [...ring];
+  const [first] = ring;
+  const last = ring[ring.length - 1];
+  return first[0] === last[0] && first[1] === last[1] ? [...ring] : [...ring, [first[0], first[1]]];
+}
+
+/** A ring as the GeoJSON feature a surface persists. */
+export function drawFeatureToGeoJSON(feature: DrawFeature): GeoJSON.Feature<GeoJSON.Polygon> {
+  return {
+    type: 'Feature',
+    id: feature.id,
+    properties: { ...(feature.properties ?? {}) },
+    geometry: { type: 'Polygon', coordinates: [closeRing(feature.ring)] },
+  };
+}
+
+/**
+ * The midpoint of every edge, INCLUDING the closing one — those are the handles that insert a vertex,
+ * and the edge between the last vertex and the first needs one as much as any other.
+ *
+ * Interpolated linearly in lng/lat rather than along a great circle. Over a city block the two differ
+ * by well under a millimetre, and the linear midpoint has the property that matters to a reader: it
+ * sits exactly halfway along the line the map draws.
+ */
+export function midpoints(ring: DrawRing): LngLat[] {
+  if (ring.length < 2) return [];
+  return ring.map((a, i) => {
+    const b = ring[(i + 1) % ring.length];
+    return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2] as LngLat;
+  });
+}
+
+/** Move one vertex. Out-of-range indices return the ring untouched rather than growing it. */
+export function moveVertex(ring: DrawRing, index: number, at: LngLat): DrawRing {
+  if (index < 0 || index >= ring.length) return ring;
+  const next = [...ring];
+  next[index] = [at[0], at[1]];
+  return next;
+}
+
+/**
+ * Insert a vertex AFTER `index` — the contract midpoint handles need, since midpoint `i` sits on the
+ * edge leaving vertex `i`. Inserting after the last vertex appends, which is the closing edge's case.
+ */
+export function insertVertex(ring: DrawRing, index: number, at: LngLat): DrawRing {
+  if (index < 0 || index >= ring.length) return ring;
+  const next = [...ring];
+  next.splice(index + 1, 0, [at[0], at[1]]);
+  return next;
+}
+
+/**
+ * Drop a vertex, unless dropping it would leave something that is not a polygon.
+ *
+ * ★ Refusing is right, and returning the ring unchanged is how it refuses. A ring of three is a
+ * triangle; take one away and there is no shape left to edit back into existence, so the handle simply
+ * stops responding rather than deleting the reader's work in a way they cannot undo by dragging.
+ */
+export function removeVertex(ring: DrawRing, index: number): DrawRing {
+  if (ring.length <= 3 || index < 0 || index >= ring.length) return ring;
+  return ring.filter((_, i) => i !== index);
+}
+
+/** Whether two positions are the same place, to within the precision a click can express. */
+const samePoint = (a: LngLat, b: LngLat) => a[0] === b[0] && a[1] === b[1];
+
+const orientation = (a: LngLat, b: LngLat, c: LngLat): number => {
+  const v = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+  return v > 0 ? 1 : v < 0 ? -1 : 0;
+};
+
+const onSegment = (a: LngLat, b: LngLat, p: LngLat): boolean =>
+  Math.min(a[0], b[0]) <= p[0] &&
+  p[0] <= Math.max(a[0], b[0]) &&
+  Math.min(a[1], b[1]) <= p[1] &&
+  p[1] <= Math.max(a[1], b[1]);
+
+/**
+ * Do two segments cross? The standard orientation test, with the collinear cases spelled out.
+ *
+ * Treated in the plane rather than on the sphere: two segments that cross on a city map cross in
+ * mercator too, and the great-circle version of this test costs an order of magnitude more for a
+ * disagreement that begins at continental scale.
+ */
+export function segmentsCross(a: LngLat, b: LngLat, c: LngLat, d: LngLat): boolean {
+  const o1 = orientation(a, b, c);
+  const o2 = orientation(a, b, d);
+  const o3 = orientation(c, d, a);
+  const o4 = orientation(c, d, b);
+  if (o1 !== o2 && o3 !== o4) return true;
+  if (o1 === 0 && onSegment(a, b, c)) return true;
+  if (o2 === 0 && onSegment(a, b, d)) return true;
+  if (o3 === 0 && onSegment(c, d, a)) return true;
+  if (o4 === 0 && onSegment(c, d, b)) return true;
+  return false;
+}
+
+/**
+ * Does the ring cross itself?
+ *
+ * ★ ADJACENT EDGES ARE SKIPPED, because they always touch — that is what makes them adjacent. The
+ * test is over pairs of edges that share no vertex, which for a closed ring means the first and last
+ * edge are neighbours too and are skipped with the rest.
+ *
+ * A figure of eight is the case this exists for. Mapbox renders one happily, with the crossing filled
+ * by the even-odd rule, so nothing on screen says the polygon is degenerate — and a zone whose
+ * boundary crosses itself has no answer to "is this point inside it" that a rider and a billing run
+ * would agree on.
+ */
+export function selfIntersects(ring: DrawRing): boolean {
+  const n = ring.length;
+  if (n < 4) return false;
+  for (let i = 0; i < n; i++) {
+    const a = ring[i];
+    const b = ring[(i + 1) % n];
+    for (let j = i + 1; j < n; j++) {
+      // share a vertex — adjacent edges, and the wrap-around pair the modulo makes adjacent too
+      if (j === i || (j + 1) % n === i || (i + 1) % n === j) continue;
+      const c = ring[j];
+      const d = ring[(j + 1) % n];
+      if (segmentsCross(a, b, c, d)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * What is wrong with this ring, or `null` if nothing is.
+ *
+ * ★ It reports rather than repairs. A draft that silently dropped its crossing vertex would move
+ * geometry the reader placed, in a way they did not ask for and cannot see happen. The composable
+ * paints the problem instead and refuses the commit.
+ */
+export function ringProblem(ring: DrawRing): DrawProblem | null {
+  const distinct = ring.filter((p, i) => i === 0 || !samePoint(p, ring[i - 1]));
+  if (distinct.length < 3) return 'too-few';
+  if (selfIntersects(ring)) return 'self-intersects';
+  return null;
+}
+
+/**
+ * The four corners of a screen-space drag, wound consistently.
+ *
+ * Screen corners rather than a lng/lat box: the composable unprojects each one, so under rotation the
+ * result is a quad aligned to the screen — the shape the reader actually drew. An axis-aligned
+ * geographic box would be a different shape from the rectangle they watched themselves make.
+ */
+export function boxCorners(a: ScreenPoint, b: ScreenPoint): ScreenPoint[] {
+  return [
+    [a[0], a[1]],
+    [b[0], a[1]],
+    [b[0], b[1]],
+    [a[0], b[1]],
+  ];
+}
+
+/** Great-circle distance in metres — what a circle's radius is measured in, and reported as. */
+export function metresBetween(a: LngLat, b: LngLat): number {
+  const dLat = toRad(b[1] - a[1]);
+  const dLng = toRad(b[0] - a[0]);
+  const lat1 = toRad(a[1]);
+  const lat2 = toRad(b[1]);
+  const h =
+    Math.sin(dLat / 2) ** 2 + Math.sin(dLng / 2) ** 2 * Math.cos(lat1) * Math.cos(lat2);
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+/**
+ * A circle on the GROUND: `segments` positions at a fixed distance from the centre.
+ *
+ * ★ NOT AN UNPROJECTED SCREEN CIRCLE. On a pitched map a screen circle unprojects to an egg, and the
+ * reader's question — "everything within a couple of hundred metres of this bay" — is about the
+ * ground, not the picture. Going through metres also means the radius is a number the control can
+ * show, which is worth more to an operator than matching the drag pixel for pixel.
+ */
+export function geodesicRing(centre: LngLat, metres: number, segments = CIRCLE_SEGMENTS): DrawRing {
+  const angular = metres / EARTH_RADIUS_M;
+  const lat = toRad(centre[1]);
+  const lng = toRad(centre[0]);
+  const sinLat = Math.sin(lat) * Math.cos(angular);
+  const cosLat = Math.cos(lat) * Math.sin(angular);
+
+  const ring: DrawRing = [];
+  for (let i = 0; i < segments; i++) {
+    const bearing = (i / segments) * 2 * Math.PI;
+    const lat2 = Math.asin(sinLat + cosLat * Math.cos(bearing));
+    const lng2 =
+      lng +
+      Math.atan2(Math.sin(bearing) * cosLat, Math.cos(angular) - Math.sin(lat) * Math.sin(lat2));
+    ring.push([toDeg(lng2), toDeg(lat2)]);
+  }
+  return ring;
+}
+
+/**
+ * Every vertex a snap may land on, given the shapes that exist.
+ *
+ * ★ `exclude` IS WHAT MAKES DRAGGING SAFE. A corner being dragged is itself a candidate, and the
+ * nearest vertex to a corner is always that corner — so without this the handle would weld itself in
+ * place the moment it was picked up. Excluding the WHOLE feature rather than the one index is the
+ * stronger rule and the right one: snapping a corner onto another corner of its own ring pinches the
+ * polygon into a shape that touches itself, which `ringProblem` then has to refuse. An operator
+ * aligning a boundary means their neighbour's corner, never their own.
+ */
+export function snapVertices(features: readonly DrawFeature[], exclude?: string): LngLat[] {
+  const out: LngLat[] = [];
+  for (const f of features) {
+    if (f.id === exclude) continue;
+    for (const v of f.ring) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * The nearest of `points` to `at`, if one is within tolerance — the snap test, in screen px.
+ *
+ * Screen space rather than metres, because the tolerance a reader feels is a distance on the display:
+ * the same 10px is metres at street zoom and kilometres at city zoom, and in both cases it is "near
+ * enough that I was aiming at it".
+ */
+export function nearestWithin(
+  points: readonly ScreenPoint[],
+  at: ScreenPoint,
+  tolerance = SNAP_PX,
+): number | null {
+  let best: number | null = null;
+  let bestDistance = tolerance;
+  points.forEach((p, i) => {
+    const d = Math.hypot(p[0] - at[0], p[1] - at[1]);
+    if (d <= bestDistance) {
+      best = i;
+      bestDistance = d;
+    }
+  });
+  return best;
+}
+
+/** Whether a drag was big enough to have been meant as a shape. */
+export function worthDrawing(a: ScreenPoint, b: ScreenPoint): boolean {
+  return Math.abs(b[0] - a[0]) > MIN_DRAW_PX || Math.abs(b[1] - a[1]) > MIN_DRAW_PX;
+}
+
+/**
+ * Undo, as a value.
+ *
+ * ★ Whole snapshots, not a log of operations. The state being remembered is a list of rings a person
+ * can hold in their head, so an inverse-operation log buys nothing and costs the class of bug where
+ * undo and redo disagree about what an operation meant. The cap keeps a long editing session from
+ * growing without bound.
+ */
+export interface DrawHistory<T> {
+  past: T[];
+  present: T;
+  future: T[];
+}
+
+export const HISTORY_CAP = 50;
+
+export const historyOf = <T>(present: T): DrawHistory<T> => ({ past: [], present, future: [] });
+
+export function pushHistory<T>(h: DrawHistory<T>, next: T, cap = HISTORY_CAP): DrawHistory<T> {
+  const past = [...h.past, h.present].slice(-cap);
+  // ★ A new edit clears the redo branch. Keeping it would let a reader redo their way into a state
+  // that never followed from what is now on screen.
+  return { past, present: next, future: [] };
+}
+
+export function undoHistory<T>(h: DrawHistory<T>): DrawHistory<T> {
+  if (!h.past.length) return h;
+  const past = [...h.past];
+  const present = past.pop() as T;
+  return { past, present, future: [h.present, ...h.future] };
+}
+
+export function redoHistory<T>(h: DrawHistory<T>): DrawHistory<T> {
+  if (!h.future.length) return h;
+  const [present, ...future] = h.future;
+  return { past: [...h.past, h.present], present, future };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * A CSS easing curve, evaluated in JS.
+ *
+ * ★ WHY THIS EXISTS. Mapbox's camera moves take an `easing` FUNCTION, not a CSS timing function — so a
+ * camera glide running alongside a CSS transition has no way to share its curve. The alternative was to
+ * pick a JS easing that "looks about right", which is exactly how two motions that are supposed to be one
+ * gesture drift apart: the panel decelerating on one curve while the map decelerates on another reads as
+ * two things happening, not one thing moving.
+ *
+ * So the curve is read from the same token the CSS uses (--motion-ease-out) and sampled here. One
+ * definition, two runtimes.
+ */
+
+/** Evaluates a cubic-bezier(x1, y1, x2, y2) the way CSS does: y as a function of x, where x is time. */
+export const cubicBezier = (x1: number, y1: number, x2: number, y2: number) => {
+  // The standard parametric form with p0 = (0,0) and p3 = (1,1).
+  const curve = (a: number, b: number, t: number) => {
+    const u = 1 - t;
+    return 3 * u * u * t * a + 3 * u * t * t * b + t * t * t;
+  };
+  return (time: number): number => {
+    if (time <= 0) return 0;
+    if (time >= 1) return 1;
+    // Bisection rather than Newton–Raphson: 20 halvings is ~1e-6 on t, cheaper to reason about than
+    // derivative handling near the flat ends of a strong curve, and this runs once per frame at most.
+    let lo = 0;
+    let hi = 1;
+    let t = time;
+    for (let i = 0; i < 20; i++) {
+      const x = curve(x1, x2, t);
+      if (Math.abs(x - time) < 1e-5) break;
+      if (x < time) lo = t;
+      else hi = t;
+      t = (lo + hi) / 2;
+    }
+    return curve(y1, y2, t);
+  };
+};
+
+const LINEAR = (t: number) => t;
+
+/**
+ * Parses a `cubic-bezier(...)` declaration into a sampler. Anything else — a keyword, an empty string, a
+ * malformed value — falls back to linear rather than throwing: a camera move with the wrong curve is a
+ * cosmetic loss, and a camera move that throws is a broken map.
+ */
+export const parseEasing = (value: string): ((t: number) => number) => {
+  const m = value.trim().match(/^cubic-bezier\(([^)]+)\)$/);
+  if (!m) return LINEAR;
+  const parts = m[1].split(',').map((n) => Number.parseFloat(n));
+  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return LINEAR;
+  return cubicBezier(parts[0], parts[1], parts[2], parts[3]);
+};
+
+/** Reads a CSS time token (`240ms`, `0.24s`) off an element, in ms. 0 for anything unparseable. */
+export const readMs = (el: Element | null, prop: string): number => {
+  if (!el) return 0;
+  const raw = getComputedStyle(el).getPropertyValue(prop).trim();
+  if (!raw) return 0;
+  const n = Number.parseFloat(raw);
+  if (Number.isNaN(n)) return 0;
+  return raw.endsWith('ms') ? n : n * 1000;
+};
+
+/** Reads a CSS easing token off an element and returns it as a sampler. */
+export const readEasing = (el: Element | null, prop: string): ((t: number) => number) =>
+  el ? parseEasing(getComputedStyle(el).getPropertyValue(prop)) : LINEAR;

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

@@ -0,0 +1,59 @@
+// The fullscreen API, resolved once as data.
+//
+// ★ RESOLVED, NOT BRANCHED AT EACH CALL. Three spellings are in play — the standard names, Safari's
+// prefixed ones, and nothing at all on iPhone — and a component that tested for them at every use ends
+// up with a template condition and a click handler that can disagree about which one it is in.
+//
+// ★ ABSENT AND FORBIDDEN COLLAPSE TO ONE ANSWER. `null` means "there is no fullscreen here", whether
+// the methods are missing (Safari on iPhone, which does fullscreen video and nothing else) or present
+// and disallowed (an iframe without `allowfullscreen`). A control that can never do its one thing
+// renders nothing, and one null check is the whole condition.
+
+export interface FullscreenApi {
+  /** method name on the ELEMENT */
+  request: string;
+  /** method name on the DOCUMENT */
+  exit: string;
+  /** property on the document holding the element currently fullscreen */
+  element: string;
+  /** the change event. The prefixed spelling lower-cases the whole word, not just the prefix */
+  event: string;
+}
+
+type DocLike = Record<string, unknown> & { documentElement?: unknown };
+
+const STANDARD: FullscreenApi = {
+  request: 'requestFullscreen',
+  exit: 'exitFullscreen',
+  element: 'fullscreenElement',
+  event: 'fullscreenchange',
+};
+
+const WEBKIT: FullscreenApi = {
+  request: 'webkitRequestFullscreen',
+  exit: 'webkitExitFullscreen',
+  element: 'webkitFullscreenElement',
+  event: 'webkitfullscreenchange',
+};
+
+/** Which spelling this document speaks, or null where it does not speak one at all. */
+export function fullscreenApi(doc: DocLike | null | undefined): FullscreenApi | null {
+  if (!doc) return null;
+  const root = doc.documentElement as Record<string, unknown> | undefined;
+  // Support is read off the ELEMENT method, not the document flag: the flag is the permission, and a
+  // browser with no fullscreen at all has neither.
+  if (root && typeof root[STANDARD.request] === 'function') {
+    return doc.fullscreenEnabled === false ? null : STANDARD;
+  }
+  if (root && typeof root[WEBKIT.request] === 'function') {
+    return doc.webkitFullscreenEnabled === false ? null : WEBKIT;
+  }
+  return null;
+}
+
+/** Whether THIS element is the one filling the screen — not merely whether something is. */
+export function isFullscreen(doc: DocLike | null | undefined, el: Element | null): boolean {
+  if (!doc || !el) return false;
+  const api = fullscreenApi(doc);
+  return !!api && doc[api.element] === el;
+}

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

@@ -0,0 +1,160 @@
+// A KERNEL FIELD — where the weight is, with no cell and no countable unit.
+//
+// ★ IT SHARES NOTHING WITH BINS BUT A BASEMAP. That is why it is its own module. A bin is a counted
+// cell: it has a size, an id, a hoverable edge, a resolution on a ladder, and a domain measured in
+// per-cell totals. A kernel field has none of those. It takes raw events, spreads each one over a
+// radius somebody chose, and paints the sum. The two used to share one function and one `domain`
+// option, and that cost a day: the same word meant per-cell totals to one and per-event weight to the
+// other, so a heat layer handed a bins domain scaled every event to a twentieth of its weight and
+// painted an empty map. Nothing failed; the map was just blank.
+//
+// ★ AND IT KNOWS NOTHING ABOUT H3. `bin.ts` is the H3 seam — cell sizes, the zoom→resolution ladder,
+// the join. None of it applies here, and this module does not import it. A surface that has events
+// does not need a grid to draw a field, and pretending otherwise is how a heat layer ends up drawing
+// its own sample points back at the reader.
+//
+// ★ HEAT FOR THE GLANCE, BINS FOR THE DECISION. The radius is a choice, the same points draw a
+// different picture at a different radius, and nothing in the image says which one is on screen. A
+// dispatch instruction — send twelve bikes to this cell — may never be read off this layer.
+import { MAP_SLOT, token, type OverlayLayer } from './useMapOverlay';
+import { SEQUENTIAL_RAMPS, rampStops, type SequentialRamp } from './ramp';
+
+/**
+ * The ramps a field may use — the engine's sequential families, sampled by `ramp.ts`.
+ *
+ * ★ A PROP, UNLIKE THE BIN RAMP, AND THE ASYMMETRY IS DELIBERATE. Bins carry one ramp because a bin
+ * map is read against a legend of buckets, and a surface free to re-ramp per view would make two
+ * screenshots of the same city incomparable. A field has no buckets to compare — it is an impression —
+ * and different fields (demand, faults, dwell time) sitting in one console want to be told apart at a
+ * glance more than they want to match.
+ */
+export const HEAT_RAMPS = SEQUENTIAL_RAMPS;
+export type HeatRamp = SequentialRamp;
+
+
+/**
+ * Where the colour stops sit on the density axis.
+ *
+ * ★ THE FIRST ONE IS NOT ZERO. Interpolating from `rgba(0,0,0,0)` up to `floor` is what fades the
+ * fringe in — alpha ramps with density across that gap, so a thin reading is faint rather than a hard
+ * edge of the palest colour. Below `floor` the field is effectively transparent.
+ */
+export const HEAT_FLOOR = 0.15;
+
+
+
+export interface HeatOptions {
+  /** source id holding the EVENTS — one feature per thing that happened */
+  source: string;
+  /**
+   * Which ramp the field paints in. Default `forest`.
+   *
+   * ★ THERE IS NO STOP COUNT HERE, AND THAT IS THE POINT. A field is CONTINUOUS — nobody matches a
+   * pixel to a swatch, so it has no buckets, and a knob for "how many" would invite reading one as if
+   * it did. `heatmap-color` needs discrete interpolation stops to describe a gradient, so the module
+   * spends every stop the ramp declares and spaces them evenly; that is a detail of the style spec,
+   * not a decision a surface makes. Buckets belong to bins, where they are counted and legended.
+   */
+  ramp?: HeatRamp;
+  /** kernel radius on the ground, in metres. Default 300 */
+  radiusM?: number;
+  /** latitude the radius is computed at. Default London */
+  lat?: number;
+  /**
+   * Property carrying each event's weight, when events are not equal.
+   *
+   * ★ DEFAULT IS UNWEIGHTED, AND THAT IS THE COMMON CASE. A ride start is a ride start; the field is
+   * the density of events and one event counts once. Reach for this only when a point genuinely
+   * carries a magnitude — a fault's severity, a bay's capacity.
+   */
+  weightProp?: string;
+  /** the per-EVENT weight range, required only with `weightProp` */
+  weightRange?: [number, number];
+  /** id prefix, so two fields can coexist. Default `heat` */
+  prefix?: string;
+  /** opacity ceiling. Default 0.5 — the basemap has to survive underneath */
+  alpha?: number;
+}
+
+/**
+ * A kernel radius that holds its size ON THE GROUND rather than on the screen.
+ *
+ * ★ `heatmap-radius` IN PIXELS IS THE ZOOM LIE IN ITS PUREST FORM. A fixed pixel radius means the same
+ * points draw a tight archipelago at z16 and one continuous blob at z11, and neither picture is about
+ * the data. A radius in metres is a claim a reader can hold: "weight within 300 m of here".
+ *
+ * ★ THE BASE-2 EXPONENTIAL IS EXACT, not an approximation. Ground resolution halves per zoom step
+ * (metres/px = 156543·cos(lat)/2^zoom), so a radius in pixels is proportional to 2^zoom — and mapbox's
+ * exponential interpolation with base 2 reproduces that curve exactly between two anchors. Two stops
+ * are therefore enough, and any zoom between them is right rather than nearly right.
+ *
+ * ⚠ Outside the anchor range mapbox CLAMPS to the endpoint value, so the ground size is only held
+ * between them. The defaults span a city map; a surface that flies to z19 should widen them.
+ */
+export function heatRadiusByZoom(metres: number, lat = 51.5, anchors: [number, number] = [10, 18]): unknown {
+  const px = (z: number) => (metres * 2 ** z) / (156543.03392 * Math.cos((lat * Math.PI) / 180));
+  const [z0, z1] = anchors;
+  return ['interpolate', ['exponential', 2], ['zoom'], z0, px(z0), z1, px(z1)];
+}
+
+/**
+ * The layers for a kernel field.
+ *
+ * ★ IT SITS IN `MAP_SLOT.route` (`middle`), NOT WITH THE ZONES. `bottom` is below the entire road
+ * network, and a field buried under every casing, carriageway and bridge reads as grey haze — measured
+ * on the demo map, where exactly that happened. `middle` clears the roads and still sits behind the 3D
+ * buildings, the basemap's labels and every mark, which stay in `top`.
+ */
+export function heatLayers(opts: HeatOptions): OverlayLayer[] {
+  const {
+    source,
+    ramp = 'forest',
+    radiusM = 300,
+    lat = 51.5,
+    weightProp,
+    weightRange,
+    prefix = 'heat',
+    alpha = 0.5,
+  } = opts;
+
+  // Every stop the family declares: a gradient is smoothest when it spends what the ramp actually has.
+  const stops = rampStops(ramp);
+  // Evenly spaced from the floor to full density. The gradient is read as a ramp, so uneven spacing
+  // would put a perceptual edge at a density that means nothing.
+  const at = (i: number) => HEAT_FLOOR + ((1 - HEAT_FLOOR) * i) / (stops.length - 1);
+
+  return [
+    {
+      id: `${prefix}-field`,
+      type: 'heatmap',
+      source,
+      slot: MAP_SLOT.route,
+      paint: {
+        // ★ ONE EVENT COUNTS ONCE unless the caller says otherwise, and a weight without a range is
+        // the empty-map bug waiting to happen — an unscaled magnitude of 4 against a domain built for
+        // per-cell totals lands at a twentieth of a weight and the field never reaches a paintable
+        // density.
+        'heatmap-weight':
+          weightProp && weightRange && weightRange[1] > weightRange[0]
+            ? ['interpolate', ['linear'], ['get', weightProp], weightRange[0], 0, weightRange[1], 1]
+            : 1,
+        'heatmap-intensity': 1,
+        // ★ THE FIRST STOP MUST BE TRANSPARENT, for two reasons. Mechanically, `heatmap-color` is
+        // evaluated across the WHOLE viewport including everywhere the density is zero, so a ramp that
+        // starts opaque paints the entire screen. And perceptually, interpolating FROM transparent is
+        // what fades the fringe in: alpha ramps with density between 0 and the first stop, so a low
+        // reading is faint rather than a hard edge of the palest colour.
+        'heatmap-color': [
+          'interpolate',
+          ['linear'],
+          ['heatmap-density'],
+          0,
+          'rgba(0, 0, 0, 0)',
+          ...stops.flatMap((name, i) => [at(i), token(name)]),
+        ],
+        'heatmap-radius': heatRadiusByZoom(radiusM, lat),
+        'heatmap-opacity': alpha,
+      },
+    },
+  ];
+}