@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,192 @@
+// How a PLACE reads on a map — the fixed things an operation works from.
+//
+// ★ A place is not a vehicle, so it does not use the vehicle's disc. It has no battery, it does not go
+// offline, and an operator cannot repair it. What it has instead is a KIND, and sometimes a COUNT.
+//
+//     kind    what the place is        (WAREHOUSE | PARKING)
+//     count   how many vehicles        optional, and it is a LABEL rather than artwork
+//
+// Shape carries the class: vehicles are round, places are square, a counted place is a pill. Shape is the
+// channel a reader resolves first, and an operations map draws both classes at once — so a depot must
+// never read as a vehicle at scanning distance.
+//
+// A ZONE is neither. A business area or a no-parking area is a region, so it is a fill and a line, not
+// a mark: a marker on the centre of an area claims a point that does not exist. See `zone.ts`.
+import placeManifest from '../../icons/forest/map/place-manifest.json';
+import countManifest from '../../icons/forest/map/place-count-manifest.json';
+
+export type PlaceKind = 'WAREHOUSE' | 'PARKING';
+
+/** Which glyph each kind lights. One glyph for each kind, as with the vehicle states. */
+export const PLACE_GLYPH: Record<PlaceKind, string> = {
+  WAREHOUSE: 'warehouse',
+  PARKING: 'parking',
+};
+
+/**
+ * ★ TWO AXES, AND THE COLOUR CARRIES THE SECOND ONE (José, 2026-07-26).
+ *
+ *     KIND       what the place is        the GLYPH — the Mohr P, or a house
+ *     CONDITION  what state it is in      the COLOUR — semantic, not categorical
+ *
+ * A bay's condition is a SEVERITY, not a category, so it takes semantic colours for the same reason the battery
+ * ring does. Colour used to carry the kind, which meant the colour and the glyph said the same thing twice and
+ * left nowhere to put "suspended".
+ *
+ * ★ It also un-double-books the palette. Vehicle discs are categorical and take the vivid set; place squares are
+ * severity and take the semantic roles. The two never overlap by construction — where before, sky was both a bay
+ * and a `parked` vehicle, and the inverted colour was both a warehouse and a `retired` one.
+ *
+ * Measured between the three: info↔warning 124 light / 130 dark, info↔error 96/95, warning↔error 48/60. A white
+ * glyph on `info` reads at 3.6:1 light and 6.7:1 dark.
+ *
+ * ⚠ Each does land near a VEHICLE disc — info↔parked 18/22, warning↔hold 9/15, error↔damage 35/7. Shape
+ * separates the classes, and the near-misses are semantically adjacent: an amber square and an amber disc both
+ * mean "wants attention". A confusion that costs nothing is not the same as one that inverts a meaning.
+ */
+export type PlaceState = 'OK' | 'SUSPENDED' | 'REMOVED';
+
+export const PLACE_STATE_COLOUR: Record<PlaceState, string> = {
+  OK: '--forest-map-place-ok',
+  SUSPENDED: '--forest-map-place-suspended',
+  REMOVED: '--forest-map-place-removed',
+};
+
+/**
+ * ★ ONLY A BAY HAS A CONDITION (José). A warehouse cannot be suspended or removed — it is a building the
+ * operation works from, not a kerbside arrangement that a council can withdraw. So the condition belongs to the
+ * BAY rather than to places in general, and this union makes a suspended warehouse UNREPRESENTABLE rather than
+ * merely discouraged. A rule that lives in a comment is a rule somebody constructs their way around.
+ *
+ * A warehouse still takes a colour, and it takes the OK one: the colour channel means "condition", and a
+ * warehouse's condition is constant. Pinning it is what keeps the channel meaning ONE thing — giving warehouses
+ * a kind-colour of their own would make the same channel mean "condition" on one glyph and "kind" on another.
+ */
+export type Place = { kind: 'WAREHOUSE' } | { kind: 'PARKING'; state: PlaceState };
+
+/** the condition a bay paints. A warehouse has none — see `placeColour`. */
+export const placeState = (place: Place): PlaceState => (place.kind === 'PARKING' ? place.state : 'OK');
+
+/**
+ * The token a place paints.
+ *
+ * ★ A WAREHOUSE IS OFF THE SCALE, not at the good end of it. It takes `--forest-map-warehouse`, the inverted
+ * colour — which is not a semantic role, so it does not claim a condition a warehouse cannot have. That is the
+ * same move as `retired` on the vehicle disc: the value that is not a hue is how the set says "this one is not
+ * on the scale the others are on". A bay's colour IS its condition; a warehouse's colour says it has none.
+ */
+export const WAREHOUSE_COLOUR = '--forest-map-warehouse';
+export const placeColour = (place: Place): string =>
+  place.kind === 'WAREHOUSE' ? WAREHOUSE_COLOUR : PLACE_STATE_COLOUR[place.state];
+
+/** A colour with zero alpha switches a region off. Params are colours and nothing else. */
+export const PARAM_OFF = 'rgba(0,0,0,0)';
+
+export const PLACE_ICON_ID = placeManifest.id;
+export const PLACE_COUNT_ICON_ID = countManifest.id;
+export const PLACE_GLYPH_PARAMS: readonly string[] = placeManifest.params
+  .filter((p) => p.kind === 'glyph')
+  .map((p) => p.name);
+
+/**
+ * The glyph a COUNTED place lights, whatever kind of place it is.
+ *
+ * The square's glyph says what the place is; the pill's says what is being counted, because a number
+ * on its own leaves its unit to be inferred. This is the one param the pill drives differently from
+ * the square, so it is named here rather than left as a string inside the expression.
+ */
+export const COUNT_GLYPH = 'bike';
+
+export interface PlaceColours {
+  /** the square or the pill */
+  body: unknown;
+  /** the lit glyph */
+  glyph: unknown;
+  /** the border, which is also the halo */
+  ring: unknown;
+}
+
+/**
+ * The params for ONE place. Every region is set, because an omitted param keeps its magenta sentinel.
+ */
+export function placeParams(kind: PlaceKind, colours: PlaceColours): Record<string, unknown> {
+  const lit = PLACE_GLYPH[kind];
+  const params: Record<string, unknown> = { body: colours.body, ring: colours.ring };
+  for (const name of PLACE_GLYPH_PARAMS) params[name] = name === lit ? colours.glyph : PARAM_OFF;
+  return params;
+}
+
+/**
+ * The `icon-image` for a layer that draws every place from ONE symbol layer. Each param becomes a `match`
+ * on the feature, exactly as the vehicle marker does.
+ */
+export function placeImageExpression(opts: {
+  /** the CONDITION → colour map. `{ OK: token('--forest-map-place-ok'), … }` */
+  state: Record<PlaceState, unknown>;
+  /** the warehouse's own colour — it is off the condition scale. `token('--forest-map-warehouse')` */
+  warehouse: unknown;
+  glyph: unknown;
+  ring: unknown;
+  /** the feature properties to read. Defaults: `kind` for the glyph, `state` for the colour */
+  props?: { kind?: string; state?: string };
+  /** draw the stretchable pill instead of the square. Pair it with `icon-text-fit: 'width'` */
+  counted?: boolean;
+}): unknown[] {
+  const kindProp = ['get', opts.props?.kind ?? 'kind'];
+  const stateProp = ['get', opts.props?.state ?? 'state'];
+  const kinds = Object.keys(PLACE_GLYPH) as PlaceKind[];
+  const states = Object.keys(PLACE_STATE_COLOUR) as PlaceState[];
+  const params: Record<string, unknown> = {
+    // ★ the body matches on the CONDITION; the glyph matches on the KIND. Two properties, two questions.
+    // ⚠ A WAREHOUSE TAKES ITS OWN COLOUR regardless of what the feature says about state. Only a bay has a
+    // condition, so a feed that puts `state: 'REMOVED'` on a warehouse is wrong rather than interesting — the
+    // expression renders what the model allows, not what the feed sent.
+    body: [
+      'case',
+      ['==', kindProp, 'WAREHOUSE'],
+      opts.warehouse,
+      ['match', stateProp, ...states.flatMap((st) => [st, opts.state[st]]), opts.state.OK],
+    ],
+    ring: opts.ring,
+  };
+  // ★★ THE COUNTED PILL LIGHTS THE BIKE, NOT THE KIND (José). The square answers "what is this place",
+  // so its glyph is the kind. The pill answers "how many vehicles are here", and the glyph names the
+  // thing being counted — a bare number beside a P leaves the unit to be inferred, and the unit is the
+  // half of the message the number cannot carry.
+  //
+  // ⚠ It follows that a counted WAREHOUSE and a counted BAY draw the same glyph. That is accepted: the
+  // count is the subject, and the kind is still on the map next to it as an uncounted square.
+  if (opts.counted) {
+    for (const name of PLACE_GLYPH_PARAMS) params[name] = name === COUNT_GLYPH ? opts.glyph : PARAM_OFF;
+  } else {
+    for (const name of PLACE_GLYPH_PARAMS) {
+      const users = kinds.filter((k) => PLACE_GLYPH[k] === name);
+      params[name] = users.length
+        ? ['match', kindProp, ...users.flatMap((k) => [k, opts.glyph]), PARAM_OFF]
+        : PARAM_OFF;
+    }
+  }
+  return ['image', opts.counted ? PLACE_COUNT_ICON_ID : PLACE_ICON_ID, { params }];
+}
+
+/**
+ * The layout a counted place needs. Without `icon-text-fit` the pill never stretches: the stretch
+ * metadata in the asset only takes effect when a layer asks the icon to fit its text.
+ *
+ * `text-field` is the caller's, because only the caller knows which property holds the count.
+ */
+export const PLACE_COUNT_LAYOUT = {
+  'icon-text-fit': 'width',
+  'icon-text-fit-padding': [0, 0, 0, 0],
+  'icon-allow-overlap': true,
+  'text-allow-overlap': true,
+  'text-size': 12,
+  'text-font': ['DIN Offc Pro Medium', 'Arial Unicode MS Bold'],
+} as const;
+
+/** Where the label goes, and how wide the pill starts. Read from the generator's manifest. */
+export const PLACE_COUNT_CONTENT = countManifest.content;
+export const PLACE_COUNT_STRETCH = countManifest.stretchX;
+
+// Zones live in `zone.ts`. They grew an audience axis and five kinds, which is more than a place file
+// should carry — and a zone was never a place to begin with.

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

