@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,329 @@
+// Fleet scale — the constants and ramps that must agree across surfaces.
+//
+// A fleet map is drawn twice: as CIRCLES while the whole city is on screen (30,000 DOM elements is not
+// a thing anyone can afford), and as SYMBOLS once the camera is close enough for a bike glyph to read.
+// The zoom at which one becomes the other is the seam, and it has to be the same number in the web
+// console, the rider app and the docs — a mismatch is a fleet that changes size or disappears when a
+// user moves between surfaces. So it lives here, exported, rather than being typed into each layer.
+//
+// Every ramp below is a style-spec expression: `useMapOverlay` passes them through untouched, and they
+// evaluate on the GPU rather than in a watcher.
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// THE DOUBLING INTERVAL — the one knob behind every size ramp on a map
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * ★★ Zoom is log₂ of ground scale, so EVERY marker size ramp is an exponential — whether or not the
+ * word `exponential` appears in it. Its base answers one question, and it is not a question of taste:
+ * how much of the mark's size belongs to the WORLD rather than to the screen?
+ *
+ * State the answer as a DOUBLING INTERVAL — the zoom levels over which the mark doubles — because that
+ * is the form a human can check against the artwork.
+ *
+ *     base = 2 ** (1 / Z₂)
+ *
+ * The base is a DECLUTTER RATE. Visible features go as 4^−Δz and ink as N·r², so the ink on screen
+ * after zooming in one level, as a fraction of what it was:
+ *
+ *     D = (base / 2)² = 4 ** (1 / Z₂ − 1)
+ *
+ *     Z₂  ∞    base 1.00    D 0.25    screen-anchored — the mark is purely "read me"
+ *     Z₂  5    base 1.15    D 0.33    the street tier
+ *     Z₂  2    base 1.41    D 0.50    ink halves per zoom level
+ *     Z₂  1    base 2.00    D 1.00    world-anchored — never declutters
+ *
+ * ★★ Z₂ = 1 IS NOT A MARKER. A mark that holds its ground size has real extent, and a thing with
+ *    extent is geometry — a `fill` or a `line` measured in metres — not a point identity. Every
+ *    Forest marker sits in Z₂ ∈ [2, ∞]. Reaching for base 2 means the wrong layer type was chosen.
+ */
+export const zoomBase = (doubling: number): number => 2 ** (1 / doubling);
+
+/** Ink on screen after zooming in one level, as a fraction of what it was. See {@link zoomBase}. */
+export const declutterRate = (doubling: number): number => 4 ** (1 / doubling - 1);
+
+/**
+ * The doubling interval a pair of endpoints IMPLIES.
+ *
+ * Not every ramp gets to choose Z₂. Where both ends are already pinned by something else — the mass
+ * tier's top must equal the disc it turns into, its bottom is the city-view ink budget — Z₂ is an
+ * OUTPUT. Report it; do not move the artwork to reach a rounder number.
+ */
+export const doublingInterval = (z1: number, v1: number, z2: number, v2: number): number =>
+  (z2 - z1) / Math.log2(v2 / v1);
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// THE ARTWORK, AND THE FLOOR IT IMPOSES
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** The marker asset's canvas, in its own units. Every dimension below is read off that same file. */
+export const MARKER_CANVAS_UNITS = 40;
+/** The disc — the body a reader sees as "the mark". The battery ring sits outside it. */
+export const DISC_R_UNITS = 14.4;
+/** Every stroke on the asset: the inner edge, the battery edge, each corner mark's outline. */
+export const EDGE_STROKE_UNITS = 1.6;
+
+/**
+ * ★★ THE LEGIBILITY FLOOR — `icon-size` 0.625, a 25px mark. MEASURED on the published style.
+ *
+ * Probed by PEAK PURITY: for each region, the closest pixel to the colour it was given, and the share
+ * of its own fill area within ΔE 5 of it. Antialiasing CAPS what a shrinking region can reach, and
+ * that cap is what "it stopped being its colour" physically means. (A mean over the region is a trap —
+ * it always includes the region's own stroke, which is a constant bias reported as a signal.)
+ *
+ *     icon-size   mark px   badge pure   dot pure   edge px   edge ΔE
+ *       0.42        16.8       31 %        54 %       0.67       4.0
+ *       0.55        22         39 %        47 %       0.88       0.2
+ *       0.625       25         53 %        64 %       1.00       0      ← the knee
+ *       0.78        31.2       59 %        58 %       1.25       0
+ *       1.30        52         75 %        71 %       2.08       0
+ *
+ * Corner marks cross half their own area at 0.625, and it is the same rung where the edge first
+ * reaches a full pixel. ONE FLOOR, TWO CHANNELS — which is why this is a single constant.
+ *
+ * Identical on gl 3.24.1 and 3.28.1, so the number is not a version artefact.
+ *
+ * ⚠ SUPERSEDES a recorded "0.88px → ΔE 88" edge cliff, which does not reproduce: peak ΔE at 0.88px is
+ *   0.2 — a pixel still reaches pure white. What degrades below a pixel is the edge's COVERAGE, not
+ *   its hue. The old figure was most likely a point sample that missed a sub-pixel stroke.
+ */
+export const MARKER_MIN_ICON_SIZE = 0.625;
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// THE SEAM
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Below this zoom a fleet is circles; at or above it, symbols.
+ *
+ * ★ The crossover goes where the INCOMING tier already clears its own floor — not where the outgoing
+ *   tier stops being affordable. The street tier enters at {@link MARKER_MIN_ICON_SIZE}, so it is
+ *   legible from its first frame and the mass tier is free to leave on its own schedule.
+ */
+export const MARKER_CROSSOVER_ZOOM = 15;
+
+/**
+ * ★★ THE DISSOLVE BAND — the zooms over which one tier becomes the other.
+ *
+ * The tiers do NOT cross-fade. Compositing the symbol (alpha b, on top) over the circle (alpha a)
+ * gives coverage `b + a(1 − b)`, so the obvious complementary fade — a = 1 − b — bottoms out at
+ * 0.5 + 0.5² = **0.75 at the midpoint**: the whole fleet visibly washes out halfway through the band
+ * and comes back. Holding coverage at 1 requires a = 1 for every b < 1.
+ *
+ * So the circle stays FULLY OPAQUE while the symbol fades in on top of it, and only leaves afterwards
+ * — by which point the symbol, which is strictly larger, already hides it completely.
+ *
+ * Two registrations make the dissolve almost invisible where the marks agree, which is most of them:
+ *   · the mass radius reaches {@link CROSSOVER_RADIUS_PX} at the band's START and holds, so both discs
+ *     are 9px across the whole band — disc colour fades in over the same disc colour, a no-op.
+ *   · the circle's 1px halo spans r9→r10, and the symbol's inner edge (1.6 units at r15.2, scaled by
+ *     0.625) spans r9.0→r10.0 — the SAME pixels, the same `--ui-bg`. Also a no-op.
+ * What is left to see is exactly the honest difference between the tiers: the battery ring outside
+ * r10, and the glyph in the middle. Those materialise; nothing jumps.
+ *
+ * ⚠ The symbol layer's `minzoom` must be the band START, not the crossover. A layer minzoom is a HARD
+ *   CUT — it was the whole bug: the symbol appeared at full opacity in one frame while the circle
+ *   faded out underneath it, unseen. Measured at 46.7 ΔE in a single 0.05 zoom step at the disc
+ *   centre, against ≤ 1.0 for every other step in the sweep.
+ */
+export const DISSOLVE_START_ZOOM = 14.5;
+export const DISSOLVE_END_ZOOM = 15.5;
+
+/** Where the street ramp tops out and the mark stops growing. */
+export const MARKER_RAMP_TOP_ZOOM = 18;
+
+/** Z₂ for the street tier — CHOSEN. The mark doubles every five zoom levels. D ≈ 0.33. */
+export const STREET_DOUBLING = 5;
+
+/**
+ * Derived, never typed beside the floor: 0.625 doubled over five levels ⇒ 0.884, a 35px mark.
+ *
+ * ★ The ramp starts at the band's END, not at the crossover. The mark holds its floor size for the
+ *   whole dissolve — growing while it fades in would push its disc out past the circle underneath and
+ *   open the translucent annulus the registration above exists to avoid. It grows once it is alone.
+ */
+export const MARKER_MAX_ICON_SIZE =
+  MARKER_MIN_ICON_SIZE * zoomBase(STREET_DOUBLING) ** (MARKER_RAMP_TOP_ZOOM - DISSOLVE_END_ZOOM);
+
+/** FMarker's rendered pin diameters, in px. DOM marks do not answer to zoom — they are Z₂ = ∞. */
+export const MARKER_PX = { sm: 24, md: 28, lg: 36 } as const;
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// THE RAMPS
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The mass tier's radius at the crossover IS the disc it is about to become — derived, so the two
+ * tiers cannot drift apart. `MARKER_PX.md / 4` used to stand here and sat 11 % under the disc.
+ */
+export const CROSSOVER_RADIUS_PX = DISC_R_UNITS * MARKER_MIN_ICON_SIZE;
+
+/** The city-view radius: the ink budget for the whole fleet on screen at once. */
+export const MASS_MIN_RADIUS_PX = 2;
+export const MASS_MIN_ZOOM = 10;
+
+/** Z₂ for the mass tier — REPORTED, not chosen: both endpoints are pinned above. ≈ 2.3 levels. */
+export const MASS_DOUBLING = doublingInterval(
+  MASS_MIN_ZOOM,
+  MASS_MIN_RADIUS_PX,
+  DISSOLVE_START_ZOOM,
+  CROSSOVER_RADIUS_PX,
+);
+
+/**
+ * Mass-tier radius. Ink coverage is quadratic in the EFFECTIVE radius — fill plus the halo stroke,
+ * which paints outside it — so this stays small where features are dense and only opens up as the
+ * camera closes in and the same features spread out.
+ *
+ * ★ ONE `exponential`, not three linear stops. The old form carried a middle stop at z13 whose only
+ *   job was to fake this curve; a stop that shapes a curve rather than stating a value is a fudge.
+ *   Over five zoom levels the difference is real — under three it would not be (see markerIconSize).
+ */
+export const fleetCircleRadius = (): unknown[] => [
+  'interpolate',
+  ['exponential', zoomBase(MASS_DOUBLING)],
+  ['zoom'],
+  MASS_MIN_ZOOM,
+  MASS_MIN_RADIUS_PX,
+  // ★ tops out at the band's START and holds there — `interpolate` clamps above its last stop. The
+  //   circle must already be the size of the disc it becomes BEFORE the symbol starts fading in, or
+  //   the symbol's disc overhangs a smaller circle and the overhang shows as a translucent ring.
+  DISSOLVE_START_ZOOM,
+  CROSSOVER_RADIUS_PX,
+];
+
+/**
+ * The halo. It is what separates one mark from the next over a busy basemap — and it is also the ink
+ * budget's biggest term, because a stroke paints OUTSIDE the radius: r=2 with a 1px stroke covers
+ * π·9, not π·4. So it stays off while the whole city is on screen, and arrives once marks have room.
+ *
+ * ★ INTERPOLATED, not stepped. As a `step` at z12.5 it switched 0 → 1px in one frame on an r≈3.7
+ *   circle — covered area (4.7/3.7)² = +62 % of the fleet's ink, instantly, which reads as a pop.
+ *   Step on IDENTITY; interpolate on SIZE.
+ */
+export const fleetCircleStroke = (): unknown[] => [
+  'interpolate',
+  ['linear'],
+  ['zoom'],
+  12,
+  0,
+  13,
+  1,
+];
+
+/**
+ * The mass tier HOLDS while the symbol tier arrives, then leaves.
+ *
+ * ★ It does not fade against the incoming tier — see {@link DISSOLVE_START_ZOOM} for why a
+ *   complementary cross-fade washes the fleet out to 75 % coverage at the midpoint. By the time this
+ *   drops, the symbol is at full alpha and strictly larger, so the circle is already hidden and the
+ *   drop cannot be seen. It is a short ramp rather than a step only so that nothing depends on the
+ *   two layers being composited in a particular order on the last frame.
+ */
+export const fleetCircleOpacity = (): unknown[] => [
+  'interpolate',
+  ['linear'],
+  ['zoom'],
+  DISSOLVE_END_ZOOM,
+  1,
+  DISSOLVE_END_ZOOM + 0.1,
+  0,
+];
+
+/**
+ * The street tier ARRIVES. Zero at the band's start — where the layer's `minzoom` lets it in, so the
+ * hard cut lands on an invisible mark — and one at the band's end.
+ *
+ * ⚠ `icon-opacity` is the only lever here: a layer `minzoom` is a hard cut with no fade of its own,
+ *   which is exactly what made the old seam a pop.
+ */
+export const fleetSymbolOpacity = (): unknown[] => [
+  'interpolate',
+  ['linear'],
+  ['zoom'],
+  DISSOLVE_START_ZOOM,
+  0,
+  DISSOLVE_END_ZOOM,
+  1,
+];
+
+/**
+ * The street tier's WHOLE size control. Because the artwork's proportions are RATIOS — the ring is a
+ * fifth of the disc's radius by construction — this one ramp scales every region together.
+ *
+ * ★ `['linear']`, deliberately. Over the 2.5 levels this spans, linear and `['exponential', 1.149]`
+ *   differ by 1.5 % at their farthest point (measured at the midpoint: 0.755 against 0.744) — which is
+ *   invisible, and readable stops are worth more than a curve nobody can see. Reach for `exponential`
+ *   past about four levels, where a linear ramp starts needing a fake middle stop to hide its kink.
+ *
+ * ★ THE STREET TIER HAS NO RADIUS RAMPS. There used to be three — `spriteRadius()`,
+ *   `markerRingRadius()` and a `MARKER_RING_STROKE = 3` — because the ring and the offline dot were
+ *   their own `circle` layers stacked around the sprite. They are regions of the uploaded icon now, so
+ *   the street tier is one symbol layer and `icon-size` is its only size control. Deleted rather than
+ *   deprecated: a fixed 3px stroke on a 12.5px disc is a ratio of 0.24, and the asset's ring is a
+ *   fifth of the disc's radius. Two numbers for one edge is how a mark drifts.
+ */
+export const markerIconSize = (): unknown[] => [
+  'interpolate',
+  ['linear'],
+  ['zoom'],
+  // `interpolate` clamps below its first stop, so the mark sits at its floor for the whole dissolve —
+  // which is what keeps it registered against the circle underneath it.
+  DISSOLVE_END_ZOOM,
+  MARKER_MIN_ICON_SIZE,
+  MARKER_RAMP_TOP_ZOOM,
+  MARKER_MAX_ICON_SIZE,
+];
+
+/**
+ * The zoom at which the street ramp reaches a given `icon-size` — {@link markerIconSize} inverted,
+ * clamped to the ramp's own span.
+ *
+ * ★ It exists so an ASSET THRESHOLD can become a ZOOM without anyone typing the zoom. A region of the
+ *   marker becomes legible at some `icon-size` — a property of the artwork, which the generator
+ *   measures and puts in the manifest — and a layer needs to know which zoom that is, which is a
+ *   property of the ramp. Two files, one number, and this is the only place they meet.
+ */
+export const zoomAtIconSize = (size: number): number => {
+  if (size <= MARKER_MIN_ICON_SIZE) return DISSOLVE_END_ZOOM;
+  if (size >= MARKER_MAX_ICON_SIZE) return MARKER_RAMP_TOP_ZOOM;
+  const span = MARKER_RAMP_TOP_ZOOM - DISSOLVE_END_ZOOM;
+  return (
+    DISSOLVE_END_ZOOM +
+    (span * (size - MARKER_MIN_ICON_SIZE)) / (MARKER_MAX_ICON_SIZE - MARKER_MIN_ICON_SIZE)
+  );
+};
+
+/**
+ * ★★ THE CLAMP ON `map.setScaleFactor()` — never leave it implicit.
+ *
+ * Mapbox's default is `[0.8, 2]`, which permits a 0.8× DOWNSCALE. Forest cannot allow that: the ramp's
+ * minimum IS the mark's measured legibility floor, where every stroke paints exactly 1.00px, so
+ * anything below 1× puts the whole mark under it — quietly, everywhere, for a reader who asked for
+ * BIGGER type. A floor that the size ramp defends and a scale factor walks straight through is not a
+ * floor.
+ *
+ * MEASURED on 3.28.1 — the clamp is real in both directions. One mark, rendered radius:
+ *
+ *     factor 1.0                 15.0px
+ *     factor 1.5                 22.5px    exactly 1.5×
+ *     factor 2.0                 30.5px
+ *     factor 3.0                 30.5px    clamped by the max
+ *     factor 0.5, range [1, 2]   15.0px    clamped by the min — the floor holds
+ *
+ * ⚠ `map.getScaleFactor()` reports what was SET, not what renders: it returns 3 while the mark is
+ *   drawn at 2, and 0.5 while it is drawn at 1. Never read it back as the effective scale.
+ */
+export const MARKER_SIZE_SCALE_RANGE: readonly [number, number] = [1, 2];
+
+/**
+ * Symbol-layer layout for a fleet. These are not stylistic — they are the fix for a silent
+ * under-render. Mapbox hides colliding icons by DEFAULT (`icon-allow-overlap: false`), so a dense
+ * fleet quietly draws a fraction of itself and the map looks like fewer bikes rather than a placement
+ * conflict. `symbol-sort-key` then decides who draws on top when they do overlap.
+ */
+export const FLEET_SYMBOL_LAYOUT = {
+  'icon-allow-overlap': true,
+  'icon-ignore-placement': true,
+  'icon-optional': true,
+} as const;

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

