@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/map/FMapZoom.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+// The zoom pair, as canvas chrome rather than Mapbox's own control.
+//
+//   <FMapZoom :map="map" />
+//
+// ★ WHY NOT mapboxgl.NavigationControl. Not the icons — the PLACEMENT. Mapbox mounts its controls into
+// its own corner containers inside the map element, which are not the HUD's areas: they cannot sit in a
+// rail, cannot take the canvas-chrome surface with everything else, and — the one that bites — cannot
+// step aside for an open <FSidePanel>. The HUD insets its areas from the strip a panel publishes;
+// Mapbox's corners know nothing about it, so a panel simply covers them.
+//
+// Nothing is lost by rebuilding it: zoom is two buttons calling two methods. Where behaviour is the
+// point rather than chrome — geolocation's permissions and tracking — the Mapbox control is WRAPPED
+// instead (FMapGeolocate).
+//
+// ★ THE MAP IS A PROP, NOT AN INJECTION, and that is forced rather than chosen. Not because the control
+// is authored in the page's template: Vue resolves provide/inject through the MOUNTED tree, so slot
+// content injects from whatever renders the slot — UFieldGroup sizes its buttons exactly that way, and
+// this control would inject from <FCanvasHud> if the HUD provided anything. The reason is siblinghood.
+// <FMap> sits in the HUD's default slot and this sits in a rail, so it is never on the ancestor chain and
+// `inject(FOREST_MAP)` resolves to nothing. (The same siblinghood makes FSidePanel publish a custom
+// property instead of providing a value.) The page already holds the instance from `@ready`.
+import { onBeforeUnmount, ref, watch } from 'vue';
+import type mapboxgl from 'mapbox-gl';
+import FCanvasControl from '../canvas/FCanvasControl.vue';
+import FCanvasControlGroup from '../canvas/FCanvasControlGroup.vue';
+
+const props = withDefaults(
+  defineProps<{
+    /** The live map, from <FMap @ready>. Null until it arrives, which disables the pair. */
+    map?: mapboxgl.Map | null;
+    /** The hub is horizontal; rails are not. */
+    orientation?: 'vertical' | 'horizontal';
+  }>(),
+  { map: null, orientation: 'vertical' },
+);
+
+// ★ Disabled at the ends, which a hand-rolled pair forgets: a zoom-in that does nothing at maxZoom is a
+// control lying about what it can do. Stock's NavigationControl tracks this, so rebuilding it without
+// the tracking would be a regression rather than a like-for-like swap.
+const atMax = ref(false);
+const atMin = ref(false);
+
+const sync = () => {
+  const m = props.map;
+  if (!m) return;
+  const z = m.getZoom();
+  atMax.value = z >= m.getMaxZoom() - 0.001;
+  atMin.value = z <= m.getMinZoom() + 0.001;
+};
+
+watch(
+  () => props.map,
+  (m, _old, onCleanup) => {
+    if (!m) return;
+    sync();
+    m.on('zoom', sync);
+    onCleanup(() => m.off('zoom', sync));
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => props.map?.off('zoom', sync));
+</script>
+
+<template>
+  <FCanvasControlGroup :orientation="orientation">
+    <FCanvasControl
+      icon="i-lucide-plus"
+      label="Zoom in"
+      :disabled="!map || atMax"
+      @click="map?.zoomIn()"
+    />
+    <FCanvasControl
+      icon="i-lucide-minus"
+      label="Zoom out"
+      :disabled="!map || atMin"
+      @click="map?.zoomOut()"
+    />
+  </FCanvasControlGroup>
+</template>

package/packages/ui/src/map/FMarker.vue

@@ -0,0 +1,218 @@
+<script setup lang="ts">
+// FMarker — Forest's marker on a Mapbox map, declared rather than assembled. Nest it in <FMap> and
+// it finds the map itself; props drive appearance, so a bike that drops to 9% or gets selected
+// re-renders like any other component instead of having classes toggled on a detached element.
+//
+// Slots: the default one REPLACES the pin — the shape, the fill, the ring and the size, not just the icon —
+// for a surface bringing its own object, e.g. <FVehicleMark>. `popup` takes an <FMapPopup>. They are separate
+// on purpose: a popup in the default slot renders nothing visible and would silently blank the marker.
+//
+// Two recipes, which is the whole system:
+//   pin  — a filled circle, tone = the fill. Live entities: bikes, the active job, an alert.
+//   pill — a quiet surface, tone = the text. Anything carrying a value or a name (charge, id).
+// Both wear a halo ring in the page background colour, which is what keeps them readable over any
+// light preset. Colour follows the map doctrine: primary for live entities, neutral for inert
+// places, warning/error for alerts only.
+//
+// ★ The element handed to mapbox NEVER carries a Vue :class — mapbox writes `mapboxgl-marker` and an
+// anchor class onto it, and a Vue class patch wipes them (the marker stops being positioned). So the
+// element is a plain wrapper created imperatively and the styled content is teleported inside it.
+import { computed, nextTick, onBeforeUnmount, provide, ref, shallowRef, useSlots, watch } from 'vue';
+import mapboxgl from 'mapbox-gl';
+import { FOREST_MARKER } from './mapContext';
+import { useLazyHost, useMapReady } from './useMap';
+
+// mapbox keeps its anchor union internal, so state it here rather than reaching for a private type.
+type Anchor =
+  | 'center' | 'top' | 'bottom' | 'left' | 'right'
+  | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+const props = withDefaults(
+  defineProps<{
+    lngLat: [number, number];
+    /** `pin` for live entities, `pill` when the marker carries a value or a name */
+    shape?: 'pin' | 'pill';
+    color?: 'primary' | 'neutral' | 'warning' | 'error';
+    /** icon name from the registered collections, e.g. `i-forest-bike`, `i-lucide-battery-low` */
+    icon?: string;
+    /** pill text. Ignored by `pin`, which is icon-only */
+    label?: string;
+    size?: 'sm' | 'md' | 'lg';
+    /** lifts and rings the marker — for the one entity a surface is acting on */
+    selected?: boolean;
+    /** takes clicks: adds a cursor, a focus ring, and a touch-sized hit area on coarse pointers */
+    interactive?: boolean;
+    /** accessible name for the interactive case. Falls back to `label` */
+    ariaLabel?: string;
+    /**
+     * The reader can move it, and `dragend` reports where it landed — a location picker, a bay being
+     * placed, "report a problem here".
+     *
+     * ★ Mapbox owns the gesture, including the pointer capture that stops the MAP panning under the
+     * drag. Rebuilding it on the element would fight that: the marker would move and the map would
+     * pan with it.
+     */
+    draggable?: boolean;
+    anchor?: Anchor;
+    offset?: [number, number];
+  }>(),
+  {
+    shape: 'pin',
+    color: 'primary',
+    icon: undefined,
+    label: undefined,
+    size: 'md',
+    selected: false,
+    interactive: false,
+    ariaLabel: undefined,
+    draggable: false,
+    anchor: 'center',
+    offset: undefined,
+  },
+);
+
+const emit = defineEmits<{
+  click: [];
+  /**
+   * Dragging finished, with where it landed. Fires only on `dragend`, never per frame — a surface
+   * reacting to a drag usually reverse geocodes or saves, and doing either sixty times a second is
+   * both wrong and billed.
+   */
+  dragend: [at: [number, number]];
+}>();
+
+const marker = shallowRef<mapboxgl.Marker | null>(null);
+// A <FMapPopup> in the `popup` slot binds to this marker.
+provide(FOREST_MARKER, marker);
+
+// The element mapbox owns. Created on demand, not during setup (which may run on a server), and kept
+// free of Vue bindings — see the note above.
+const { host, ensure } = useLazyHost();
+
+useMapReady((m) => {
+  if (marker.value) return;
+  marker.value = new mapboxgl.Marker({
+    element: ensure(),
+    anchor: props.anchor,
+    draggable: props.draggable,
+    ...(props.offset ? { offset: props.offset } : {}),
+  })
+    .setLngLat(props.lngLat)
+    .addTo(m);
+
+  marker.value.on('dragend', () => {
+    const at = marker.value!.getLngLat();
+    emit('dragend', [at.lng, at.lat]);
+  });
+});
+
+watch(
+  () => props.lngLat,
+  (at) => marker.value?.setLngLat(at),
+);
+
+// Toggleable after creation, because a surface often arms dragging only in an editing mode.
+watch(
+  () => props.draggable,
+  (on) => marker.value?.setDraggable(on),
+);
+
+// The wrong-slot trap, made loud. A popup put in the DEFAULT slot replaces the pin instead of
+// attaching to it: the slot renders only a teleport anchor, so the marker paints nothing and there is
+// no error anywhere. Nothing distinguishes that from a marker that is simply empty, so the check is
+// the DOM: content was provided, yet the visual box has no element and no text in it.
+const visualEl = ref<HTMLElement | null>(null);
+const slots = useSlots();
+if (import.meta.env.DEV) {
+  watch(marker, async (mk) => {
+    if (!mk || !slots.default) return;
+    await nextTick();
+    const el = visualEl.value;
+    if (!el || el.childElementCount > 0 || el.textContent?.trim()) return;
+    console.warn(
+      '[FMarker] the default slot rendered nothing, so this marker is blank. An <FMapPopup> belongs ' +
+        'in the `popup` slot — the default slot REPLACES the pin.\n' +
+        '  <FMarker><template #popup><FMapPopup>…</FMapPopup></template></FMarker>',
+    );
+  });
+}
+
+onBeforeUnmount(() => marker.value?.remove());
+
+// ── Appearance ────────────────────────────────────────────────────────────
+const PIN_SIZE = { sm: 'size-6', md: 'size-7', lg: 'size-9' };
+const ICON_SIZE = { sm: 'size-3', md: 'size-3.5', lg: 'size-4.5' };
+const PILL_SIZE = { sm: 'px-2 py-0.5 text-[11px]', md: 'px-2.5 py-1 text-xs', lg: 'px-3 py-1.5 text-sm' };
+// pin: tone fills. pill: tone is the text on a quiet surface.
+const PIN_TONE = {
+  primary: 'bg-primary text-inverted',
+  neutral: 'bg-elevated text-default',
+  warning: 'bg-warning text-inverted',
+  error: 'bg-error text-inverted',
+};
+const PILL_TONE = {
+  primary: 'text-primary',
+  neutral: 'text-muted',
+  warning: 'text-warning',
+  error: 'text-error',
+};
+
+/**
+ * ★ A DEFAULT SLOT REPLACES THE PIN, INCLUDING ITS CHROME.
+ *
+ * The comment at the top of this file always said the slot replaces the pin; the classes did not — the slot
+ * only replaced the ICON, so an object handed in still landed inside a coloured circle with the pin's ring,
+ * shadow and fixed size. `<FVehicleMark>` in the slot came out as a marker inside a marker.
+ *
+ * With a slot, the wrapper keeps only what belongs to the MARKER rather than to the pin: layout, the transition,
+ * the lift when selected, and the pointer. The object brings its own shape and its own edge — the vehicle asset
+ * already carries a background-coloured stroke, which is the same job `ring-2 ring-(--ui-bg)` does for a pin.
+ */
+const visual = computed(() => {
+  // The transition carries the selected lift/scale — a small near element, so the --motion-fast pair.
+  const base = 'flex items-center justify-center transition duration-(--motion-fast) ease-(--motion-ease-out)';
+  if (slots.default) {
+    return [base, props.selected ? 'z-10 scale-110' : '', props.interactive ? 'cursor-pointer' : ''];
+  }
+  return [
+    base,
+    'rounded-full shadow-md',
+    // The halo: a ring in the page background separates the marker from whatever the basemap put
+    // underneath it, in every light preset.
+    'ring-2 ring-(--ui-bg)',
+    props.shape === 'pin'
+      ? [PIN_SIZE[props.size], PIN_TONE[props.color]]
+      : ['gap-1 bg-default font-semibold ring-1 ring-default', PILL_SIZE[props.size], PILL_TONE[props.color]],
+    props.selected ? 'z-10 scale-110 ring-primary' : '',
+    props.interactive ? 'cursor-pointer' : '',
+  ];
+});
+</script>
+
+<template>
+  <Teleport v-if="host" :to="host">
+    <component
+      :is="interactive ? 'button' : 'div'"
+      :type="interactive ? 'button' : undefined"
+      :aria-label="interactive ? (ariaLabel ?? label) : undefined"
+      :class="[
+        'flex items-center justify-center',
+        // Touch surfaces need a 44px target; growing the pin instead would break the size ladder,
+        // so the hit area is transparent padding around it. Fine pointers keep the tight box.
+        interactive ? 'coarse:size-11 rounded-full focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary' : '',
+      ]"
+      @click="emit('click')"
+    >
+      <span ref="visualEl" :class="visual">
+        <!-- Default slot REPLACES the pin, so a popup must not live here — it would render as two
+             teleport anchors and suppress the icon. That is what the `popup` slot below is for. -->
+        <slot>
+          <UIcon v-if="icon" :name="icon" :class="ICON_SIZE[size]" />
+          <span v-if="label && shape === 'pill'">{{ label }}</span>
+        </slot>
+      </span>
+      <!-- <FMapPopup> declares itself here and teleports its body into mapbox's popup element. -->
+      <slot name="popup" />
+    </component>
+  </Teleport>
+</template>