@@ -0,0 +1,95 @@
+// The engine's sequential ramps, sampled for a map layer — one place, for both mechanisms.
+//
+// ★ THE MAP DOES NOT ALIAS THE RAMPS, AND IT USED TO. There was a `--forest-map-density-*` block in
+// forest.css restating five positions of the brand ramp, for one reason: the engine declares sequential
+// ramps once, tuned for a light page, so something has to reverse them after dark. Putting that in
+// tokens looked right — a GL layer cannot forget a token — until the field needed a RAMP PROP, which
+// tokens cannot express without aliasing every family in both modes.
+//
+// So the reversal moved here, and the aliases stopped earning their place. What settled it was a bug:
+// the alias block named five positions, a bin map asked for seven buckets, and `--forest-map-density-5`
+// did not exist. An undefined var in a GL paint property does not fail — it falls back to the inherited
+// colour — so the densest cells in London painted GREY while the legend went on showing green. Sampling
+// the engine's own stops cannot land on a colour that does not exist.
+//
+// ★ THE INVERSION IS UNFORGETTABLE BECAUSE IT IS THE ONLY WAY IN. Both `densityLayers` and `heatLayers`
+// build their colours through `rampStops`, so neither a bin map nor a field can ship a ramp that means
+// the opposite thing after dark. That was the property the tokens were bought for, kept without them.
+
+/** The engine's sequential families, by the name it gives them. */
+export const SEQUENTIAL_RAMPS = ['forest', 'indigo', 'moss', 'cividis', 'viridis', 'magma'] as const;
+export type SequentialRamp = (typeof SEQUENTIAL_RAMPS)[number];
+
+/** How many stops the engine declares per family — the two scientific maps carry one more. */
+export const RAMP_LENGTH: Record<SequentialRamp, number> = {
+  forest: 9,
+  indigo: 9,
+  moss: 9,
+  cividis: 10,
+  viridis: 10,
+  magma: 9,
+};
+
+/** The engine's diverging families. `redBlue` is the convention the fleet console already paints. */
+export const DIVERGING_RAMPS = ['blueOrange', 'redBlue', 'purpleGreen', 'forestWarm'] as const;
+export type DivergingRamp = (typeof DIVERGING_RAMPS)[number];
+
+const kebab = (s: string) => s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+/**
+ * ★ THE CENTRE IS A TOKEN, AND IT IS THE ONE COLOUR NOT ON ANY RAMP.
+ *
+ * Stop 4 means "no meaningful gap", so it has to vanish against the basemap in both modes. Every
+ * family's own centre is a pale neutral, which is right on a light ground and wrong on a dark one —
+ * it would make "nothing to report" the loudest thing on the map after dark. `--ui-bg-muted` is near
+ * white in light and a dark neutral in dark, so it disappears in both, which is the whole job.
+ *
+ * ⚠ NOT `--ui-bg`: measured on the running app, that resolves to the same near-white in BOTH modes.
+ */
+export const BALANCE_CENTRE_TOKEN = '--forest-map-balance-centre';
+
+/**
+ * A diverging family's stops, low → centre → high.
+ *
+ * ★ THE ARMS REVERSE WITHIN THEMSELVES IN DARK MODE; THE HUES NEVER SWAP SIDES. Reversing the whole
+ * ramp the way a sequential one reverses would exchange the two arms — deficit would paint as surplus,
+ * which is the single error this layer must never make. Each arm is reversed in place instead, so the
+ * strongest reading stays furthest from the ground in both modes and the direction stays put.
+ */
+export function divergingStops(ramp: DivergingRamp, invert = prefersInvertedRamp()): string[] {
+  const name = kebab(ramp);
+  const arm = (from: number, to: number) => {
+    const idx = Array.from({ length: 4 }, (_, i) => from + i * Math.sign(to - from));
+    return (invert ? [...idx].reverse() : idx).map((i) => `--dataviz-diverging-${name}-${i}`);
+  };
+  return [...arm(0, 3), BALANCE_CENTRE_TOKEN, ...arm(5, 8)];
+}
+
+/**
+ * ★ READING THE DOM HERE IS CORRECT, not a leak. `useMapOverlay` re-invokes the whole spec on a
+ * colour-mode change (`onTokenModeChange(run)` → `run()` → `spec()`), so a builder that reads the mode
+ * at call time is re-run with the new one. In node there is no document and no dark mode; the light
+ * order is the right answer for a test.
+ */
+export const prefersInvertedRamp = (): boolean => {
+  if (typeof document === 'undefined') return false;
+  const root = document.documentElement;
+  return root.classList.contains('dark') || root.dataset.theme === 'dark';
+};
+
+/**
+ * `n` token names sampled evenly across a family, low → high, reversed when the page is dark so that
+ * further from the ground always means more.
+ *
+ * Omit `n` for every stop the family declares — which is what a continuous gradient wants, and what a
+ * bucketed layer must not have.
+ */
+export function rampStops(ramp: SequentialRamp, n?: number, invert = prefersInvertedRamp()): string[] {
+  const len = RAMP_LENGTH[ramp];
+  const count = Math.max(2, Math.min(Math.round(n ?? len), len));
+  const names = Array.from(
+    { length: count },
+    (_, i) => `--dataviz-sequential-${ramp}-${Math.round((i * (len - 1)) / (count - 1))}`,
+  );
+  return invert ? names.reverse() : names;
+}

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