@@ -0,0 +1,67 @@
+// The arithmetic behind <FMapScale>: how far the bar says it is, and how much of its track it fills.
+//
+// Out here rather than in the SFC because it is the only part with anything to get wrong, and
+// packages/ui tests run in node with no DOM. The component measures the map and paints; this decides
+// what the number is.
+
+export type ScaleUnit = 'metric' | 'imperial';
+
+export interface ScaleReading {
+  /** the rounded distance, in the reading's own unit */
+  distance: number;
+  /** what the bar is labelled — the distance and its unit, already formatted */
+  label: string;
+  /** how much of the available track the bar fills, 0–1 */
+  ratio: number;
+}
+
+const FEET_PER_METRE = 3.2808399;
+const FEET_PER_MILE = 5280;
+
+/**
+ * The largest 1/2/3/5 × 10ⁿ step that fits inside `max`.
+ *
+ * ★ A scale bar's whole job is a number you can read without arithmetic. Drawing the full available
+ * width and labelling it "1.37 km" is technically accurate and useless — the reader wants a round
+ * stick to hold against the map. So the BAR shrinks to the number rather than the number stretching
+ * to the bar, which is also why this never returns more than it was given.
+ */
+export function roundedDistance(max: number): number {
+  const pow10 = Math.pow(10, Math.floor(Math.log10(max)));
+  const d = max / pow10;
+  const step = d >= 10 ? 10 : d >= 5 ? 5 : d >= 3 ? 3 : d >= 2 ? 2 : 1;
+  // ★ pow10 * step reintroduces binary-float noise below 1 — 0.1 * 3 is 0.30000000000000004 — and
+  // `distance` is public, so it is cleaned here rather than only where the label is formatted.
+  return Number((pow10 * step).toPrecision(12));
+}
+
+/** Trims float noise without printing trailing zeroes — 1.5 stays 1.5, 3.0 becomes 3. */
+const trim = (n: number): string => String(Number(n.toFixed(2)));
+
+/**
+ * What to draw for a track that spans `maxMetres` on the ground.
+ *
+ * Null when the map cannot answer yet — a zero-width canvas during layout, or a degenerate camera.
+ * `Math.log10(0)` is -Infinity and every number downstream becomes NaN, which paints a full-width bar
+ * carrying a meaningless label. An absent scale bar is honest; a lying one is not.
+ */
+export function scaleReading(maxMetres: number, unit: ScaleUnit): ScaleReading | null {
+  if (!(maxMetres > 0) || !Number.isFinite(maxMetres)) return null;
+
+  if (unit === 'imperial') {
+    const maxFeet = maxMetres * FEET_PER_METRE;
+    if (maxFeet >= FEET_PER_MILE) {
+      const miles = roundedDistance(maxFeet / FEET_PER_MILE);
+      return { distance: miles, label: `${trim(miles)} mi`, ratio: (miles * FEET_PER_MILE) / maxFeet };
+    }
+    const feet = roundedDistance(maxFeet);
+    return { distance: feet, label: `${trim(feet)} ft`, ratio: feet / maxFeet };
+  }
+
+  if (maxMetres >= 1000) {
+    const km = roundedDistance(maxMetres / 1000);
+    return { distance: km, label: `${trim(km)} km`, ratio: (km * 1000) / maxMetres };
+  }
+  const metres = roundedDistance(maxMetres);
+  return { distance: metres, label: `${trim(metres)} m`, ratio: metres / maxMetres };
+}

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

