@humanforest/nuxt-layer 0.1.0

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

@@ -0,0 +1,807 @@
+// How a vehicle reads on a map.
+//
+// ★ THREE INDEPENDENT AXES, not one status enum. This is the thing every surface gets wrong first:
+//
+//     state        what the operation thinks of the bike   (FUNCTIONAL, LOST, SERVICE_WORKSHOP, …)
+//     connectivity whether it is talking to us right now   (offline: boolean)
+//     battery      how much charge is left                 (HIGH | MEDIUM | LOW | CRITICAL)
+//
+// They vary independently, and AVAILABILITY IS DERIVED FROM ALL THREE — never stored, never a state.
+// Verified against a 31,602-vehicle production snapshot (2026-07-24): `isAvailable()` below reproduces
+// the platform's own `available` flag on 31,602 of 31,602 vehicles. So a bike can be perfectly
+// FUNCTIONAL and still not rentable because it is offline or flat, which is exactly the case a single
+// status enum cannot express — and exactly why the marker encodes the three separately.
+//
+// The encoding that falls out of that:
+//
+//     disc colour   state GROUP   — VIVID, because the disc is categorical: which kind of thing is this
+//     glyph         lost or not    — colour finds them, the glyph confirms
+//     battery ring  SEMANTIC       — the OUTER CIRCLE, and a layer can switch it off entirely
+//     the mark's edge FIXED        — the inner circle's own stroke, always the background colour
+//     offline dot   the EXCEPTION  — nothing at all when the bike is talking
+//
+// Encoding only the exceptions is not minimalism for its own sake: 88.7% of the fleet has fine charge
+// and 80% is online, so signalling the normal case would ink ~25,000 marks to say "nothing happening"
+// and blow the overplotting budget the mass tier runs to.
+
+import markerManifest from '../../icons/forest/map/manifest.json';
+// The LOD pair turns an asset threshold into a zoom. `scale.ts` imports nothing, so there is no cycle.
+import { MARKER_MIN_ICON_SIZE, zoomAtIconSize } from './scale';
+
+/** Wunder v2 vocabulary. The set the platform actually emits, plus the two it emits but has not adopted. */
+export type VehicleState =
+  | 'FUNCTIONAL'
+  | 'INSPECT'
+  | 'RELOCATE'
+  | 'SERVICE_MECHANICS'
+  | 'MAINTENANCE'
+  | 'SERVICE_WORKSHOP'
+  | 'COLLECT'
+  | 'SERVICE_ON_SITE'
+  | 'LOST'
+  | 'OPERATIONAL_HOLD'
+  | 'AWAITING_ACTION'
+  | 'READY_FOR_DEPLOYMENT'
+  | 'RETIRED'
+  | 'IMPOUNDED'
+  | 'OTHER';
+
+/**
+ * RENTAL — the fourth axis, and it is NOT a state.
+ *
+ * ★ THE PLATFORM'S OWN VOCABULARY, not a set invented here. `rentalState` is a field on the vehicle, and
+ * these are its values verbatim — so a surface passes the API's string through untranslated. An invented
+ * enum needs a mapping table on every caller, and a mapping table is a place for the meaning to drift.
+ *
+ *     AVAILABLE     no rental. The vehicle is rentable.
+ *     RESERVATION   a rental in state RESERVATION is attached — held for someone, not yet moving
+ *     DRIVING       a rental is ACTIVE and the vehicle is in DRIVING mode
+ *     PARKING       a rental is ACTIVE and the vehicle is in PARKING mode — the rider paused the trip
+ *     DELIVERED     attached to a booking in state DELIVERED, waiting to become a rental
+ *
+ * ★ A vehicle with a rental attached is still `FUNCTIONAL`. The state axis says what the OPERATION thinks of
+ * the vehicle; rental says what a RIDER is doing with it. They vary independently, which is why this is not
+ * another `VehicleState`: adding one there would have made "somebody has it" and "it needs a repair" mutually
+ * exclusive, and both are true at once often enough to matter.
+ *
+ * What the mark draws — THREE cases, because that is what an operator can act on differently:
+ *
+ *     AVAILABLE   nothing at all               the usual case, and the exception rule says draw nothing
+ *     taken       the disc becomes a GRADIENT, and the glyph becomes the pine
+ *     PARKING     the same, plus the PAUSE MARK in the bottom-right corner
+ *
+ * ⚠ `DRIVING` and `DELIVERED` draw the same as `RESERVATION`. José scoped this to AVAILABLE, RESERVATION and
+ * PARKING, and the other two still arrive from the API — so they take the nearest correct treatment rather
+ * than falling through to "available", which would draw a rented vehicle as rentable. If a surface ever needs
+ * to tell driving from reserved, that is a new mark, not a new colour.
+ */
+export type RentalState = 'AVAILABLE' | 'RESERVATION' | 'DRIVING' | 'PARKING' | 'DELIVERED';
+
+/** the rental states in which somebody already has the vehicle — everything except AVAILABLE */
+export const RENTAL_TAKEN: readonly RentalState[] = ['RESERVATION', 'DRIVING', 'PARKING', 'DELIVERED'];
+
+/** the one rental state that adds a corner mark: the rider paused the trip and the vehicle is locked */
+export const RENTAL_PAUSED: RentalState = 'PARKING';
+
+/**
+ * ★ TWO VOCABULARIES, AND ONLY ONE OF THEM IS A WIRE FORMAT (José, 2026-07-26).
+ *
+ *     the VALUE     Wunder v2 — `FUNCTIONAL`, `SERVICE_ON_SITE`, … the platform's own enum. Code uses this
+ *                   everywhere: props, expressions, feature properties, `STATE_GROUP`.
+ *     the LABEL     ForestFleet — "Active", "Damaged", … what an operator reads on a Forest surface.
+ *
+ * A surface NEVER derives the label from the value. `labelOf('SERVICE_ON_SITE')` gives "Service on site",
+ * which is the v2 wording and is not what ForestFleet calls it. Use `stateLabel()`.
+ *
+ * ⚠ SEVERAL LABELS MEAN SOMETHING DIFFERENT FROM THEIR VALUE, which is why this is a table and not a
+ * transformation — and why it changes the glyph each state should light:
+ *
+ *     OPERATIONAL_HOLD   → "Support & community"   not "held back"
+ *     AWAITING_ACTION    → "Investigation"         not "waiting"
+ *     IMPOUNDED          → "Storage"               not "held by someone else"
+ *     RETIRED            → "Terminated"            harder than "retired"
+ */
+export const STATE_LABEL: Record<VehicleState, string> = {
+  FUNCTIONAL: 'Active',
+  INSPECT: 'Inspect',
+  RELOCATE: 'Relocate',
+  SERVICE_MECHANICS: 'Staff',
+  MAINTENANCE: 'Task in progress',
+  SERVICE_WORKSHOP: 'Warehouse',
+  COLLECT: 'Damage collect',
+  SERVICE_ON_SITE: 'Damaged',
+  LOST: 'Missing',
+  OPERATIONAL_HOLD: 'Support & community',
+  AWAITING_ACTION: 'Investigation',
+  READY_FOR_DEPLOYMENT: 'Ready for deployment',
+  RETIRED: 'Terminated',
+  IMPOUNDED: 'Storage',
+  OTHER: 'Other',
+};
+
+/** the ForestFleet label for a state. Use this on any surface a person reads. */
+export const stateLabel = (state: VehicleState): string => STATE_LABEL[state] ?? labelOf(state);
+
+/** Battery bands. Derived by the platform from state-of-charge against the category's own thresholds. */
+export type BatteryLevel = 'HIGH' | 'MEDIUM' | 'LOW' | 'CRITICAL';
+
+/**
+ * What the RING says about charge — three bands, not four.
+ *
+ * ★ HIGH and MEDIUM paint the same colour, so the ring collapses them into one `OK` band (José,
+ * 2026-07-26). The platform keeps four levels because a rental rule and a table need the difference; a
+ * ring 2.4 units wide cannot show it. Two names for one colour invited a reader to look for a distinction
+ * that was never drawn, and cost an extra atlas variant per marker for nothing.
+ */
+export type BatteryRingBand = 'OK' | 'LOW' | 'CRITICAL';
+
+/** Which ring band each platform level falls in. The only place the four collapse into three. */
+export const BATTERY_RING_BAND: Record<BatteryLevel, BatteryRingBand> = {
+  HIGH: 'OK',
+  MEDIUM: 'OK',
+  LOW: 'LOW',
+  CRITICAL: 'CRITICAL',
+};
+
+/**
+ * The category thresholds in production for `Forest Bike`, read from
+ * `category.coreProperties.socLevels`. They live per-category on the platform, so treat these as the
+ * current values rather than as constants — and prefer the platform's `batteryLevel` enum over
+ * recomputing from `stateOfCharge`, which lags it on ~2% of vehicles.
+ */
+export const SOC_THRESHOLDS = { critical: 6, low: 20, medium: 50 } as const;
+
+/**
+ * Five disc groups, because the disc is the only channel a reader can scan in parallel and five is
+ * where a categorical palette stops separating at 3px under colour-vision deficiency.
+ *
+ * `hold` deliberately takes blue rather than amber, and `damage` red: amber and red are spoken for by
+ * the battery ring, and the ring is concentric with the disc. Two rings of the same hue touching each
+ * other is one ring. The halo sits OUTSIDE the battery ring, so the mark keeps a background-coloured band
+ * against the basemap whatever the charge is.
+ */
+export type StateGroup = 'functional' | 'damage' | 'parked' | 'lost' | 'hold' | 'retired';
+
+export const STATE_GROUP: Record<VehicleState, StateGroup> = {
+  // Green — on the street and nothing is wrong. The only group a rider can rent from.
+  FUNCTIONAL: 'functional',
+  INSPECT: 'functional',
+  RELOCATE: 'functional',
+  // Red — something is wrong, or somebody is finding out what is wrong.
+  SERVICE_ON_SITE: 'damage',
+  COLLECT: 'damage',
+  AWAITING_ACTION: 'damage',
+  // Sky — off the street and accounted for. Inventory rather than a problem.
+  SERVICE_WORKSHOP: 'parked',
+  IMPOUNDED: 'parked',
+  READY_FOR_DEPLOYMENT: 'parked',
+  // Purple — nobody knows where it is.
+  LOST: 'lost',
+  // Amber — a person has it on purpose: an engineer, the community team, an internal team.
+  MAINTENANCE: 'hold',
+  OPERATIONAL_HOLD: 'hold',
+  SERVICE_MECHANICS: 'hold',
+  OTHER: 'hold',
+  // Ink — out of the fleet. Its own group because "dead" is not "parked": one is inventory, the other is gone.
+  RETIRED: 'retired',
+};
+
+/** The token each group paints its disc from. Resolved through `token()` like any other GL colour. */
+/**
+ * The token each group paints its disc from.
+ *
+ * ★ Three of them are aliases onto the CVD-safe categorical set, not semantic roles, because the disc
+ * has to stay clear of the RING — which owns amber and red, and is concentric with it. Chosen by
+ * measuring ΔE against the resolved ring colours in both modes (see forest.css): crimson separates from
+ * the critical red at ΔE 33 light / 28 dark, where the obvious choice of `--ui-error` for damage scored
+ * ΔE 0 — the same colour as the ring it sits inside.
+ *
+ * `functional` keeps the brand green: it is 74% of the fleet and the one group that should look like
+ * Forest. `parked` takes a NEUTRAL, because "inert" wants grey and a categorical set has none — but it takes
+ * its own `--forest-map-parked`, not a text role. A disc is a surface that carries a glyph; `--ui-text-dimmed`
+ * is tuned for type on a page, so borrowing it tied the disc to a decision about paragraph contrast.
+ */
+export const STATE_GROUP_COLOUR: Record<StateGroup, string> = {
+  functional: '--forest-map-functional',
+  damage: '--forest-map-damage',
+  hold: '--forest-map-hold',
+  parked: '--forest-map-parked',
+  lost: '--forest-map-lost',
+  retired: '--forest-map-retired',
+};
+
+/**
+ * Which glyph each STATE lights. One per state, not one per group.
+ *
+ * The disc carries SIX groups. Five are hues, which is where a categorical palette stops separating at
+ * marker size. The glyph has no such cap: it is only legible at the street tier, where a reader is
+ * looking at one marker rather than scanning a city — so ten glyphs are as easy to tell apart as two.
+ * They used to cost ten uploads; now they are ten regions in one file.
+ *
+ * ★ The Forest bike is reserved for FUNCTIONAL. It is the brand mark and should mean "a working bike
+ * you can take", not "a bike-shaped thing in a workshop".
+ */
+export const STATE_GLYPH: Record<VehicleState, string> = {
+  FUNCTIONAL: 'bike',
+  INSPECT: 'eye',
+  RELOCATE: 'relocate',
+  MAINTENANCE: 'wrench',
+  SERVICE_WORKSHOP: 'warehouse',
+  COLLECT: 'truck',
+  SERVICE_ON_SITE: 'bandage',
+  LOST: 'question',
+  OPERATIONAL_HOLD: 'hand',
+  AWAITING_ACTION: 'flag',
+  READY_FOR_DEPLOYMENT: 'ready',
+  RETIRED: 'skull',
+  IMPOUNDED: 'container',
+  SERVICE_MECHANICS: 'staff',
+  OTHER: 'bike', // the fallback rather than its own artwork
+};
+
+/** A colour with zero alpha is how a region is switched off. Params are colours and nothing else. */
+export const PARAM_OFF = 'rgba(0,0,0,0)';
+
+/** The icon id and the param names, read from the generator's manifest so they cannot drift. */
+export const MARKER_ICON_ID = markerManifest.id;
+export const MARKER_GLYPH_PARAMS: readonly string[] = markerManifest.params
+  .filter((p) => p.kind === 'glyph')
+  .map((p) => p.name);
+
+/**
+ * The badge — a fourth region, for a fact the three axes do not carry.
+ *
+ * ★ SHAPE AND COLOUR, never a glyph. Measured on the real asset: at the 25px crossover the badge is
+ * 6.8px across with 4.8px of fill inside a 1.00px outline, and a glyph in that reads as a lighter patch
+ * rather than a mark.
+ * A square still reads square at that size and a triangle still reads triangle, so the two shapes are the
+ * channel that survives, and colour is the second.
+ *
+ * FOUR shapes, so a surface can carry four classes of fact and tell them apart. They all inscribe in the same
+ * circle, so the corner keeps its clearance whichever one paints, and only one is ever lit. Nothing paints one
+ * yet: `claimed` (somebody is already going to this vehicle) is the first intended use, and an open task on the
+ * vehicle is the second. See `BADGE_LEGIBILITY` — the star is not a scan-tier shape.
+ *
+ * ★ The badge takes VIVID colours, like the disc — it is categorical, not a severity. The two defaults are
+ * measured as the vivid hues furthest from everything already on the mark: sky is ΔE 46 light / 49 dark from
+ * the nearest disc and 92/98 from the ring; pink is 37/38 and 37/42.
+ *
+ * ⚠ Do NOT paint a badge amber or red. Those belong to the RING (charge) and the DOT (connectivity), which
+ * are semantic — a third warm mark on a 25px marker cannot be told from either.
+ */
+export type BadgeShape = 'square' | 'triangle' | 'circle' | 'star';
+
+export const BADGE_SHAPES: readonly BadgeShape[] = markerManifest.badge.shapes as readonly BadgeShape[];
+
+/** the two params each shape owns: its fill, and the outline that separates it from the disc */
+export const BADGE_PARAMS: Record<BadgeShape, { fill: string; edge: string }> = {
+  square: { fill: 'badgeSquare', edge: 'badgeSquareEdge' },
+  triangle: { fill: 'badgeTriangle', edge: 'badgeTriangleEdge' },
+  circle: { fill: 'badgeCircle', edge: 'badgeCircleEdge' },
+  star: { fill: 'badgeStar', edge: 'badgeStarEdge' },
+};
+
+/**
+ * How well each shape survives the smallest tier, so a surface can pick one on more than taste.
+ *
+ * ★ At the crossover a badge is about 8px. A SQUARE and a CIRCLE are solid at that size and tell each other
+ * apart by their corners. A TRIANGLE still reads triangular. A STAR does not: each point is under a pixel wide
+ * and antialiasing rounds it off, so it becomes a blob — legible when a reader is looking at one vehicle, not
+ * when they are scanning. Use the star for a fact that only matters up close.
+ */
+export const BADGE_LEGIBILITY: Record<BadgeShape, 'scan' | 'street'> = {
+  square: 'scan',
+  circle: 'scan',
+  triangle: 'scan',
+  star: 'street',
+};
+
+/**
+ * The badge colours: the VIVID SET, plus the inverted colour. Nothing else.
+ *
+ * ★ Named as the palette names them (José). An earlier version invented `lime`, `deep` and `paper` for
+ * `--acid-300`, `--forest-950` and `--neutral-0` — three colours from outside the categorical set, under three
+ * words that exist nowhere else in the system. It measured well and read as a different palette, which is worse
+ * than measuring badly: a reader cannot tell whether `deep` is a Forest colour or something a badge invented.
+ * The badge draws from the same set as the disc, and `inverted` is the one non-hue, exactly as it is for the
+ * `retired` disc.
+ *
+ * ⚠ MOST OF THESE COLLIDE, and the list does not hide it — see `BADGE_SAFE`. A badge sits on a disc, beside a
+ * ring and a dot, and the mark already spends five hues plus amber and red on those. Measured worst-case ΔE
+ * against everything on the mark: sky 44, inverted 41, pink 37, then a cliff — blue 24, orange 23, rose 23,
+ * purple 21, emerald 10, amber 9, and green / indigo / fuchsia / red at 0 because they ARE disc or ring colours.
+ */
+export const BADGE_COLOURS = {
+  green: '--dataviz-categorical-vivid-green',
+  emerald: '--dataviz-categorical-vivid-emerald',
+  amber: '--dataviz-categorical-vivid-amber',
+  orange: '--dataviz-categorical-vivid-orange',
+  red: '--dataviz-categorical-vivid-red',
+  rose: '--dataviz-categorical-vivid-rose',
+  pink: '--dataviz-categorical-vivid-pink',
+  fuchsia: '--dataviz-categorical-vivid-fuchsia',
+  purple: '--dataviz-categorical-vivid-purple',
+  indigo: '--dataviz-categorical-vivid-indigo',
+  blue: '--dataviz-categorical-vivid-blue',
+  sky: '--dataviz-categorical-vivid-sky',
+  inverted: '--ui-bg-inverted',
+} as const;
+
+export type BadgeColour = keyof typeof BADGE_COLOURS;
+
+/**
+ * The three that clear the ΔE 33 floor against everything else on the mark. A surface picking outside this list
+ * is choosing a badge a reader cannot separate from the disc under it or the ring around it.
+ */
+export const BADGE_SAFE: readonly BadgeColour[] = ['sky', 'inverted', 'pink'];
+
+/** the first badge hue — vivid sky, the furthest colour from everything else on the mark */
+export const BADGE_COLOUR = BADGE_COLOURS.sky;
+/** the second, for a second class of fact — vivid pink */
+export const BADGE_COLOUR_ALT = BADGE_COLOURS.pink;
+
+/** The badge's outline: the background colour, like every other edge in the asset. */
+export const BADGE_EDGE = '--ui-bg';
+
+export interface MarkerBadge {
+  shape: BadgeShape;
+  /** the fill. Ink by default; never `--ui-error` or `--ui-warning` */
+  fill: unknown;
+  /** the outline, so the badge separates from the disc behind it. Defaults to the mark's `edge`. */
+  edge?: unknown;
+}
+
+/** every badge param switched off — the state of the region when a vehicle has nothing to add */
+export const BADGE_OFF: Record<string, unknown> = Object.fromEntries(
+  Object.values(BADGE_PARAMS).flatMap((p) => [
+    [p.fill, PARAM_OFF],
+    [p.edge, PARAM_OFF],
+  ]),
+);
+
+export interface MarkerColours {
+  /** the disc — the state group */
+  body: unknown;
+  /** the lit glyph */
+  glyph: unknown;
+  /**
+   * The stroke of the INNER circle — the mark's own edge, and its separation from the basemap. Always the
+   * background token. It belongs to the disc, so it survives the battery being switched off.
+   */
+  /**
+   * The stroke of the INNER circle — the mark's own edge, and its separation from the basemap. Always the
+   * background token.
+   *
+   * ★ THIS IS THE ONLY EDGE A CALLER PASSES. Every other outline in the asset — the battery ring's, the
+   * offline dot's, the badge's, the locked mark's — defaults to this value, because they are all the
+   * background colour and always will be.
+   *
+   * ⚠ They are still SEPARATE PARAMS IN THE FILE, and they have to be. An outline belongs to a region that
+   * can be switched off, and an SVG stroke does not disappear when its fill goes transparent: a `dotEdge`
+   * sharing the always-painted `edge` sentinel would paint a background-coloured ghost ring on the disc of
+   * every ONLINE vehicle. Measured — the ghost is real. What CAN share a sentinel is one region's several
+   * shapes: `lockedEdge` paints the pause mark's outline and both of its bars.
+   */
+  edge: unknown;
+  /**
+   * The OUTER circle: `fill` is the battery colour a reader sees as a ring.
+   *
+   * ★ OMIT IT and the whole outer circle disappears — both of its params go transparent together. That is the
+   * toggle: a surface that does not care about charge draws no ring at all. The mark then ends at 16 of 20
+   * units, so it is simply smaller — do NOT rescale to compensate, because one `icon-size` ramp shared by
+   * every surface is worth more than a constant footprint.
+   */
+  battery?: { fill: unknown; edge?: unknown };
+
+  /**
+   * The offline dot. OMIT IT for a vehicle that is reporting — the fill and the outline go transparent
+   * together, which is the only correct way to switch the region off.
+   *
+   * Same shape as `battery` and `locked` on purpose: all three are optional regions, and all three take a
+   * fill plus an outline that defaults to `edge`.
+   */
+  dot?: { fill: unknown; edge?: unknown };
+
+  /**
+   * The IN-USE gradient's two stops. Omit and the disc keeps `body`: both stops go transparent together and
+   * the gradient circle paints nothing.
+   *
+   * ⚠ A gradient cannot be a param — a param is one colour — so the gradient's GEOMETRY is baked into the
+   * asset and only its stops are addressable. Pass the same colour twice for a flat in-use disc.
+   */
+  inUse?: { from: unknown; to: unknown };
+
+  /**
+   * The pause mark, bottom-right, when the rider has LOCKED the vehicle. `edge` paints its outline AND its
+   * two bars — one region, three shapes.
+   */
+  locked?: { fill: unknown; edge?: unknown };
+}
+
+/**
+ * The params for ONE vehicle. Every region is set explicitly — an omitted param falls back to its
+ * magenta sentinel, so a complete object is the only safe kind, and there are fifteen of them.
+ * Hand-writing that is the thing this exists to prevent.
+ */
+export function markerParams(
+  state: VehicleState,
+  colours: MarkerColours,
+  badge?: MarkerBadge,
+  rental: RentalState = 'AVAILABLE',
+): Record<string, unknown> {
+  // ★ RENTAL WINS THE GLYPH. A vehicle a rider is on is FUNCTIONAL, so the state would light the bike — but
+  // "a rider has this" is the more useful fact at the moment somebody is reading one marker, and the disc has
+  // already changed underneath it. The state's own glyph comes back the instant the rental ends.
+  const lit = RENTAL_TAKEN.includes(rental) ? RENTAL_GLYPH : STATE_GLYPH[state];
+  const params: Record<string, unknown> = {
+    body: colours.body,
+    edge: colours.edge,
+    // the in-use gradient, off unless the caller passes both stops
+    inUseFrom: colours.inUse?.from ?? PARAM_OFF,
+    inUseTo: colours.inUse?.to ?? PARAM_OFF,
+    // the locked pause mark, off unless the caller asks for it
+    locked: colours.locked?.fill ?? PARAM_OFF,
+    lockedEdge: colours.locked ? (colours.locked.edge ?? colours.edge) : PARAM_OFF,
+    // the outer circle, off unless a caller asks for it
+    battery: colours.battery?.fill ?? PARAM_OFF,
+    // each optional region's outline defaults to the mark's own edge — one value, passed once
+    batteryEdge: colours.battery ? (colours.battery.edge ?? colours.edge) : PARAM_OFF,
+    // ⚠ The outline goes transparent WITH the fill. An SVG stroke does not disappear when its fill does, so a
+    // dot switched off by its fill alone leaves a background-coloured ghost ring on the disc.
+    dot: colours.dot?.fill ?? PARAM_OFF,
+    dotEdge: colours.dot ? (colours.dot.edge ?? colours.edge) : PARAM_OFF,
+    // Both shapes off by default. A caller that wants one turns exactly that one on, so a badge can never
+    // paint two shapes over each other.
+    ...BADGE_OFF,
+  };
+  if (badge) {
+    const region = BADGE_PARAMS[badge.shape];
+    params[region.fill] = badge.fill;
+    params[region.edge] = badge.edge ?? colours.edge;
+  }
+  for (const name of MARKER_GLYPH_PARAMS) params[name] = name === lit ? colours.glyph : PARAM_OFF;
+  return params;
+}
+
+/**
+ * The whole `icon-image` for a layer that draws EVERY vehicle from ONE symbol layer.
+ *
+ * This is what the marker collapses to now that expression-valued params are verified working
+ * (MAPS-SPEC M10): each param becomes a `match` on the feature, so there are no separate ring or dot
+ * layers, no radius ramps to keep in step between them, and nothing to get out of paint order.
+ *
+ * Callers pass resolved colours — `token()` values through `useMapOverlay`, or `resolveMapColor`
+ * output when driving the instance directly.
+ */
+export function markerImageExpression(opts: {
+  /** group → colour, from the VIVID set: { functional: token('--forest-map-functional'), … } */
+  group: Record<StateGroup, unknown>;
+  /** the glyph colour, usually the background token */
+  glyph: unknown;
+  /** the inner circle's stroke — the mark's own edge. `token('--ui-bg')` */
+  edge: unknown;
+  /**
+   * The outer circle, per battery band. Omit it (or pass `false`) and no vehicle gets a ring: both of its
+   * params go transparent, and the mark is the inner circle alone.
+   */
+  battery?: { fill: Record<BatteryRingBand, unknown>; edge: unknown } | false;
+  /** the offline dot. `edge` defaults to the mark's own `edge`, like every other optional region */
+  dot: { fill: unknown; edge?: unknown };
+  /**
+   * The badge, per feature. `when` is any expression that evaluates truthy for the vehicles that should
+   * carry it — `['get', 'claimed']`, or `['>', ['get', 'openTasks'], 0]`. Omit it and both shapes stay off.
+   */
+  badge?: { shape: BadgeShape; fill: unknown; edge: unknown; when: unknown };
+  /**
+   * The RENTAL axis. Omit it and every vehicle draws as free: no gradient, no pause mark, and the glyph
+   * stays the one the state asked for.
+   *
+   * The feature property is read as a `RentalState` string — the platform's value, untranslated. `inUse` is
+   * the gradient's two stops, `locked` is the pause mark. Pass both: PARKING draws the gradient as well.
+   */
+  rental?: { inUse: { from: unknown; to: unknown }; locked: { fill: unknown; edge: unknown } };
+  /** feature properties to read. Defaults match the fleet fixture */
+  props?: { state?: string; battery?: string; offline?: string; rental?: string };
+  /**
+   * Emit the LOD PAIR instead of one image: the same icon twice, glyphs off in the first. Pair it with
+   * `icon-image-cross-fade: markerGlyphCrossFade()`, or the layer pins itself to the glyph-less variant.
+   */
+  lod?: boolean;
+}): unknown[] {
+  const stateProp = ['get', opts.props?.state ?? 'state'];
+  const batteryProp = ['get', opts.props?.battery ?? 'battery'];
+  const offlineProp = ['get', opts.props?.offline ?? 'offline'];
+  const rentalProp = ['get', opts.props?.rental ?? 'rental'];
+  const states = Object.keys(STATE_GLYPH) as VehicleState[];
+  // Every taken state paints the gradient; only PARKING paints the corner mark.
+  const onRental = ['match', rentalProp, [...RENTAL_TAKEN], true, false];
+  const onLocked = ['==', rentalProp, RENTAL_PAUSED];
+
+  const params: Record<string, unknown> = {
+    // disc: state → its group's colour
+    body: [
+      'match',
+      stateProp,
+      ...states.flatMap((st) => [st, opts.group[STATE_GROUP[st]]]),
+      opts.group.hold,
+    ],
+    // the inner circle's stroke. One value, no expression: the mark's edge never varies by feature.
+    edge: opts.edge,
+    // the outer circle. Both params off together when a surface does not draw battery at all.
+    battery: opts.battery
+      ? ['match', batteryProp, 'CRITICAL', opts.battery.fill.CRITICAL, 'LOW', opts.battery.fill.LOW, opts.battery.fill.OK]
+      : PARAM_OFF,
+    batteryEdge: opts.battery ? opts.battery.edge : PARAM_OFF,
+    // dot: drawn only when the vehicle has stopped reporting
+    dot: ['case', ['to-boolean', offlineProp], opts.dot.fill, PARAM_OFF],
+    dotEdge: ['case', ['to-boolean', offlineProp], opts.dot.edge ?? opts.edge, PARAM_OFF],
+    // the in-use gradient: both stops together, on for a rental of any kind
+    inUseFrom: opts.rental ? ['case', onRental, opts.rental.inUse.from, PARAM_OFF] : PARAM_OFF,
+    inUseTo: opts.rental ? ['case', onRental, opts.rental.inUse.to, PARAM_OFF] : PARAM_OFF,
+    // the pause mark: only when the rider has locked it
+    locked: opts.rental ? ['case', onLocked, opts.rental.locked.fill, PARAM_OFF] : PARAM_OFF,
+    lockedEdge: opts.rental ? ['case', onLocked, opts.rental.locked.edge, PARAM_OFF] : PARAM_OFF,
+    // badge: both shapes off, then the chosen one switched on for the features `when` selects
+    ...BADGE_OFF,
+  };
+  if (opts.badge) {
+    const region = BADGE_PARAMS[opts.badge.shape];
+    const on = ['to-boolean', opts.badge.when];
+    params[region.fill] = ['case', on, opts.badge.fill, PARAM_OFF];
+    params[region.edge] = ['case', on, opts.badge.edge, PARAM_OFF];
+  }
+
+  // Each glyph lights for the states that use it, and is transparent for the rest.
+  //
+  // ★ With a rental layer the pine OVERRIDES the state's glyph, so every state glyph has to be suppressed
+  // while a rider has the vehicle — otherwise the bike and the pine paint on top of each other, which is
+  // exactly the tangle the one-glyph-at-a-time rule exists to prevent.
+  const rentalPine = opts.rental ? 'pine' : null;
+  for (const name of MARKER_GLYPH_PARAMS) {
+    if (name === rentalPine) {
+      params[name] = ['case', onRental, opts.glyph, PARAM_OFF];
+      continue;
+    }
+    const users = states.filter((st) => STATE_GLYPH[st] === name);
+    const byState: unknown = users.length
+      ? ['match', stateProp, ...users.flatMap((st) => [st, opts.glyph]), PARAM_OFF]
+      : PARAM_OFF;
+    params[name] = rentalPine ? ['case', onRental, PARAM_OFF, byState] : byState;
+  }
+
+  // ★★ THE LOD PAIR. The mark is drawn from `icon-size` 0.625, but the glyph — which paints
+  // strokeWidth × scale, not strokeWidth — only reaches a full pixel at 0.694. Between those two the
+  // disc, the edge and the ring are all fine and the glyph is a smudge.
+  //
+  // So the layer carries the SAME icon twice, once with every glyph switched off, and blends between
+  // them. A region is switched off by a transparent param, so the "coarse" variant needs no artwork of
+  // its own — which is what makes the two variants register perfectly: the disc, the edge and the ring
+  // are literally the same pixels, so the blend moves the GLYPH and nothing else.
+  //
+  // ⚠ `icon-image-cross-fade` takes only `measure-light` and `zoom` — no `feature`. The pair is a
+  //   camera-driven LOD and can never vary per vehicle. Pair this with markerGlyphCrossFade().
+  if (!opts.lod) return ['image', MARKER_ICON_ID, { params }];
+  const coarse: Record<string, unknown> = { ...params };
+  for (const name of MARKER_GLYPH_PARAMS) coarse[name] = PARAM_OFF;
+  return ['image', MARKER_ICON_ID, { params: coarse }, MARKER_ICON_ID, { params }];
+}
+
+/**
+ * The cross-fade that brings the glyph in, for a layer using `markerImageExpression({ lod: true })`.
+ *
+ * ★ DERIVED END TO END. The asset says at which `icon-size` its glyph reaches the floor
+ * (`manifest.glyph.floorIconSize`); the ramp says which zoom that is. Nobody types a zoom, so moving
+ * the ramp or re-drawing the glyph moves this with them.
+ *
+ * ⚠ Drive it with THIS expression, never a constant — the property is camera-parameterised, and a
+ *   bare number pins every vehicle to one variant for good.
+ */
+export function markerGlyphCrossFade(): unknown[] {
+  return [
+    'interpolate',
+    ['linear'],
+    ['zoom'],
+    zoomAtIconSize(MARKER_MIN_ICON_SIZE),
+    0,
+    zoomAtIconSize(markerManifest.glyph.floorIconSize),
+    1,
+  ];
+}
+
+/**
+ * Paint the real asset for the browser: substitute each sentinel with the colour its param carries, and
+ * hand back the artwork.
+ *
+ * ★ This is how a docs surface shows the marker WITHOUT redrawing it. A redrawing has to duplicate the
+ * glyph paths and the geometry, and then it drifts — silently, because a diagram cannot fail a build.
+ * Fetch `/map-icons/<manifest.file>`, run it through here, and what is on screen is the file, painted
+ * exactly the way Mapbox will paint it.
+ *
+ * `inner: true` strips the root `<svg>` and the `<m:metadata>` block, leaving artwork that can be
+ * dropped inside a `<g>` in some other coordinate space — which is what lets a diagram scale it up and
+ * annotate it. The metadata has to go: it declares the sentinels, so leaving it in would put unpainted
+ * magenta values back into the markup.
+ *
+ * ★ `idPrefix` IS REQUIRED WHEN A PAGE INLINES MORE THAN ONE COPY. The asset carries a `<radialGradient>`
+ * with an id, and an id is unique per DOCUMENT — which is fine in Mapbox, where each icon is its own
+ * document, and broken in a browser, where sixty inlined markers all resolve `url(#inUse)` to the FIRST
+ * one's stops. The symptom is subtle and uniform: every gradient paints whatever the first marker on the
+ * page happens to be, so a panel of variants silently shows one variant. Pass a unique prefix per instance.
+ */
+export function paintMarkerSvg(
+  raw: string,
+  params: Record<string, string>,
+  opts: { inner?: boolean; idPrefix?: string } = {},
+): string {
+  let svg = raw;
+  // ★ The name→sentinel table comes from the FILE, not from a manifest this module imports. Every asset
+  // declares its own params in `<m:metadata>`, and the sentinels are positional — so the vehicle's fourth
+  // sentinel and a place asset's fourth sentinel are the same hex with different names. Reading the
+  // vehicle's manifest here painted a place's glyphs with the vehicle's param names, which resolved to
+  // nothing and left every glyph transparent.
+  const declared = [...raw.matchAll(/<m:parameter[^>]*m:name="([^"]+)"[^>]*m:value="([^"]+)"/g)].map((m) => ({
+    name: m[1],
+    sentinel: m[2],
+  }));
+  const table = declared.length ? declared : markerManifest.params;
+  for (const p of table) {
+    svg = svg.replaceAll(p.sentinel, params[p.name] ?? PARAM_OFF);
+  }
+  if (opts.idPrefix) {
+    // Rewrite every declared id and every reference to it. Both halves have to move together, so this is one
+    // pass over the two forms the asset can use: `id="x"` and `url(#x)`.
+    svg = svg
+      .replace(/\sid="([^"]+)"/g, (_m, id) => ` id="${opts.idPrefix}-${id}"`)
+      .replace(/url\(#([^)]+)\)/g, (_m, id) => `url(#${opts.idPrefix}-${id})`);
+  }
+  if (!opts.inner) return svg;
+  return svg
+    .replace(/<m:metadata>[\s\S]*?<\/m:metadata>/, '')
+    .replace(/^[\s\S]*?<svg[^>]*>/, '')
+    .replace(/<\/svg>\s*$/, '')
+    .trim();
+}
+
+/** the asset's own viewBox size, so a caller scaling it does not hard-code 40 */
+export const MARKER_CANVAS = markerManifest.size;
+
+/**
+ * The battery ring — the outer circle's fill, in THREE bands.
+ *
+ * ★ SEMANTIC, because the ring says how bad the charge is: green when there is nothing to do, amber when
+ * the bike wants collecting soon, red when it wants collecting now. A surface that does not dispatch on
+ * charge switches the whole outer circle off instead of painting it a quiet colour.
+ */
+export const BATTERY_RING: Record<BatteryRingBand, string> = {
+  OK: '--ui-success',
+  LOW: '--ui-warning',
+  CRITICAL: '--ui-error',
+};
+
+/** the ring colour for a platform level, through the three bands */
+export const batteryRingToken = (level: BatteryLevel): string => BATTERY_RING[BATTERY_RING_BAND[level]];
+
+/**
+ * The IN-USE disc — a two-stop radial gradient, vivid amber into vivid green.
+ *
+ * ★ Chosen by search, not by taste: 824 ramp pairs, each scored on the WORST distance to everything else on
+ * the mark (five discs and all three ring bands, because the ring is concentric with the disc). This pair
+ * scores ΔE 42.7 at its worst, against a floor of 33 — and the two collisions already shipped are 17 and 7.
+ *
+ * Why a gradient at all, when a flat `acid-700` measures BETTER (44.7): the flat colour wins on separation
+ * and the gradient wins on being unmistakable. It is the one mark on the map that says "somebody is riding
+ * this", and the sweep reads as alive where a flat chip does not.
+ *
+ * ⚠ The brightness is capped by the GLYPH, not by the palette. The pine is painted in the background colour,
+ * so a brighter disc loses it: above roughly L 60 the mean drops under 3:1 and the mark reads as a blank chip
+ * with a ghost in it. This pair sits at L 54.7 with 3.70 — bright, with margin.
+ *
+ * ★ VERIFIED ON THE PUBLISHED STYLE (2026-07-26, mapbox-gl 3.24.1). The gradient renders AND param
+ * substitution reaches a `stop-color`: the disc reads as a monotonic ramp, 231,190,8 → 121,206,60 across nine
+ * samples, with the sentinel nowhere. `IN_USE_FLAT` therefore stops being a pending risk and becomes an
+ * option — a surface that wants a flat in-use disc points both stops at it.
+ */
+export const IN_USE_GRADIENT = { from: '--forest-map-inuse-from', to: '--forest-map-inuse-to' } as const;
+
+/** the fallback if the renderer will not draw a gradient. Measured best-in-class among flat colours. */
+export const IN_USE_FLAT = '--forest-map-inuse-flat';
+
+/**
+ * The pause mark a locked rental puts in the bottom-right corner.
+ *
+ * INK, not vivid and not semantic. It is the strongest value against every disc, and the rental axis is
+ * neither a category among the state groups nor a severity — so it takes neither palette.
+ */
+export const LOCKED_MARK = '--forest-map-locked';
+
+/** the glyph a taken vehicle lights, whatever its state asked for. AVAILABLE keeps the state's own. */
+export const RENTAL_GLYPH = 'pine';
+
+/** the charge levels whose ring is a warning rather than a healthy green */
+export const BATTERY_ALERT: readonly BatteryLevel[] = ['LOW', 'CRITICAL'];
+
+/**
+ * The offline dot. Red: a vehicle that has stopped reporting is a fault, not a status. It sits on the
+ * marker's shoulder rather than on its edge, so it never competes with the red a critical battery puts
+ * on the border — different position, different shape, same urgency vocabulary.
+ */
+export const OFFLINE_DOT = '--ui-error';
+
+/** The states a bike can be rentable in. Only FUNCTIONAL today; the others are here because the
+ *  platform has them in its vocabulary and any of them could be adopted without changing this code. */
+export const AVAILABLE_STATES: readonly VehicleState[] = ['FUNCTIONAL'];
+
+/** Battery bands that still allow a rental. LOW is deliberately not one — a rider should not start a
+ *  trip on a bike that is about to need collecting. */
+export const AVAILABLE_BATTERY: readonly BatteryLevel[] = ['HIGH', 'MEDIUM'];
+
+export interface VehicleFacts {
+  state: VehicleState;
+  battery: BatteryLevel;
+  offline: boolean;
+  /**
+   * ⚠ OPTIONAL, and it defaults to AVAILABLE deliberately. The 31,602/31,602 agreement with the platform's own
+   * `available` flag was measured BEFORE this axis existed, on a snapshot that carried no rental data — so a
+   * caller that passes nothing gets exactly the behaviour that was verified. Pass it and a rented vehicle is
+   * correctly unavailable.
+   */
+  rental?: RentalState;
+}
+
+/**
+ * Availability, derived. Reproduces the platform's `available` flag on 31,602/31,602 production
+ * vehicles — so this is the rule, not an approximation of it.
+ */
+export const isAvailable = (v: VehicleFacts): boolean =>
+  !v.offline &&
+  (v.rental ?? 'AVAILABLE') === 'AVAILABLE' &&
+  AVAILABLE_STATES.includes(v.state) &&
+  AVAILABLE_BATTERY.includes(v.battery);
+
+/**
+ * EVERY reason a bike is not available, not just the first one. Null when it is available.
+ *
+ * All three axes can fail at once, and a list that says only "offline" about a bike that is also flat
+ * sends someone to do half a job. The marker shows all three simultaneously — the words beside it
+ * should too.
+ */
+export function unavailableReasons(v: VehicleFacts): string[] {
+  const reasons: string[] = [];
+  if (!AVAILABLE_STATES.includes(v.state)) reasons.push(v.state.toLowerCase().replace(/_/g, ' '));
+  // A rented vehicle is not "unavailable" in the same sense as a broken one, and the wording says so: the
+  // operation does not have to do anything about it.
+  if (v.rental && v.rental !== 'AVAILABLE') reasons.push(v.rental.toLowerCase());
+  if (v.offline) reasons.push('offline');
+  if (!AVAILABLE_BATTERY.includes(v.battery)) reasons.push(`battery ${v.battery.toLowerCase()}`);
+  return reasons;
+}
+
+/** The same, as one phrase for a callout. Null when the bike is available. */
+export function unavailableReason(v: VehicleFacts): string | null {
+  const reasons = unavailableReasons(v);
+  if (!reasons.length) return null;
+  if (reasons.length === 1) return reasons[0];
+  return `${reasons.slice(0, -1).join(', ')} and ${reasons.at(-1)}`;
+}
+
+/**
+ * An enum value as prose: `SERVICE_ON_SITE` → "Service on site", `OK` → "OK".
+ *
+ * ★ ONE helper, because every surface that shows a state, a group, a band or a rental state was lowercasing it
+ * by hand — and lowercasing everything reads as a stylistic tic rather than as a vocabulary. Sentence case:
+ * the value is a proper noun in this system's vocabulary, not a label in a form.
+ *
+ * Short all-caps values are left alone (`OK`), because they are initialisms rather than words.
+ */
+export const labelOf = (value: string): string => {
+  if (value.length <= 2) return value;
+  const words = value.toLowerCase().replace(/_/g, ' ');
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+/** A style-spec `match` from a feature property to each group's token expression input. */
+export const groupMatchInput = (property = 'state'): unknown[] => {
+  const pairs: unknown[] = [];
+  for (const [state, group] of Object.entries(STATE_GROUP)) pairs.push(state, group);
+  return ['match', ['get', property], ...pairs, 'hold'];
+};