@@ -0,0 +1,163 @@
+// The arithmetic behind region selection — lasso and box — kept out of the composable so it can be
+// tested in node, where packages/ui's suite runs.
+//
+// What lives here: what a gesture MEANS (replace / add / subtract), what a drawn path becomes
+// (a screen-space box to query, a polygon to trim against), and the set algebra that produces the new
+// selection. What does not: pointers, GL, and turf's point-in-polygon — those need a browser and a map.
+import { polygon } from '@turf/helpers';
+
+/** What a region gesture does to the selection that already exists. */
+export type RegionMode = 'replace' | 'add' | 'subtract';
+
+/**
+ * Which tool the canvas is holding. `off` is a state, not the absence of one — a drag pans, and only
+ * the modifier still draws.
+ *
+ * ★ It exists because a modifier is not reachable on a phone. Gating region selection behind ⌘ makes
+ * it a desktop-only feature, so an armed tool is what makes a plain drag select — and once a plain
+ * drag can select, `off` has to be something a reader can see and choose rather than an implied
+ * default.
+ */
+export type RegionTool = 'off' | 'lasso' | 'box' | 'circle';
+
+/** The shape a gesture draws. The modifier path, which has no tool, draws the more general one. */
+export type RegionShape = 'lasso' | 'box' | 'circle';
+
+export function shapeForTool(tool: RegionTool): RegionShape {
+  return tool === 'off' ? 'lasso' : tool;
+}
+
+/**
+ * A circle from its drag: the press is the CENTRE and the pointer is on the rim.
+ *
+ * ★ Centre-out rather than corner-to-corner, because a circle has no corners to drag between. Bounding
+ * a circle by its box would put the centre halfway along the drag, so the shape would slide away from
+ * the point the reader pressed — which for "everything within N of this bay" is exactly the point they
+ * were aiming at.
+ */
+export function circleFromPath(path: readonly ScreenPoint[]): { centre: ScreenPoint; radius: number } | null {
+  const centre = path[0];
+  const rim = path[path.length - 1];
+  if (!centre || !rim) return null;
+  const radius = Math.hypot(rim[0] - centre[0], rim[1] - centre[1]);
+  return radius > 0 ? { centre, radius } : null;
+}
+
+/** Screen-space hit test for the circle tool — a distance compare, no polygon needed. */
+export function inCircle(p: ScreenPoint, centre: ScreenPoint, radius: number): boolean {
+  return Math.hypot(p[0] - centre[0], p[1] - centre[1]) <= radius;
+}
+
+/** Whether a plain drag — no modifier — starts a region rather than panning the map. */
+export function armsOnPlainDrag(tool: RegionTool): boolean {
+  return tool !== 'off';
+}
+
+/** A point in SCREEN space (px from the map canvas's top-left), which is what queries take. */
+export type ScreenPoint = [number, number];
+
+/** [[minX, minY], [maxX, maxY]] — the shape `queryRenderedFeatures` wants. */
+export type ScreenBox = [ScreenPoint, ScreenPoint];
+
+/**
+ * Smaller than this on both axes and the gesture is a click, not a region.
+ *
+ * ★ Without a floor, every click on the map runs a box query and replaces the selection — which makes
+ * single-select unusable, because <useFeatureSelect>'s click handler and this would both fire on the
+ * same press and the last one would win. 4px is under the smallest deliberate drag and above the
+ * jitter of a click on a trackpad.
+ */
+export const MIN_REGION_PX = 4;
+
+/**
+ * The modifiers a gesture STARTED with decide what it means.
+ *
+ * ★ Read once at pointerdown, never at pointerup. Someone who presses shift, drags a lasso and lets
+ * go of shift before releasing the button still meant "add to the selection" — reading the end state
+ * would silently turn their addition into a replacement and throw the rest away.
+ */
+export function regionMode(e: { shiftKey: boolean; altKey: boolean }): RegionMode {
+  // Subtract wins when both are held: of the two it is the destructive reading, and a reader holding
+  // an accidental extra modifier is better served by removing too little than replacing everything.
+  if (e.altKey) return 'subtract';
+  if (e.shiftKey) return 'add';
+  return 'replace';
+}
+
+/**
+ * The selection a region produces, given what was already selected.
+ *
+ * ★ Returns a new Set. The caller's set is live state painted onto GL features, and mutating it here
+ * would repaint through a reference nobody expected to change.
+ */
+export function applyMode(
+  current: ReadonlySet<string | number>,
+  caught: readonly (string | number)[],
+  mode: RegionMode,
+): Set<string | number> {
+  if (mode === 'replace') return new Set(caught);
+
+  const next = new Set(current);
+  // An empty region is a no-op for both, rather than a clear: lassoing empty water while adding must
+  // not throw the selection away, and neither must a subtract that caught nothing.
+  if (mode === 'add') for (const id of caught) next.add(id);
+  else for (const id of caught) next.delete(id);
+  return next;
+}
+
+/**
+ * The screen-space box enclosing a path — the cheap first pass before any polygon test.
+ *
+ * ★ For a circle the path is only centre and rim, so its own bounds would be a box from the centre
+ * outward — a QUARTER of the circle. `circleBounds` squares it around the centre instead.
+ */
+export function pathBounds(path: readonly ScreenPoint[]): ScreenBox {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const [x, y] of path) {
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  return [
+    [minX, minY],
+    [maxX, maxY],
+  ];
+}
+
+/** The query box for a circle: squared around the centre, not the drag's own bounds. */
+export function circleBounds(centre: ScreenPoint, radius: number): ScreenBox {
+  return [
+    [centre[0] - radius, centre[1] - radius],
+    [centre[0] + radius, centre[1] + radius],
+  ];
+}
+
+/** Whether a gesture is big enough to have been meant. */
+export function worthQuerying(box: ScreenBox): boolean {
+  const [[minX, minY], [maxX, maxY]] = box;
+  return maxX - minX > MIN_REGION_PX || maxY - minY > MIN_REGION_PX;
+}
+
+/**
+ * A drawn path as a closed polygon, for trimming the box query down to the shape actually drawn.
+ *
+ * Null when the path cannot be a ring. Two points is a line, and asking whether a marker is inside a
+ * line is not a question with an answer — turf would either throw or quietly say no, and a lasso that
+ * silently selects nothing is worse than one that declines to run.
+ *
+ * ★ The ring is in SCREEN space, not lng/lat, and the markers are tested in screen space too. That is
+ * deliberate: a lasso is drawn on the picture, so it should catch what it visually encloses. Doing it
+ * in geographic space would disagree with the drawn shape wherever the map is rotated or pitched.
+ */
+export function pathPolygon(path: readonly ScreenPoint[]): GeoJSON.Feature<GeoJSON.Polygon> | null {
+  if (path.length < 3) return null;
+  const ring: ScreenPoint[] = [...path];
+  const first = ring[0];
+  const last = ring[ring.length - 1];
+  if (first[0] !== last[0] || first[1] !== last[1]) ring.push([first[0], first[1]]);
+  return polygon([ring]);
+}

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