@@ -0,0 +1,50 @@
+// One selection, two vocabularies.
+//
+// `useFeatureSelect` holds a Set of feature ids, because that is what a GL layer paints through
+// feature-state. A table holds TanStack's RowSelectionState — `Record<string, boolean>`, keyed by
+// whatever `get-row-id` returned. This is the translation, and it exists for one reason:
+//
+// ★ TANSTACK'S KEYS ARE STRINGS. GL feature ids are frequently NUMBERS — a GeoJSON `id` of 42 stays a
+// number all the way through `queryRenderedFeatures`. `42` and `'42'` are the same row to a person and
+// different keys to both sides, and nothing throws: the table selects nothing, the map paints nothing,
+// and the surface author concludes the composable is broken. Every id crosses this boundary as a
+// string, and the id type is the first thing the tests pin.
+
+export type RowSelection = Record<string, boolean>;
+
+/** The one place an id changes type. Everything downstream of here is a string. */
+export const rowKey = (id: string | number): string => String(id);
+
+/** The id set as a table's selection record. */
+export function toRowSelection(ids: Iterable<string | number>): RowSelection {
+  const out: RowSelection = {};
+  for (const id of ids) out[rowKey(id)] = true;
+  return out;
+}
+
+/**
+ * The selected keys out of a table's record.
+ *
+ * ★ Only the true ones. TanStack keeps a key at `false` after a row is deselected rather than deleting
+ * it, so `Object.keys()` on the record is the set of rows that have EVER been selected — which as a
+ * map selection means the bikes the reader has been clicking all afternoon stay lit.
+ */
+export function selectedKeys(selection: RowSelection): string[] {
+  return Object.keys(selection).filter((key) => selection[key]);
+}
+
+/**
+ * Whether the two sides already agree — the loop guard.
+ *
+ * Map → record → table → record → map is a cycle, and Vue will run it. Comparing by value before
+ * writing either side means a round trip that changes nothing writes nothing. A selection is tens of
+ * ids, not thousands, so this is cheaper than the epoch counter it replaces and impossible to get
+ * subtly wrong.
+ */
+export function sameSelection(ids: Iterable<string | number>, selection: RowSelection): boolean {
+  const keys = selectedKeys(selection);
+  const wanted = new Set<string>();
+  for (const id of ids) wanted.add(rowKey(id));
+  if (keys.length !== wanted.size) return false;
+  return keys.every((key) => wanted.has(key));
+}

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

