@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,196 @@
+// The H3 seam — joining values to cells, and choosing which cell size a zoom deserves.
+//
+// ★ FOREST DOES NOT INVENT A GRID. The fleet server already indexes with H3 (`latLngToCell`, and a
+// stored grid it ships as polygons), so a bespoke Forest hex grid would be a second, incompatible
+// hexagonal picture of the same city. This module speaks H3's vocabulary and takes GEOMETRY IN.
+//
+// ★ AND IT TAKES NO DEPENDENCY. `h3-js` is ~60KB gzipped of emscripten output, and the path that
+// exists does not need it: the cells arrive as a FeatureCollection carrying `h3_id`. What is needed
+// here is the arithmetic AROUND the cells — how big one is, which resolution a zoom wants, how a value
+// map joins onto them, and what domain a heavy-tailed feed deserves. All of that is a table and four
+// functions. If a surface ever has raw points and no server to bin them, it imports h3-js itself and
+// hands the result here; that is a call site's decision, not the design system's.
+//
+// Everything here is pure: no map, no DOM, no network. It runs in the node suite.
+
+/**
+ * AVERAGE EDGE LENGTH IN METRES, PER H3 RESOLUTION.
+ *
+ * ★ THIS TABLE IS WHY A LEGEND CAN STATE ITS UNIT. A hex map with no stated cell size invites the
+ * reader to compare two cells that are not the same size as each other across a zoom, or to read a
+ * count as a density. "cell ≈ 460 m across" costs one line and closes both.
+ *
+ * H3 cells are not all identical — the icosahedral projection varies them by a few percent, and the
+ * twelve pentagons are their own case — so these are the documented AVERAGES. They are the right
+ * number for a legend and the wrong number for a calculation that has to balance; anything that must
+ * be exact should ask h3-js for the cell it actually holds.
+ */
+export const H3_EDGE_M: Record<number, number> = {
+  5: 8544,
+  6: 3229,
+  7: 1220,
+  8: 461,
+  9: 174,
+  10: 65.8,
+  11: 24.9,
+};
+
+/** The resolutions this ladder will choose between. Below 6 a cell is bigger than London. */
+export const H3_RES_RANGE: readonly number[] = [6, 7, 8, 9, 10, 11];
+
+/**
+ * How wide a cell should be ON SCREEN, in CSS px.
+ *
+ * Under the low end a cell stops being a thing a reader can point at — and stops being a thing a
+ * pointer can hit, which matters more, because a bin that cannot be hovered cannot state its count.
+ * Over the high end the grid stops being a texture and starts being a small number of large tiles,
+ * which reads as a coarse choropleth of nothing in particular.
+ *
+ * The band is wide on purpose: H3 resolutions step by roughly a factor of 2.6 in edge length, so no
+ * ladder can keep a cell inside a tight band across every zoom.
+ */
+export const CELL_PX_BAND = { min: 40, max: 110, ideal: 65 } as const;
+
+/** Web-mercator ground resolution — metres per CSS pixel at a zoom and latitude. */
+export const metresPerPixel = (zoom: number, lat: number): number =>
+  (156543.03392 * Math.cos((lat * Math.PI) / 180)) / 2 ** zoom;
+
+/** How wide a cell of this resolution draws, in CSS px, at a zoom and latitude. */
+export const cellWidthPx = (res: number, zoom: number, lat: number): number =>
+  (2 * H3_EDGE_M[res]) / metresPerPixel(zoom, lat);
+
+/**
+ * The resolution to bin at for a zoom — the rung whose drawn cell lands nearest the ideal width.
+ *
+ * ★ THE LADDER IS WHERE THE ZOOM LIE LIVES, SO IT IS OWNED HERE RATHER THAN LEFT TO A CALL SITE.
+ * Binning at a fixed resolution and letting the reader zoom means the same data draws a different
+ * claim at every scale: at z10 a res-9 grid is a stipple with a count of one in most cells, and at z16
+ * a res-7 grid is four tiles. Neither is wrong about the data and both are wrong about the reader.
+ *
+ * ⚠ Changing resolution RE-BINS, which means the numbers change. A surface that follows this ladder
+ * must re-fetch or re-aggregate as it steps, and its legend must restate the cell size — that is the
+ * cost of not lying, and it is why `h3ResForZoom` is a decision a surface makes deliberately rather
+ * than something that happens to it.
+ */
+export function h3ResForZoom(zoom: number, lat = 51.5): number {
+  let best = H3_RES_RANGE[0];
+  let bestGap = Infinity;
+  for (const res of H3_RES_RANGE) {
+    // Compared in log space: a cell twice too big and one half too small are the same error, which
+    // a linear difference would score very differently.
+    const gap = Math.abs(Math.log(cellWidthPx(res, zoom, lat) / CELL_PX_BAND.ideal));
+    if (gap < bestGap) {
+      bestGap = gap;
+      best = res;
+    }
+  }
+  return best;
+}
+
+/** Does a resolution actually draw inside the band at this zoom, or is it the least-bad rung? */
+export const cellFitsBand = (res: number, zoom: number, lat = 51.5): boolean => {
+  const px = cellWidthPx(res, zoom, lat);
+  return px >= CELL_PX_BAND.min && px <= CELL_PX_BAND.max;
+};
+
+// ── joining values onto cells ────────────────────────────────────────────────────────────────────
+
+interface CellFeature {
+  type: 'Feature';
+  properties: Record<string, unknown> | null;
+  geometry: unknown;
+}
+export interface CellCollection {
+  type: 'FeatureCollection';
+  features: CellFeature[];
+}
+
+export interface JoinOptions {
+  /** property holding the cell id on the incoming features. Default `h3_id` */
+  idProp?: string;
+  /** property the value is written to. Default `value` */
+  valueProp?: string;
+  /** drop cells with no reading instead of passing them through unvalued. Default false */
+  dropUnread?: boolean;
+}
+
+/**
+ * Join a `{ cellId: value }` map onto a collection of cell polygons.
+ *
+ * ★ A CELL WITH NO READING KEEPS NO VALUE — it does not get a zero. "Nobody counted here" and "we
+ * counted and it was none" are different claims, and a join that quietly writes 0 turns the first into
+ * the second everywhere the feed is sparse. The unvalued cell passes through without the value
+ * property so a layer filter can skip it (`['has', 'value']`), or is dropped outright with
+ * `dropUnread` where the surface would rather not ship the geometry at all.
+ */
+export function joinCellValues(
+  cells: CellCollection,
+  values: Record<string, number>,
+  opts: JoinOptions = {},
+): CellCollection {
+  const { idProp = 'h3_id', valueProp = 'value', dropUnread = false } = opts;
+  const features: CellFeature[] = [];
+
+  for (const f of cells.features) {
+    const id = f.properties?.[idProp];
+    const v = typeof id === 'string' ? values[id] : undefined;
+    const read = typeof v === 'number' && Number.isFinite(v);
+    if (!read && dropUnread) continue;
+    features.push({
+      ...f,
+      properties: read
+        ? { ...(f.properties ?? {}), [valueProp]: v }
+        : { ...(f.properties ?? {}) },
+    });
+  }
+
+  return { type: 'FeatureCollection', features };
+}
+
+// ── domains ─────────────────────────────────────────────────────────────────────────────────────
+
+export interface Domain {
+  domain: [number, number];
+  /** how many readings sit above the top of the domain and are painted at the top stop */
+  clamped: number;
+  /** the percentile the top was taken at, for the legend to state */
+  percentile: number;
+}
+
+/**
+ * `[0, p]` where p is a percentile of the readings — 95th by default.
+ *
+ * ★ A LINEAR DOMAIN OVER REAL OPS DATA IS A BLANK MAP. Counts per cell are heavy-tailed: one depot,
+ * one station, one Friday night, and the maximum is an order of magnitude above the median, which
+ * pushes every ordinary cell into the palest stop and paints the city as empty with one bright dot.
+ * Clamping at a percentile spends the ramp where the readings are.
+ *
+ * ★ AND THE CLAMP IS REPORTED, NOT HIDDEN. `clamped` is the count of cells painted at the top stop
+ * that are actually above it, so the legend can say "12 cells above 40" rather than implying the
+ * ramp's top is the maximum. A silent clamp is a lie with a percentile in front of it.
+ */
+export function robustDomain(values: readonly number[], percentile = 0.95): Domain {
+  const finite = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
+  if (!finite.length) return { domain: [0, 0], clamped: 0, percentile };
+  const idx = Math.min(finite.length - 1, Math.max(0, Math.ceil(percentile * finite.length) - 1));
+  const top = finite[idx];
+  return {
+    domain: [0, top],
+    clamped: finite.filter((v) => v > top).length,
+    percentile,
+  };
+}
+
+/**
+ * A domain for a SIGNED reading — `[-m, +m]`, symmetric by construction.
+ *
+ * ★ SYMMETRY IS NOT A CONVENIENCE, IT IS THE CLAIM. A diverging ramp says "this far from zero, in this
+ * direction". An asymmetric domain makes the same colour mean +20 on one side and −8 on the other, so
+ * the picture reads as a bias that is an artefact of the scale. Whichever arm is longer sets both.
+ */
+export function symmetricDomain(values: readonly number[], percentile = 0.95): Domain {
+  const mags = values.filter((v) => Number.isFinite(v)).map(Math.abs);
+  const { domain, clamped } = robustDomain(mags, percentile);
+  const m = domain[1];
+  return { domain: [-m, m], clamped, percentile };
+}

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