@@ -0,0 +1,167 @@
+// A path, painted. Layer specs as data for useMapOverlay, exactly as zoneLayers() is.
+//
+// There is no FRoute.vue for the same reason there is no FZone.vue: a route is GL-world, and mapbox's
+// style spec is already declarative. Wrapping it in a component per layer would add a lossy second
+// dialect over one that works.
+import { MAP_SLOT, token, type OverlayLayer, type OverlaySource } from './useMapOverlay';
+
+/**
+ * Width ramps, in CSS pixels.
+ *
+ * ★ Each is the WHOLE value of its paint property. A zoom `interpolate` nested inside arithmetic is
+ * rejected by mapbox without an error: `getLayer()` returns undefined and the route simply is not
+ * there.
+ */
+export const ROUTE_WIDTH = ['interpolate', ['linear'], ['zoom'], 10, 2, 14, 4, 18, 7] as const;
+export const ROUTE_CASING_WIDTH = ['interpolate', ['linear'], ['zoom'], 10, 4, 14, 7, 18, 11] as const;
+export const TRAIL_WIDTH = ['interpolate', ['linear'], ['zoom'], 10, 1.5, 14, 3, 18, 5] as const;
+
+/** GL has no `transparent` keyword for a token to resolve to, so the fade's far end is stated outright. */
+const CLEAR = 'rgba(0, 0, 0, 0)';
+
+const ROUND = { 'line-cap': 'round', 'line-join': 'round' } as const;
+
+/**
+ * The source a route is drawn from.
+ *
+ * ★ `lineMetrics: true` is not optional. `line-gradient` — which paints both the played/remaining
+ * split and the trail's fade — is only valid on a source that carries it, and a layer asking for one
+ * without it is rejected in silence.
+ */
+export function routeSource(line: GeoJSON.Feature | GeoJSON.FeatureCollection): OverlaySource {
+  return { type: 'geojson', data: line, lineMetrics: true };
+}
+
+export interface RouteLayerOptions {
+  /** the source id holding the route feature */
+  source: string;
+  /** id prefix, so two routes can share a map. Default `route` */
+  prefix?: string;
+  /** the line. Default `--ui-primary` — pass a dimmed token when `travelledLayers` paints over it */
+  colour?: string;
+  /** the outline that lifts the line off the basemap. Default `--ui-bg` */
+  casingColour?: string;
+  visible?: boolean;
+}
+
+/**
+ * A casing and a line, in that order.
+ *
+ * ★ THE ARRAY IS THE PAINT ORDER. `useMapOverlay` inserts by array position rather than by mount
+ * sequence for exactly this case: an 8px casing that lands above its 4px line swallows the line.
+ *
+ * Both sit in `MAP_SLOT.route` — the road surface. A route belongs with the roads and under the marks:
+ * it cannot be selected, and nothing about it is the live state of a vehicle.
+ *
+ * The casing takes the page background because the line has to read as lifted off the basemap in both
+ * colour modes, and the background is the one value that flips with the mode by definition. Emissive
+ * strength arrives from `useMapOverlay`, which matters here — an unlit line paints at about a fifth of
+ * its luminance under the night preset.
+ */
+export function routeLayers(opts: RouteLayerOptions): OverlayLayer[] {
+  const {
+    source,
+    prefix = 'route',
+    colour = '--ui-primary',
+    casingColour = '--ui-bg',
+    visible = true,
+  } = opts;
+
+  return [
+    {
+      id: `${prefix}-casing`,
+      type: 'line',
+      source,
+      slot: MAP_SLOT.route,
+      visible,
+      layout: { ...ROUND },
+      paint: { 'line-color': token(casingColour), 'line-width': ROUTE_CASING_WIDTH },
+    },
+    {
+      id: `${prefix}-line`,
+      type: 'line',
+      source,
+      slot: MAP_SLOT.route,
+      visible,
+      layout: { ...ROUND },
+      paint: {
+        'line-color': token(colour),
+        'line-width': ROUTE_WIDTH,
+      },
+    },
+  ];
+}
+
+export interface TravelledLayerOptions {
+  /** the source id holding the travelled slice — `trackSlice(track, span.start, at)` through `trackLine` */
+  source: string;
+  prefix?: string;
+  /** the travelled line. Default `--ui-primary` */
+  colour?: string;
+  visible?: boolean;
+}
+
+/**
+ * What has been played, as its own geometry drawn over the route.
+ *
+ * ★ THIS IS NOT A GRADIENT, AND THAT IS THE WHOLE POINT. The obvious implementation is one
+ * `line-gradient` on the route with a `step` at the playhead — and it is WRONG, because
+ * `['line-progress']` indexes DISTANCE along the line while a Forest playhead is a fraction of TIME.
+ * The two only agree at constant speed. Feed a time fraction into a distance parameter and every halt
+ * and every signal gap pushes the fill behind the mark by exactly the time they consumed: on the
+ * reference trip the fill trailed the vehicle by most of a kilometre.
+ *
+ * Slicing the track instead makes the painted line the travelled path BY CONSTRUCTION. It costs one
+ * `setData` per frame on a short feature, which is the same cost the trail already pays, and it drops
+ * the `lineMetrics` requirement for this layer entirely.
+ *
+ * No casing: it is drawn over a route that already has one.
+ */
+export function travelledLayers(opts: TravelledLayerOptions): OverlayLayer[] {
+  const { source, prefix = 'travelled', colour = '--ui-primary', visible = true } = opts;
+  return [
+    {
+      id: `${prefix}-line`,
+      type: 'line',
+      source,
+      slot: MAP_SLOT.route,
+      visible,
+      layout: { ...ROUND },
+      paint: { 'line-color': token(colour), 'line-width': ROUTE_WIDTH },
+    },
+  ];
+}
+
+export interface TrailLayerOptions {
+  source: string;
+  prefix?: string;
+  /** the solid end, at the mark. Default `--ui-primary` */
+  colour?: string;
+  visible?: boolean;
+}
+
+/**
+ * The fading tail behind a moving mark.
+ *
+ * One layer, no casing: a trail is a hint about where something just was, and giving it a route's
+ * weight would make the two compete. It fades to nothing at its oldest end, which is what says
+ * "recent" without a legend — and `trackTail` hands over fixes oldest-first, so `line-progress` 0 is
+ * the old end.
+ */
+export function trailLayers(opts: TrailLayerOptions): OverlayLayer[] {
+  const { source, prefix = 'trail', colour = '--ui-primary', visible = true } = opts;
+  return [
+    {
+      id: `${prefix}-line`,
+      type: 'line',
+      source,
+      slot: MAP_SLOT.route,
+      visible,
+      layout: { ...ROUND },
+      paint: {
+        'line-width': TRAIL_WIDTH,
+        'line-gradient': ['interpolate', ['linear'], ['line-progress'], 0, CLEAR, 1, token(colour)],
+      },
+    },
+  ];
+}