package/packages/ui/src/map/FTrackScrubber.vue

@@ -0,0 +1,94 @@
+<script setup lang="ts">
+// The transport bar for a track.
+//
+// It is FTrackScrubber and not FMapPlayback because it needs no map — the same reason FVehicleMark and
+// FVehicleLegend are not FMap-prefixed. It scrubs a track; whether anything is drawing that track is
+// not its business.
+import { computed } from 'vue';
+import { elapsedLabel } from './track';
+import type { TrackPlayback } from './useTrackPlayback';
+
+const props = withDefaults(
+  defineProps<{
+    playback: TrackPlayback;
+    /** the multipliers offered. Default 1, 2, 4, 8 */
+    speeds?: number[];
+    /** what the slider is scrubbing, for a screen reader */
+    label?: string;
+  }>(),
+  { speeds: () => [1, 2, 4, 8], label: 'Playback position' },
+);
+
+// Speed is derived from what the surface passes into useTrackPlayback, so this control asks rather
+// than sets. The surface owns the value it hands the clock.
+const emit = defineEmits<{ 'update:speed': [speed: number | 'fit'] }>();
+
+/**
+ * ★ THE MENU SHOWS THE SETTING, NOT THE RESOLVED MULTIPLIER.
+ *
+ * `fit` on a 50-minute trip resolves to about 101×. Binding the menu to that put 101.4 in a list of
+ * 1/2/4/8 — a selected value present in no option, truncated to "101…" by the control's width.
+ * `fit` is the first option because it is the default and the one most readers want.
+ */
+const speedItems = computed(() => [
+  { label: 'Fit', value: 'fit' as const },
+  ...props.speeds.map((s) => ({ label: `${s}×`, value: s })),
+]);
+
+const empty = computed(() => !props.playback.span.value.ms);
+const elapsed = computed(() => elapsedLabel(props.playback.at.value - props.playback.span.value.start));
+const total = computed(() => elapsedLabel(props.playback.span.value.ms));
+
+/**
+ * The wall-clock time under the playhead.
+ *
+ * ★ This is what a screen reader announces. "43 per cent" is a number nobody can act on — an operator
+ * auditing a rental is looking for a moment, not a fraction.
+ */
+const stamp = computed(() =>
+  empty.value ? '' : new Date(props.playback.at.value).toLocaleTimeString('en-GB'),
+);
+
+const percent = computed({
+  get: () => Math.round(props.playback.progress.value * 100),
+  set: (v: number) => props.playback.seekProgress(v / 100),
+});
+</script>
+
+<template>
+  <div class="flex items-center gap-3">
+    <UButton
+      :icon="playback.playing.value ? 'i-lucide-pause' : 'i-lucide-play'"
+      :aria-label="playback.playing.value ? 'Pause' : 'Play'"
+      color="neutral"
+      variant="ghost"
+      :disabled="empty"
+      @click="playback.toggle()"
+    />
+
+    <!-- Times are tabular: Mohr has no tabular figures, so the role swaps the face. Without it the
+         digits jitter as the clock runs and the eye tracks that instead of the map. -->
+    <span class="type-tabular text-sm">{{ elapsed }}</span>
+
+    <USlider
+      v-model="percent"
+      class="flex-1"
+      :min="0"
+      :max="100"
+      :disabled="empty"
+      :aria-label="label"
+      :aria-valuetext="stamp"
+    />
+
+    <span class="type-tabular text-sm text-dimmed">{{ total }}</span>
+
+    <USelect
+      :model-value="playback.mode.value"
+      :items="speedItems"
+      :disabled="empty"
+      aria-label="Playback speed"
+      class="w-24"
+      @update:model-value="(v: number | 'fit') => emit('update:speed', v)"
+    />
+  </div>
+</template>