@@ -0,0 +1,83 @@
+// Reading a coordinate pair out of something a person pasted.
+//
+// ★ THE ORDER IS GENUINELY AMBIGUOUS AND CANNOT ALWAYS BE RESOLVED. GeoJSON, Mapbox and this codebase
+// all say [lng, lat]; Google Maps, every support ticket copied out of it, and most humans say
+// "lat, lng". For London the two are far apart (51.5 and -0.05) and the pair reads unambiguously, but
+// `1.5, 2.5` is a real location under either reading and no amount of cleverness settles it.
+//
+// So: use the range where it decides, and fall back to the convention people TYPE rather than the one
+// the format uses. Anything above 90 cannot be a latitude, which resolves most real pastes on its own.
+
+/** [lng, lat], the order the rest of the map subsystem speaks. */
+export type LngLat = [number, number];
+
+export interface ParseCoordinatesOptions {
+  /**
+   * What an ambiguous pair means — both readings valid, neither number above 90.
+   * @default 'lat-first' — what a person pastes out of Google Maps
+   */
+  assume?: 'lat-first' | 'lng-first';
+}
+
+const PAIR = /^\s*(-?\d+(?:\.\d+)?)\s*[,\s]\s*(-?\d+(?:\.\d+)?)\s*$/;
+
+/**
+ * A coordinate pair, or null when the text is not one.
+ *
+ * Null rather than a guess: this feeds a search field where every other source is also being asked,
+ * and a loose parser that read "4412" or "E9 6NU" as a position would put a nonsense location above
+ * the vehicle someone was actually looking for.
+ */
+export function parseCoordinates(text: string, options: ParseCoordinatesOptions = {}): LngLat | null {
+  const match = PAIR.exec(text);
+  if (!match) return null;
+
+  const a = Number(match[1]);
+  const b = Number(match[2]);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return null;
+
+  // Above 90 can only be a longitude, which settles the order without any convention.
+  const aIsLng = Math.abs(a) > 90;
+  const bIsLng = Math.abs(b) > 90;
+  if (aIsLng && bIsLng) return null; // two longitudes is not a position
+  const latFirst = bIsLng ? true : aIsLng ? false : (options.assume ?? 'lat-first') === 'lat-first';
+
+  const lat = latFirst ? a : b;
+  const lng = latFirst ? b : a;
+  if (Math.abs(lat) > 90 || Math.abs(lng) > 180) return null;
+  return [lng, lat];
+}
+
+/** How a coordinate pair is written back to a reader — [lng, lat] in, "lat, lng" out. */
+export function formatCoordinates([lng, lat]: LngLat, places = 5): string {
+  return `${lat.toFixed(places)}, ${lng.toFixed(places)}`;
+}
+
+/** Web Mercator at the equator, for a 512px tile — the constant mapbox's zoom scale is built on. */
+const METRES_PER_PIXEL_Z0 = 156543.03392;
+/** One degree of latitude, in metres. Longitude narrows with latitude; latitude does not. */
+const METRES_PER_DEGREE = 111320;
+
+/**
+ * How many decimals a readout may honestly print at this camera.
+ *
+ * ★ PRECISION IS A CLAIM. Five decimals is about a metre. Printed at zoom 3, where a pixel spans
+ * kilometres, four of those digits are noise a reader cannot tell from signal — and a coordinate
+ * copied out of that readout is an address nobody visited. The reading is only ever as fine as the
+ * pixel it was taken from.
+ *
+ * `cos(lat)` is in it because a pixel covers less ground as latitude rises: the same zoom is a finer
+ * reading in Tromsø than in London. Same reason the scale bar measures the canvas rather than
+ * deriving a distance from the zoom level.
+ *
+ * Clamped at both ends — 2 so a world view still names a place rather than a hemisphere, 7 because
+ * past that the projection has nothing left to say.
+ */
+export function coordinatePlaces(zoom: number, lat: number): number {
+  const z = Number.isFinite(zoom) ? zoom : 0;
+  // 89.9 rather than 90: cos(90°) is 0, and a pixel covering no ground asks for infinite decimals.
+  const safeLat = Number.isFinite(lat) ? Math.min(Math.abs(lat), 89.9) : 0;
+  const metresPerPixel = (METRES_PER_PIXEL_Z0 * Math.cos((safeLat * Math.PI) / 180)) / 2 ** z;
+  const places = Math.ceil(-Math.log10(metresPerPixel / METRES_PER_DEGREE));
+  return Math.min(7, Math.max(2, Number.isFinite(places) ? places : 2));
+}

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