@@ -0,0 +1,58 @@
+// A coordinate pair, pasted into the search field, answered with the place it names.
+//
+// ★ THE REAL CASE IS A SUPPORT TICKET. Ops work from positions all day — a telemetry log, an incident
+// report, a message from a rider's app — and every one of them carries a lat/lng rather than a street.
+// Pasting it into the field and getting "280 Mare Street, Hackney" is the shortest path from a
+// coordinate someone was handed to the place they have to think about. Mapbox's own search box has
+// `allowReverse` for the same reason.
+//
+// ★ IT ALWAYS CARRIES GEOMETRY, so it never needs `resolve`. The query IS the position — the reverse
+// lookup only supplies the NAME. A failed or empty geocode is therefore still a usable result: the
+// camera can fly to a coordinate nobody has a word for, which is exactly the case on a canal towpath
+// or an industrial estate.
+import { geocoder, type Geocoder } from '../../address';
+import { areaLabel, formatAddress } from '../../address/address';
+import { formatCoordinates, parseCoordinates, type ParseCoordinatesOptions } from '../coordinates';
+import type { MapSearchResult, MapSearchSource } from '../mapSearch';
+
+export interface CoordinateSourceOptions extends ParseCoordinatesOptions {
+  accessToken: string;
+  /** heading shown above the row */
+  label?: string;
+  /** stands in for the geocoder in tests */
+  client?: Pick<Geocoder, 'reverse'>;
+}
+
+export function coordinateSource(options: CoordinateSourceOptions): MapSearchSource {
+  const client = options.client ?? geocoder({ accessToken: options.accessToken });
+
+  return {
+    id: 'coordinates',
+    label: options.label ?? 'Coordinates',
+    icon: 'i-lucide-crosshair',
+    limit: 1,
+
+    // ★ Reserves the best-match row, and should: a pasted coordinate pair is not a fuzzy query with a
+    // ranking, it is an exact statement of where. Cheap and synchronous — it only parses the text.
+    mayMatchExactly: (query) => parseCoordinates(query, options) !== null,
+
+    async search(query, signal): Promise<MapSearchResult[]> {
+      const at = parseCoordinates(query, options);
+      if (!at) return [];
+
+      const address = await client.reverse(at, signal).catch(() => null);
+      const geometry: GeoJSON.Geometry = { type: 'Point', coordinates: at };
+
+      // Named where Mapbox knows the place, and still usable where it does not.
+      return [
+        {
+          id: formatCoordinates(at),
+          title: address ? (formatAddress(address) || (areaLabel(address) ?? formatCoordinates(at))) : formatCoordinates(at),
+          subtitle: address ? formatCoordinates(at) : 'No address here',
+          exact: true,
+          geometry,
+        },
+      ];
+    },
+  };
+}