package/packages/ui/src/map/FVehicleLegend.vue

@@ -0,0 +1,72 @@
+<script setup lang="ts">
+// The key to a vehicle mark.
+//
+//   <FCanvasCard><FVehicleLegend /></FCanvasCard>
+//   <FVehicleLegend :axes="['state']" />        a surface that paints no ring
+//
+// ★ A SECTION PER AXIS, and the sections are the content. A vehicle is three independent axes rather
+// than one status enum, so a flat list would read as one enum with 36 values. Within a section exactly
+// one channel moves — see vehicleLegend.ts, which builds the rows and holds everything else still.
+//
+// ★ THE SWATCH IS THE MARK. <FVehicleMark> needs no map and draws at its natural size, so a row shows
+// the artwork the map actually draws rather than a square approximating a disc inside a ring. It is
+// also the only swatch that can show a glyph, which no colour chip can.
+//
+// ★ IT CARRIES NO SURFACE, like <FMapLegend>. Over a basemap it wants a panel, and FCanvasCard is the
+// panel the rest of the chrome uses.
+import FVehicleMark from './FVehicleMark.vue';
+import { vehicleLegendSections, type VehicleLegendAxis } from './vehicleLegend';
+import { MARKER_CANVAS } from './vehicle';
+import { computed } from 'vue';
+
+const props = withDefaults(
+  defineProps<{
+    /** The axes this surface paints. Drop `charge` where the marks carry no ring. */
+    axes?: VehicleLegendAxis[];
+    /**
+     * The drawn size of each row's mark.
+     *
+     * Defaults to the asset's own canvas — 1:1, the size the map draws. A key that shrank its marks
+     * would be showing a reader something other than what they are looking at, so scaling down is a
+     * decision a surface makes deliberately rather than a default it inherits.
+     */
+    size?: number;
+    /**
+     * The colour the marks' edges paint, forwarded to each <FVehicleMark>.
+     *
+     * A mark separates from its background with an edge in the background's own colour, so a legend on
+     * a panel that is not `--ui-bg` passes that panel's token or the edge stops working.
+     */
+    edge?: string;
+  }>(),
+  { axes: () => ['state', 'charge', 'connectivity'], size: MARKER_CANVAS, edge: undefined },
+);
+
+const sections = computed(() => vehicleLegendSections(props.axes));
+</script>
+
+<template>
+  <div class="flex flex-col gap-3">
+    <section v-for="section in sections" :key="section.axis" class="flex flex-col gap-1.5">
+      <p class="type-overline text-dimmed">{{ section.label }}</p>
+
+      <ul role="list" class="flex flex-col gap-1">
+        <li v-for="row in section.rows" :key="row.key" class="flex items-center gap-2">
+          <FVehicleMark
+            :state="row.mark.state"
+            :battery="row.mark.battery"
+            :offline="row.mark.offline"
+            :size="size"
+            :edge="edge"
+            aria-hidden="true"
+          />
+          <span class="type-caption text-default">{{ row.label }}</span>
+        </li>
+      </ul>
+
+      <!-- The silent case. It has no row because it paints nothing: a reporting vehicle carries no dot
+           at all, which is what keeps 80% of the fleet from being inked to say nothing is happening. -->
+      <p v-if="section.note" class="type-caption text-muted">{{ section.note }}</p>
+    </section>
+  </div>
+</template>