@@ -0,0 +1,401 @@
+// HOW MUCH, painted on the map — the ground paint for a quantity and for a signed gap.
+//
+// Zones say what the rules are and marks say where each vehicle is. Between them there was nothing
+// that answered "where is demand", "where did the faults cluster", "which cells are short of bikes".
+// This is that layer, and like `zone.ts` it is PAINT rather than a component: the style spec already
+// says everything a fill needs to say.
+//
+// ★ THIS MODULE IS BINS AND BALANCE ONLY. The kernel field lives in `heat.ts` and shares nothing with
+//   this one but a basemap. A bin is a COUNTED CELL: it has a size, an id, a hoverable edge, a
+//   resolution on a ladder and a domain in per-cell totals. A field has none of those. They were one
+//   function with one `kind` flag and one `domain`, and the word meant two different things depending
+//   on the branch — which is how a heat layer handed a bins domain scaled every event to a twentieth
+//   of its weight and painted a blank map without failing.
+//
+//   The rule between them survives the split: HEAT FOR THE GLANCE, BINS FOR THE DECISION. A dispatch
+//   instruction — send twelve bikes to this cell — may never be read off a kernel field, which is why
+//   bins step and heat interpolates. The smooth one is the one you cannot read a number from.
+//
+// ★ ABSENT IS ABSENT; ZERO IS A READING. A cell nobody counted is not painted (see `joinCellValues`,
+//   which refuses to write a zero it was not given, and the `['has', …]` filter below). A cell counted
+//   as none IS painted, at the palest stop, because "we looked and there was nothing" is information.
+//   This is also why opacity does not ramp with the value: that would erase the distinction and
+//   double-encode one number in two channels, making the low cells the hardest to see and to hover.
+//
+// ★ THE TWO RAMPS FLIP IN TWO DIFFERENT PLACES, AND EACH IS THE ONLY WAY IN.
+//   The SEQUENTIAL ramp is sampled from the engine by `ramp.ts`, which reverses the stop order after
+//   dark — every bucket count lands on a real engine stop, which is what stopped a seven-bucket map
+//   asking for an alias that did not exist and painting grey.
+//   The DIVERGING ramp is sampled the same way, except for its CENTRE — "no meaningful gap" is not a
+//   position on any ramp, so that one stop stays a token (`--forest-map-balance-centre`). Its arms
+//   reverse WITHIN themselves rather than end to end, so blue keeps meaning short after dark.
+//   Either way nothing in this file knows which mode it is in, and no caller is asked to remember —
+//   the house rule elsewhere ("consumers invert the stop order in dark mode") is a trap on GL, where a
+//   surface that forgets ships a map meaning the opposite thing after dark with nothing failing.
+import { MAP_SLOT, token, type OverlayLayer } from './useMapOverlay';
+import { H3_EDGE_M } from './bin';
+import { divergingStops, rampStops, type DivergingRamp, type SequentialRamp } from './ramp';
+
+/**
+ * ★ THE ALPHA CEILING, AND IT IS MEASURED (`bun scripts/mapDensity.ts`).
+ *
+ * Two independent reasons land on the same number. The basemap has to survive underneath — a density
+ * layer that hides the streets stops being a map and becomes a chart with a coastline. And the
+ * distance from a composited stop to the nearest hue the map has already spent (the vivid categorical
+ * set the vehicle marks draw from) collapses from ΔE00 15 at 0.5 to 8 at 0.65, which is where a
+ * reader starts mistaking ground paint for a mark.
+ */
+export const DENSITY_ALPHA = 0.5;
+
+/**
+ * ★ FIVE STOPS, AND FIVE IS A CEILING RATHER THAN A PREFERENCE.
+ *
+ * Composited at DENSITY_ALPHA over Standard's worst ground, five stops of the brand ramp still clear
+ * ΔE00 5.6 between neighbours; the sixth does not. viridis and magma sustain nine — and that is the
+ * reason to refuse them here, not to prefer them: the house already documents that a reader recovers
+ * RANK from a shade and not a value, so nine steps is a promise nobody can use, bought with the brand.
+ */
+export const DENSITY_STEPS = 5;
+
+/** Nine, because a diverging ramp needs a centre stop and four rungs of magnitude on each arm. */
+export const BALANCE_STEPS = 9;
+
+/**
+ * The bin ramp's stops for a bucket count — the brand family, sampled and dark-flipped by `ramp.ts`.
+ *
+ * ★ SAMPLED, NOT ALIASED. There used to be a `--forest-map-density-*` block in forest.css naming five
+ * positions, and a seven-bucket map asked it for a sixth that did not exist — an undefined var in a GL
+ * paint property falls back to the inherited colour rather than failing, so London's densest cells
+ * painted grey under a green legend. Sampling cannot name a colour that is not there.
+ */
+export const densityStops = (steps: number, ramp: SequentialRamp = 'forest') => rampStops(ramp, steps);
+
+/** The balance ramp's stops — arms sampled from the engine, centre from the one token not on a ramp. */
+export const balanceStops = (ramp: DivergingRamp = 'blueOrange') => divergingStops(ramp);
+
+// ── expressions ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A `step` over the domain — n buckets, ascending, one token per bucket.
+ *
+ * ★ STEP, NEVER INTERPOLATE, and the flat-domain guard is not a nicety. Mapbox requires a `step`'s
+ * stops to ascend strictly; a domain of [0, 0] (an empty feed, a single reading, everything clamped to
+ * one value) produces duplicates, and mapbox REJECTS the layer without raising — the layer is simply
+ * absent and the map looks subtly wrong forever. A degenerate domain paints one flat colour instead.
+ */
+export function stepColour(prop: string, domain: [number, number], steps: number, tokenAt: (i: number) => string): unknown {
+  const [lo, hi] = domain;
+  if (!(hi > lo)) return token(tokenAt(steps - 1));
+  const expr: unknown[] = ['step', ['get', prop], token(tokenAt(0))];
+  for (let i = 1; i < steps; i++) {
+    expr.push(lo + ((hi - lo) * i) / steps, token(tokenAt(i)));
+  }
+  return expr;
+}
+
+/** The bucket edges a legend has to label — the same arithmetic `stepColour` paints with. */
+export function stepEdges(domain: [number, number], steps: number): number[] {
+  const [lo, hi] = domain;
+  return Array.from({ length: steps + 1 }, (_, i) => lo + ((hi - lo) * i) / steps);
+}
+
+// ── layers ──────────────────────────────────────────────────────────────────────────────────────
+
+export interface DensityOptions {
+  /** source id holding the counted cells */
+  source: string;
+  /** the value range the ramp spans. STATE IT — see the note on viewport-relative domains below */
+  domain: [number, number];
+  /** feature property holding the reading. Default `value` */
+  prop?: string;
+  /** id prefix, so two density overlays can coexist. Default `density` */
+  prefix?: string;
+  /**
+   * Which sequential family the buckets paint in. Default `forest`.
+   *
+   * ⚠ TWO BIN MAPS IN ONE CONSOLE SHOULD SHARE A RAMP. Unlike a field — an impression, where telling
+   * two layers apart is worth more than matching them — a bin map is read against a legend, and two
+   * screenshots of the same city in different ramps invite comparisons that are not there. The default
+   * is the measured pick; changing it is a surface-level decision, not a per-view one.
+   */
+  ramp?: SequentialRamp;
+  /**
+   * How many buckets the ramp is cut into. Default DENSITY_STEPS (5), which is a MEASURED ceiling.
+   *
+   * ★ FEWER IS ALWAYS SAFE; MORE STOPS WORKING, and it stops working silently. Composited over
+   * Standard's worst ground at DENSITY_ALPHA, five buckets of the brand ramp still clear ΔE00 5.6
+   * between neighbours; a sixth lands inside the threshold and two adjacent buckets become one colour
+   * to the reader, which makes the legend a promise the paint cannot keep. Three or four is an
+   * editorial choice needing no permission. Six or more is a decision to show a distinction that is
+   * not there — /maps/density has a control that lets you watch it collapse.
+   *
+   * ⚠ PASS THE SAME NUMBER TO `densityLegend()`. The layer and its key cut the domain independently,
+   * so a mismatch labels buckets the map never paints.
+   */
+  steps?: number;
+  /** draw the cell edges. Default true */
+  hairline?: boolean;
+  /** opacity ceiling. Default DENSITY_ALPHA, and going past it is a deliberate act */
+  alpha?: number;
+}
+
+/**
+ * The layers for a density overlay.
+ *
+ * ★ THE DOMAIN IS STATED, NEVER TAKEN FROM THE VIEWPORT. A domain fitted to what is on screen re-scales
+ * as the reader pans, so the same cell changes colour because its NEIGHBOURS changed — the map appears
+ * to respond to panning, which is the one thing it must never appear to do. `robustDomain()` in bin.ts
+ * computes one from the whole feed, once.
+ *
+ * ★ IT SITS IN `MAP_SLOT.route` (`middle`), NOT WITH THE ZONES, and the difference is what each layer
+ * is for. `bottom` is above the polygons and BELOW the entire road network, which is right for a zone:
+ * a boundary is a rule about a region, the streets inside it stay fully legible, and the rule is not
+ * something the reader is measuring. Density IS the thing being measured, and buried under every road
+ * casing, every carriageway fill and every bridge, it reads as a smudge — measured on the demo map,
+ * where a heat field in `bottom` came back as grey haze under Bloomsbury's streets.
+ *
+ * `middle` still sits behind the 3D buildings, behind the basemap's labels and — the part that matters
+ * — behind every mark, which stay in `top`. A mark is the data; this is the quantity behind it, and it
+ * may never cover one.
+ */
+export function densityLayers(opts: DensityOptions): OverlayLayer[] {
+  const {
+    source,
+    domain,
+    prop = 'value',
+    prefix = 'density',
+    ramp = 'forest',
+    steps = DENSITY_STEPS,
+    hairline = true,
+    alpha = DENSITY_ALPHA,
+  } = opts;
+
+  const layers: OverlayLayer[] = [
+    {
+      id: `${prefix}-fill`,
+      type: 'fill',
+      source,
+      slot: MAP_SLOT.route,
+      // ★ Absent is absent: a cell that carries no reading is not painted at all. Without this filter
+      // an unvalued cell falls into the `step`'s first bucket and is published as a counted zero.
+      filter: ['has', prop],
+      paint: {
+        'fill-color': stepColour(prop, domain, steps, (i) => densityStops(steps, ramp)[i]),
+        'fill-opacity': alpha,
+        // fill-emissive-strength is injected by useMapOverlay — `fill` is a shaded type, and an unlit
+        // overlay paints at about a fifth of its luminance under the night preset.
+      },
+    },
+  ];
+
+  if (hairline) {
+    layers.push({
+      id: `${prefix}-edge`,
+      type: 'line',
+      source,
+      slot: MAP_SLOT.route,
+      filter: ['has', prop],
+      paint: {
+        // ★ THE SEAM IS INK, NOT A THIRD COLOUR. Adjacent cells one step apart are separable but not
+        // instantly countable; a hairline restores the grid as a texture. It takes the inverted
+        // background — dark on a light map, light on a dark one — so it reads as a seam between cells
+        // rather than as another value in the ramp.
+        'line-color': token('--ui-bg-inverted'),
+        'line-width': 0.5,
+        'line-opacity': 0.15,
+      },
+    });
+  }
+
+  return layers;
+}
+
+export interface BalanceOptions extends Omit<DensityOptions, 'ramp' | 'steps'> {
+  /**
+   * Which diverging family the arms paint in. Default `blueOrange`.
+   *
+   * ★ THE DEFAULT IS MEASURED, NOT CONVENTIONAL. blueOrange holds ΔE00 25 between its arms under the
+   * worst dichromacy against redBlue's 18, purpleGreen's 14 and forestWarm's 7 — and it keeps off red
+   * and amber, which are spent on severity here (the no-parking zone, the critical battery ring). A
+   * balance is not a severity. `redBlue` is what the fleet console paints today, so it is the one to
+   * reach for while a surface is migrating.
+   */
+  ramp?: DivergingRamp;
+  /**
+   * Readings this close to zero are NOT PAINTED — the honest absence.
+   *
+   * A balance is a gap against an expectation, and an expectation has a band. Inside it there is
+   * nothing to report, and reporting it anyway ("slightly over") invites acting on noise.
+   */
+  deadband?: number;
+}
+
+/**
+ * The layers for a signed balance — surplus against deficit, around zero.
+ *
+ * ★ BINS ONLY. A kernel field is a density of points and carries no sign; there is no honest way to
+ * heat-map a quantity that can be negative, because the two arms would add rather than cancel.
+ *
+ * ★ MAGNITUDE IS THE POINT. The console this replaces reduced the reading to a three-valued status
+ * before painting, so a cell one bike over the band and a cell forty over painted identically. The
+ * ramp carries the size of the gap; the SIGN carries its direction; and the deadband — not a third
+ * colour — carries "no claim".
+ */
+export function balanceLayers(opts: BalanceOptions): OverlayLayer[] {
+  const {
+    source,
+    domain,
+    prop = 'value',
+    prefix = 'balance',
+    ramp = 'blueOrange',
+    hairline = true,
+    alpha = DENSITY_ALPHA,
+    deadband = 0,
+  } = opts;
+
+  // ★ The domain must be symmetric or the same colour means +20 on one arm and −8 on the other, and
+  // the map reads as a bias that is an artefact of the scale. `symmetricDomain()` builds one.
+  if (domain[0] !== -domain[1]) {
+    throw new Error(
+      `balanceLayers: domain must be symmetric around zero, got [${domain[0]}, ${domain[1]}]. Use symmetricDomain().`,
+    );
+  }
+
+  const painted: unknown[] = deadband > 0 ? ['>', ['abs', ['get', prop]], deadband] : ['has', prop];
+  const filter: unknown[] = deadband > 0 ? ['all', ['has', prop], painted] : painted;
+
+  const layers: OverlayLayer[] = [
+    {
+      id: `${prefix}-fill`,
+      type: 'fill',
+      source,
+      slot: MAP_SLOT.route,
+      filter,
+      paint: {
+        'fill-color': stepColour(prop, domain, BALANCE_STEPS, (i) => balanceStops(ramp)[i]),
+        'fill-opacity': alpha,
+      },
+    },
+  ];
+
+  if (hairline) {
+    layers.push({
+      id: `${prefix}-edge`,
+      type: 'line',
+      source,
+      slot: MAP_SLOT.route,
+      filter,
+      paint: {
+        'line-color': token('--ui-bg-inverted'),
+        'line-width': 0.5,
+        'line-opacity': 0.15,
+      },
+    });
+  }
+
+  return layers;
+}
+
+// ── the legend model ────────────────────────────────────────────────────────────────────────────
+
+export interface RampStop {
+  key: string;
+  /** a token NAME — the swatch is DOM and references it directly, like MapLegendItem.colour */
+  colour: string;
+  from: number;
+  to: number;
+  label: string;
+}
+
+export interface RampLegend {
+  kind: 'density' | 'balance';
+  stops: RampStop[];
+  /** what one reading counts, e.g. "rides" — the legend is meaningless without it */
+  unit?: string;
+  /** cell width in metres, when the readings are binned. Printed so the unit is never implicit */
+  cellM?: number;
+  /** readings above the domain, painted at the top stop. Stated rather than hidden */
+  clamped?: number;
+  percentile?: number;
+}
+
+const fmt = (v: number, span: number): string => {
+  const n = span >= 10 ? Math.round(v) : Math.round(v * 10) / 10;
+  return String(n);
+};
+
+export interface LegendOptions {
+  domain: [number, number];
+  /** the family the layer painted with — the key has to match it or the swatches lie */
+  ramp?: SequentialRamp | DivergingRamp;
+  /** must match the layer's `steps`, or the key describes buckets the map never paints */
+  steps?: number;
+  unit?: string;
+  /** H3 resolution the cells are binned at — turns into the stated cell size */
+  res?: number;
+  clamped?: number;
+  percentile?: number;
+  deadband?: number;
+}
+
+/** Legend rows for a density ramp — one per painted bucket, labelled in the reading's own units. */
+export function densityLegend(opts: LegendOptions): RampLegend {
+  const { domain, unit, res, clamped, percentile, steps = DENSITY_STEPS } = opts;
+  const stops = densityStops(steps, (opts.ramp as SequentialRamp) ?? 'forest');
+  const edges = stepEdges(domain, steps);
+  const span = domain[1] - domain[0];
+  return {
+    kind: 'density',
+    unit,
+    cellM: res != null ? Math.round(2 * H3_EDGE_M[res]) : undefined,
+    clamped,
+    percentile,
+    stops: edges.slice(0, -1).map((from, i) => ({
+      key: String(i),
+      colour: stops[i],
+      from,
+      to: edges[i + 1],
+      // The top bucket is open — everything at or above its floor is painted there, including the
+      // clamped readings, so a closed label would understate it.
+      label: i === steps - 1 ? `${fmt(from, span)}+` : `${fmt(from, span)}–${fmt(edges[i + 1], span)}`,
+    })),
+  };
+}
+
+/**
+ * Legend rows for a balance ramp.
+ *
+ * ★ IT READS OUTWARD FROM ZERO, not left to right. The reader's question is "how far off, and which
+ * way", so the centre is the anchor and each arm is labelled by its own direction. The deadband, when
+ * there is one, is a row of its own saying what is deliberately not painted.
+ */
+export function balanceLegend(opts: LegendOptions & { low?: string; high?: string }): RampLegend {
+  const { domain, unit, res, clamped, percentile, deadband = 0, low = 'short', high = 'over' } = opts;
+  const stops = balanceStops((opts.ramp as DivergingRamp) ?? 'blueOrange');
+  const edges = stepEdges(domain, BALANCE_STEPS);
+  const span = domain[1] - domain[0];
+  const mid = Math.floor(BALANCE_STEPS / 2);
+  return {
+    kind: 'balance',
+    unit,
+    cellM: res != null ? Math.round(2 * H3_EDGE_M[res]) : undefined,
+    clamped,
+    percentile,
+    stops: edges.slice(0, -1).map((from, i) => {
+      const to = edges[i + 1];
+      const centre = i === mid;
+      const arm = i < mid ? low : high;
+      return {
+        key: String(i),
+        colour: stops[i],
+        from,
+        to,
+        label: centre
+          ? deadband > 0
+            ? `within ${fmt(deadband, span)}`
+            : 'on target'
+          : `${fmt(Math.abs(i < mid ? to : from), span)}+ ${arm}`,
+      };
+    }),
+  };
+}