package/packages/ui/src/map/sources/mapboxPlaces.ts

@@ -0,0 +1,71 @@
+// Mapbox places and addresses as one <FMapSearch> source.
+//
+// It uses @mapbox/search-js-core — the headless half of Mapbox Search JS, no DOM and nothing to theme
+// around — rather than the packaged <mapbox-search-box> element. FMapSearch.vue's header says why the
+// element is not an option.
+//
+// ★ SEPARATE ENTRY POINT (`@humanforest/ui/map-search-places`). An app whose sources are all internal
+// should not ship Mapbox's search client.
+import { SearchBoxCore, SessionToken } from '@mapbox/search-js-core';
+import type { MapSearchResult, MapSearchSource } from '../mapSearch';
+
+/** The two calls this source makes, so a test can stand in for the client. */
+type PlacesClient = Pick<SearchBoxCore, 'suggest' | 'retrieve'>;
+
+export interface MapboxPlacesOptions {
+  accessToken: string;
+  /** ISO country codes to restrict to, e.g. `'gb'` */
+  country?: string;
+  language?: string;
+  /** bias results towards a point — usually the map's current centre */
+  proximity?: [number, number];
+  limit?: number;
+  /** stands in for the real client in tests */
+  client?: PlacesClient;
+}
+
+export function mapboxPlaces(options: MapboxPlacesOptions): MapSearchSource {
+  const client: PlacesClient =
+    options.client ??
+    new SearchBoxCore({
+      accessToken: options.accessToken,
+      country: options.country,
+      language: options.language,
+    });
+
+  // ★ One session token spans the suggests leading to a single retrieve, which is how the Search Box
+  // API bills a search: as one session rather than one call per keystroke. It rolls after each
+  // retrieve, because that is what ends the session.
+  let session = new SessionToken();
+
+  return {
+    id: 'places',
+    label: 'Places',
+    icon: 'i-lucide-map-pin',
+    limit: options.limit ?? 5,
+    // No mayMatchExactly: Mapbox ranks by relevance and never claims a query answers itself.
+    async search(query: string, signal: AbortSignal): Promise<MapSearchResult[]> {
+      const { suggestions } = await client.suggest(query, {
+        sessionToken: session,
+        proximity: options.proximity,
+        signal,
+      });
+
+      return suggestions.map((s) => ({
+        id: s.mapbox_id,
+        title: s.name,
+        subtitle: s.place_formatted,
+        // ★ No geometry here — suggest() returns names and addresses but no coordinates. They come
+        // from retrieve(), which is why every place result carries a resolve instead.
+        resolve: async (retrieveSignal: AbortSignal) => {
+          const { features } = await client.retrieve(s, {
+            sessionToken: session,
+            signal: retrieveSignal,
+          });
+          session = new SessionToken();
+          return features[0].geometry;
+        },
+      }));
+    },
+  };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The house style: Forest's own Mapbox style, which IMPORTS Standard rather than copying it.
+ *
+ * Every Forest map points here. Standard's own style cannot carry uploaded images, so a surface that
+ * needs the Forest marker — or any future Forest icon — has to be on this one; and because it is an
+ * import, every `slot` value and every basemap config lever behaves exactly as it does on Standard.
+ *
+ * ★ Publishing this style in Studio is a PRODUCTION CHANGE: every surface picks it up at once. Pin a
+ * version (`…/style-id?version=N`) the moment that becomes a risk worth managing.
+ *
+ * ★ It lives in a plain module rather than in FMap.vue because `<script setup>` cannot contain ES
+ * module exports — vite rejects the SFC outright, and `vue-tsc` does not catch it.
+ */
+export const FOREST_MAP_STYLE = 'mapbox://styles/humanforest/cms17j8ib004n01rzhq68cygn';