package/packages/ui/src/map/FVehicleMark.vue

@@ -0,0 +1,166 @@
+<script lang="ts">
+/**
+ * ⚠ MODULE SCOPE, deliberately. `<script setup>` runs once PER INSTANCE, so a counter declared there resets
+ * to the same value for every mark — every instance would take the id `fvm1`, and the gradient collision this
+ * prefix exists to prevent would be back with extra steps.
+ */
+let seq = 0;
+const nextUid = () => `fvm${(seq += 1)}`;
+</script>
+
+<script setup lang="ts">
+// FVehicleMark — one vehicle, drawn from its facts. NOT a map component.
+//
+// ★ WHY `Mark` AND NOT `Marker`. They are two concepts in this system, not synonyms:
+//
+//     MARK    the graphic. Artwork with no position — it goes in a list row or a detail header.
+//     MARKER  a mark POSITIONED on a map, by a symbol layer or by <FMarker> at a lngLat.
+//
+// This takes no coordinate and needs no map, so `FVehicleMarker` would be a promise it does not keep — and
+// `FMarker` already owns "marker" for the positioned thing. The docs on /maps/fleet-markers declare both terms.
+//
+// ★ IT PAINTS THE UPLOADED ASSET, so there is ONE source of truth for the artwork and two renderers for two
+// jobs. The fleet is a symbol layer, because 30k marks have to be on the GPU and need collision, sort keys and
+// paint-order slots. Everything else — the selected vehicle on a map, a list row, a detail header, a legend —
+// is this component, because a DOM object can be focused, read by a screen reader, and put in a table cell,
+// and a symbol inside a canvas is pixels.
+//
+// Before this existed the two paths drew DIFFERENT marks: `FMarker` painted a plain pin with `i-forest-bike`,
+// so a vehicle changed shape when you selected it, and the two could drift apart with no build error to catch
+// it. Now selection changes the halo and nothing else.
+//
+// ⚠ NO FETCH. The asset is inlined (`markerAsset.ts`, emitted by the generator) rather than loaded from a
+// public path, because a consuming app has no `/map-icons/` URL and a fetch would flash an empty mark on first
+// paint. It costs ~8 KB in the bundle of anything that imports this.
+//
+// Usage on a map — FMarker's default slot replaces the pin, so the mark is the marker:
+//   <FMarker :lng-lat="v.at" selected interactive><FVehicleMark v-bind="v.facts" /></FMarker>
+// Usage anywhere else:
+//   <FVehicleMark state="FUNCTIONAL" battery="LOW" :size="28" />
+import { computed } from 'vue';
+import { MARKER_SVG } from './markerAsset';
+import manifest from '../../icons/forest/map/manifest.json';
+import {
+  BADGE_COLOURS,
+  BADGE_EDGE,
+  IN_USE_GRADIENT,
+  LOCKED_MARK,
+  OFFLINE_DOT,
+  RENTAL_PAUSED,
+  RENTAL_TAKEN,
+  STATE_GROUP,
+  STATE_GROUP_COLOUR,
+  batteryRingToken,
+  labelOf,
+  stateLabel,
+  markerParams,
+  paintMarkerSvg,
+  type BadgeShape,
+  type BatteryLevel,
+  type RentalState,
+  type VehicleState,
+} from './vehicle';
+import { resolveMapColor } from './mapColor';
+import { useTokenMode } from './useTokenMode';
+
+const props = withDefaults(
+  defineProps<{
+    /** what the operation thinks of the vehicle */
+    state: VehicleState;
+    /**
+     * Charge. OMIT IT and no ring is drawn at all — the mark is then 20% smaller from the same artwork, which
+     * is correct and must not be compensated for. Pass it on a surface that dispatches on charge.
+     */
+    battery?: BatteryLevel;
+    /** the vehicle has stopped reporting */
+    offline?: boolean;
+    /** what a rider is doing with it. The platform's own `rentalState`, passed through */
+    rental?: RentalState;
+    /** the fourth region — a claim, or an open task. Nothing paints one in production yet */
+    badge?: BadgeShape;
+    /** the badge's fill, as a token name. Never `--ui-error` or `--ui-warning` */
+    badgeColour?: string;
+    /** the drawn size in px. The asset is a 40-unit canvas, so 40 is 1:1 */
+    size?: number;
+    /**
+     * The colour the mark's edges paint — its separation from whatever is behind it.
+     *
+     * Defaults to `--ui-bg`, which is right on a page and on a Forest basemap. A surface drawing the mark on a
+     * coloured panel passes that panel's token instead, or the edge disappears into it.
+     */
+    edge?: string;
+  }>(),
+  {
+    battery: undefined,
+    offline: false,
+    rental: 'AVAILABLE',
+    badge: undefined,
+    badgeColour: BADGE_COLOURS.sky,
+    size: 40,
+    edge: '--ui-bg',
+  },
+);
+
+// ★ NOT `isDark`. resolveMapColor reads getComputedStyle, so it has to run AFTER the mode class lands on
+// <html>; a boolean ref flips first and resolves the mode the page just left, which leaves the mark one toggle
+// behind. useTokenMode ticks off the DOM mutation instead.
+const tokenMode = useTokenMode();
+const colour = (t: string) => resolveMapColor(`var(${t})`);
+
+/**
+ * A unique id prefix per instance.
+ *
+ * ⚠ REQUIRED. The asset declares a gradient id, and an id is unique per DOCUMENT — fine in Mapbox, where each
+ * icon is its own document, and broken here: two of these on one page would both resolve `url(#inUse)` to the
+ * first one's stops, so a list of vehicles would show the first row's gradient on every row.
+ */
+const uid = nextUid();
+
+const artwork = computed(() => {
+  void tokenMode.value;
+  const edge = colour(props.edge);
+  const rented = RENTAL_TAKEN.includes(props.rental);
+  return paintMarkerSvg(
+    MARKER_SVG,
+    markerParams(
+      props.state,
+      {
+        body: colour(STATE_GROUP_COLOUR[STATE_GROUP[props.state]]),
+        glyph: edge,
+        edge,
+        // omitted battery → no ring, both of the outer circle's params transparent together
+        battery: props.battery ? { fill: colour(batteryRingToken(props.battery)) } : undefined,
+        dot: props.offline ? { fill: colour(OFFLINE_DOT) } : undefined,
+        inUse: rented
+          ? { from: colour(IN_USE_GRADIENT.from), to: colour(IN_USE_GRADIENT.to) }
+          : undefined,
+        locked: props.rental === RENTAL_PAUSED ? { fill: colour(LOCKED_MARK) } : undefined,
+      },
+      props.badge ? { shape: props.badge, fill: colour(props.badgeColour), edge: colour(BADGE_EDGE) } : undefined,
+      props.rental,
+    ) as Record<string, string>,
+    { inner: true, idPrefix: uid },
+  );
+});
+
+/** the accessible name — the facts in words, because the mark itself is a picture */
+const label = computed(() => {
+  const bits = [stateLabel(props.state)];
+  if (props.rental !== 'AVAILABLE') bits.push(labelOf(props.rental));
+  if (props.battery) bits.push(`battery ${labelOf(props.battery)}`);
+  if (props.offline) bits.push('offline');
+  return bits.join(', ');
+});
+</script>
+
+<template>
+  <svg
+    :width="size"
+    :height="size"
+    :viewBox="`0 0 ${manifest.size} ${manifest.size}`"
+    class="block shrink-0"
+    role="img"
+    :aria-label="label"
+    v-html="artwork"
+  />
+</template>