@12-apps/routing 0.0.0-stage → 1.1.0

package/src/providers/google.ts

@@ -0,0 +1,85 @@
+/**
+ * Google Routes API (`directions/v2:computeRoutes`).
+ *
+ * **Licence note for hosts:** Google's Maps Platform terms do not allow
+ * content from its services (this route line included) to be displayed on a
+ * non-Google map. A host that draws with `RouteMap` over an OpenStreetMap
+ * basemap must not list this provider; it exists for hosts that render on a
+ * Google basemap, or that use only the durations.
+ */
+
+import { decodePolyline } from "../core/geo";
+import type { ProviderOutcome, RoutingProvider } from "../core/provider";
+import type { LngLat, RouteLeg, RouteRequest } from "../core/types";
+
+import { fetchJson, legsOf, numberOr, routeOutcome, trimBase } from "./http";
+
+export interface GoogleRoutesOptions {
+  apiKey: string | undefined;
+  /** `TWO_WHEELER` (default) or `DRIVE`. */
+  travelMode?: "TWO_WHEELER" | "DRIVE";
+  /** Ask for a traffic-aware duration (billed at the Pro tier). */
+  trafficAware?: boolean;
+  baseUrl?: string;
+}
+
+const DEFAULT_BASE_URL = "https://routes.googleapis.com";
+
+interface GoogleLeg {
+  distanceMeters?: unknown;
+  duration?: unknown;
+}
+
+interface GoogleBody {
+  routes?: { polyline?: { encodedPolyline?: unknown }; legs?: GoogleLeg[] }[];
+}
+
+const waypoint = (point: LngLat) => ({ location: { latLng: { latitude: point.lat, longitude: point.lng } } });
+
+function requestBody(request: RouteRequest, options: GoogleRoutesOptions): string {
+  const last = request.returnTo ?? request.stops[request.stops.length - 1]!;
+  const middle = request.returnTo ? request.stops : request.stops.slice(0, -1);
+  return JSON.stringify({
+    origin: waypoint(request.origin),
+    destination: waypoint(last),
+    intermediates: middle.map(waypoint),
+    travelMode: options.travelMode ?? "TWO_WHEELER",
+    ...(options.trafficAware ? { routingPreference: "TRAFFIC_AWARE" } : {}),
+  });
+}
+
+export function googleRoutesProvider(options: GoogleRoutesOptions): RoutingProvider {
+  const base = trimBase(options.baseUrl ?? DEFAULT_BASE_URL);
+  return {
+    name: "google-routes",
+    async route(request, { fetch, signal }): Promise<ProviderOutcome> {
+      if (!options.apiKey) return { ok: false, kind: "unconfigured" };
+      const answer = await fetchJson({
+        fetch,
+        signal,
+        url: `${base}/directions/v2:computeRoutes`,
+        init: {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-goog-api-key": options.apiKey,
+            "x-goog-fieldmask": "routes.polyline.encodedPolyline,routes.legs.distanceMeters,routes.legs.duration",
+          },
+          body: requestBody(request, options),
+        },
+      });
+      if (!answer.ok) return answer;
+      const route = (answer.body as GoogleBody).routes?.[0];
+      if (!route) return { ok: false, kind: "no-route" };
+      const encoded = route.polyline?.encodedPolyline;
+      return routeOutcome(typeof encoded === "string" ? decodePolyline(encoded) : null, legsOf(route.legs, legOf));
+    },
+  };
+}
+
+/** `duration` is a protobuf Duration string, `"123s"` or `"12.5s"`. */
+function legOf(leg: GoogleLeg): RouteLeg | null {
+  const distanceM = numberOr(leg.distanceMeters, 0);
+  const match = typeof leg.duration === "string" ? /^(\d+(?:\.\d+)?)s$/.exec(leg.duration) : null;
+  return distanceM === null || !match ? null : { distanceM, durationS: Number(match[1]) };
+}

package/src/providers/http.ts

@@ -0,0 +1,90 @@
+/**
+ * The one HTTP step every adapter shares: call, classify the failure, parse
+ * JSON. An adapter only knows its URL, its body and how to read its answer.
+ */
+
+import { failureOfResponse, failureOfThrown, type ProviderOutcome } from "../core/provider";
+import type { Position, RouteLeg } from "../core/types";
+
+type Failure = Extract<ProviderOutcome, { ok: false }>;
+
+interface JsonCall {
+  fetch: typeof fetch;
+  signal: AbortSignal;
+  url: string;
+  init?: RequestInit;
+  /**
+   * Whether a non-2xx answer means "there is no route between these points"
+   * rather than a failed request — read from the status AND the error body,
+   * because services reuse a generic status for it (OSRM answers 400).
+   */
+  isNoRoute?: (status: number, body: unknown) => boolean;
+}
+
+export async function fetchJson(call: JsonCall): Promise<{ ok: true; body: unknown } | Failure> {
+  let response: Response;
+  try {
+    response = await call.fetch(call.url, { ...call.init, signal: call.signal });
+  } catch (error) {
+    return failureOfThrown(error, call.signal) as Failure;
+  }
+  if (!response.ok && call.isNoRoute) {
+    const text = await response.text().catch(() => "");
+    if (call.isNoRoute(response.status, parseJson(text))) return { ok: false, kind: "no-route", status: response.status };
+    return { ok: false, kind: "http", status: response.status, detail: text.slice(0, 200) };
+  }
+  const failed = await failureOfResponse(response);
+  if (failed) return failed as Failure;
+  try {
+    return { ok: true, body: (await response.json()) as unknown };
+  } catch (error) {
+    // An abort while the body streams is the planner's timeout, not a bad body.
+    return call.signal.aborted ? (failureOfThrown(error, call.signal) as Failure) : { ok: false, kind: "body" };
+  }
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+/** `[lng, lat][]` from an untrusted value, or `null`. */
+export function positionsOf(value: unknown): Position[] | null {
+  if (!Array.isArray(value)) return null;
+  const out: Position[] = [];
+  for (const item of value) {
+    if (!Array.isArray(item) || typeof item[0] !== "number" || typeof item[1] !== "number") return null;
+    out.push([item[0], item[1]]);
+  }
+  return out;
+}
+
+/** Every leg read, or `null` when any one is unreadable. */
+export function legsOf<T>(items: readonly T[] | undefined, read: (item: T) => RouteLeg | null): RouteLeg[] | null {
+  if (!items) return null;
+  const legs = items.map(read);
+  return legs.every((leg): leg is RouteLeg => leg !== null) ? legs : null;
+}
+
+/** The success outcome, or an unreadable-body failure when either part is missing. */
+export function routeOutcome(geometry: Position[] | null, legs: RouteLeg[] | null): ProviderOutcome {
+  return geometry && legs ? { ok: true, geometry, legs } : { ok: false, kind: "body" };
+}
+
+/** A number, with a missing value read as `fallback` (services omit zero-length legs). */
+export const numberOr = (value: unknown, fallback: number): number | null =>
+  value === undefined ? fallback : typeof value === "number" ? value : null;
+
+/**
+ * A base URL without its trailing slashes. A loop rather than `/\/+$/`: that
+ * pattern backtracks polynomially on a long run of slashes, and a base URL is
+ * host config this package does not control.
+ */
+export function trimBase(url: string): string {
+  let end = url.length;
+  while (end > 0 && url[end - 1] === "/") end -= 1;
+  return url.slice(0, end);
+}

package/src/providers/openrouteservice.ts

@@ -0,0 +1,71 @@
+/**
+ * openrouteservice (OpenStreetMap data, the same map the default basemap
+ * draws). `POST /v2/directions/{profile}/geojson` with every waypoint in one
+ * call; the answer's single feature carries the line and one segment per leg.
+ */
+
+import { toPosition } from "../core/geo";
+import { waypointsOf, type ProviderOutcome, type RoutingProvider } from "../core/provider";
+import type { RouteLeg } from "../core/types";
+
+import { fetchJson, legsOf, numberOr, positionsOf, routeOutcome, trimBase } from "./http";
+
+export interface OpenRouteServiceOptions {
+  /** The account's API key. Empty/absent = every attempt is `unconfigured`. */
+  apiKey: string | undefined;
+  /** ORS profile. `driving-car` is the closest public profile to a motorbike. */
+  profile?: string;
+  /** Override for a self-hosted instance. */
+  baseUrl?: string;
+}
+
+const DEFAULT_BASE_URL = "https://api.openrouteservice.org";
+
+interface OrsSegment {
+  distance?: unknown;
+  duration?: unknown;
+}
+
+interface OrsBody {
+  features?: { geometry?: { coordinates?: unknown }; properties?: { segments?: OrsSegment[] } }[];
+}
+
+export function openRouteServiceProvider(options: OpenRouteServiceOptions): RoutingProvider {
+  const base = trimBase(options.baseUrl ?? DEFAULT_BASE_URL);
+  const profile = options.profile ?? "driving-car";
+  return {
+    name: "openrouteservice",
+    async route(request, { fetch, signal }): Promise<ProviderOutcome> {
+      if (!options.apiKey) return { ok: false, kind: "unconfigured" };
+      const answer = await fetchJson({
+        fetch,
+        signal,
+        url: `${base}/v2/directions/${encodeURIComponent(profile)}/geojson`,
+        isNoRoute: orsNoRoute,
+        init: {
+          method: "POST",
+          headers: { authorization: options.apiKey, "content-type": "application/json", accept: "application/geo+json" },
+          body: JSON.stringify({ coordinates: waypointsOf(request).map(toPosition) }),
+        },
+      });
+      if (!answer.ok) return answer;
+      const feature = (answer.body as OrsBody).features?.[0];
+      return routeOutcome(positionsOf(feature?.geometry?.coordinates), legsOf(feature?.properties?.segments, legOf));
+    },
+  };
+}
+
+/**
+ * ORS answers "no route" (2009) and "no routable point near a waypoint" (2010)
+ * with 404 — the same status as a wrong profile or URL, so the body decides.
+ */
+function orsNoRoute(status: number, body: unknown): boolean {
+  const code = (body as { error?: { code?: unknown } } | null)?.error?.code;
+  return status === 404 && (code === 2009 || code === 2010);
+}
+
+function legOf(segment: OrsSegment): RouteLeg | null {
+  const distanceM = numberOr(segment.distance, 0);
+  const durationS = numberOr(segment.duration, 0);
+  return distanceM === null || durationS === null ? null : { distanceM, durationS };
+}

package/src/providers/osrm.ts

@@ -0,0 +1,58 @@
+/**
+ * OSRM (`/route/v1/{profile}/{coords}`), self-hosted or a public instance.
+ * The public demo server is for testing only — a host that lists it in
+ * production should expect to land on the fallback when it rate-limits.
+ */
+
+import { waypointsOf, type ProviderOutcome, type RoutingProvider } from "../core/provider";
+import type { RouteLeg } from "../core/types";
+
+import { fetchJson, legsOf, positionsOf, routeOutcome, trimBase } from "./http";
+
+export interface OsrmOptions {
+  /** e.g. `https://osrm.example.net`. Empty/absent = `unconfigured`. */
+  baseUrl: string | undefined;
+  /** OSRM profile segment, `driving` by default. */
+  profile?: string;
+}
+
+interface OsrmLeg {
+  distance?: unknown;
+  duration?: unknown;
+}
+
+interface OsrmBody {
+  code?: unknown;
+  routes?: { geometry?: { coordinates?: unknown }; legs?: OsrmLeg[] }[];
+}
+
+export function osrmProvider(options: OsrmOptions): RoutingProvider {
+  return {
+    name: "osrm",
+    async route(request, { fetch, signal }): Promise<ProviderOutcome> {
+      if (!options.baseUrl) return { ok: false, kind: "unconfigured" };
+      const coords = waypointsOf(request)
+        .map((point) => `${point.lng},${point.lat}`)
+        .join(";");
+      const profile = encodeURIComponent(options.profile ?? "driving");
+      const url = `${trimBase(options.baseUrl)}/route/v1/${profile}/${coords}?overview=full&geometries=geojson&steps=false`;
+      const answer = await fetchJson({ fetch, signal, url, init: { headers: { accept: "application/json" } }, isNoRoute: osrmNoRoute });
+      if (!answer.ok) return answer;
+      const body = answer.body as OsrmBody;
+      if (body.code === "NoRoute") return { ok: false, kind: "no-route" };
+      if (body.code !== "Ok") return { ok: false, kind: "body" };
+      const route = body.routes?.[0];
+      return routeOutcome(positionsOf(route?.geometry?.coordinates), legsOf(route?.legs, legOf));
+    },
+  };
+}
+
+/** OSRM answers an impossible route with HTTP 400 and a `code` in the body. */
+function osrmNoRoute(status: number, body: unknown): boolean {
+  const code = (body as { code?: unknown } | null)?.code;
+  return status === 400 && (code === "NoRoute" || code === "NoSegment");
+}
+
+function legOf(leg: OsrmLeg): RouteLeg | null {
+  return typeof leg.distance === "number" && typeof leg.duration === "number" ? { distanceM: leg.distance, durationS: leg.duration } : null;
+}

package/src/react/copy.ts

@@ -0,0 +1,24 @@
+/**
+ * Every word the map draws. Required host config — there are no defaults in
+ * the component; the named packs (`./pt-BR`, `./en-US`, `./locales`) are what a
+ * host passes when it has no reason to say anything else.
+ */
+
+export interface RouteMapCopy {
+  /** Zoom-in control's accessible name. */
+  zoomIn: string;
+  /** Zoom-out control's accessible name. */
+  zoomOut: string;
+  /** Fit-everything control's accessible name. */
+  fitAll: string;
+  /** The map area's own accessible name. */
+  mapLabel: string;
+  /** Shown in place of the map when it cannot render (no WebGL, style failed). */
+  mapError: string;
+  /** The retry button under `mapError`. */
+  retry: string;
+  /** A group of overlapping markers, by how many it holds. */
+  group: (count: number) => string;
+  /** The basemap's required attribution line. */
+  attribution: string;
+}

package/src/react/en-US.ts

@@ -0,0 +1,12 @@
+import type { RouteMapCopy } from "./copy";
+
+export const EN_US_ROUTE_MAP_COPY: RouteMapCopy = {
+  zoomIn: "Zoom in",
+  zoomOut: "Zoom out",
+  fitAll: "Show all",
+  mapLabel: "Map",
+  mapError: "The map could not be loaded.",
+  retry: "Try again",
+  group: (count) => `${count} here — tap to choose`,
+  attribution: "© OpenFreeMap © OpenMapTiles © OpenStreetMap contributors",
+};

package/src/react/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@12-apps/routing/react` — the web host's surface:
+ * `createWebRouting(config) → { RouteMap }`. Build once per config (the wiring
+ * binder does); `RouteMap` is a component TYPE the host places wherever a
+ * route belongs.
+ */
+
+import { buildRouteMap } from "./route-map";
+import type { RouteMapConfig, RouteMapProps } from "./types";
+import type { JSX } from "react";
+
+export interface RoutingSurface {
+  RouteMap: (props: RouteMapProps) => JSX.Element;
+}
+
+export function createWebRouting(config: RouteMapConfig): RoutingSurface {
+  if (!config?.copy || !config.theme) throw new TypeError("createWebRouting: `copy` and `theme` are required");
+  return { RouteMap: buildRouteMap(config) };
+}
+
+export { DEFAULT_STYLE_URL } from "./route-map";
+export { boundsOf, groupMarkers } from "./map-geometry";
+export type { RouteMapConfig, RouteMapMarker, RouteMapPlace, RouteMapProps, RouteMapStop, RouteMapTheme } from "./types";
+export type { RouteMapCopy } from "./copy";
+export type { MapLibreLike, MapLike, MarkerLike } from "./maplibre-types";
+export { PT_BR_ROUTE_MAP_COPY } from "./pt-BR";
+export { EN_US_ROUTE_MAP_COPY } from "./en-US";
+export { ROUTE_MAP_COPY } from "./locales";

package/src/react/locales.ts

@@ -0,0 +1,12 @@
+import type { RouteMapCopy } from "./copy";
+import { EN_US_ROUTE_MAP_COPY } from "./en-US";
+import { PT_BR_ROUTE_MAP_COPY } from "./pt-BR";
+
+/** Mirrored rather than imported, so the package stays liftable into any repo. */
+type LocalePack<T> = { readonly "pt-BR": T; readonly "en-US": T };
+
+/** Both languages, keyed by tag — what a host hands its i18n resolver. */
+export const ROUTE_MAP_COPY = {
+  "pt-BR": PT_BR_ROUTE_MAP_COPY,
+  "en-US": EN_US_ROUTE_MAP_COPY,
+} as const satisfies LocalePack<RouteMapCopy>;

package/src/react/map-css.ts

@@ -0,0 +1,20 @@
+/**
+ * The few rules MapLibre's own stylesheet supplies that the map cannot work
+ * without (canvas and marker positioning). Injected once at mount rather than
+ * imported, so the package keeps `sideEffects: false` and a host needs no CSS
+ * loader for it.
+ */
+
+export const MAP_CSS_ID = "routing-map-css";
+
+export const MAP_CSS = [
+  ".maplibregl-map{position:relative;overflow:hidden;-webkit-tap-highlight-color:transparent}",
+  ".maplibregl-canvas{position:absolute;left:0;top:0}",
+  ".maplibregl-canvas-container.maplibregl-interactive{cursor:grab}",
+  ".maplibregl-marker{position:absolute;top:0;left:0;will-change:transform}",
+  // Phone-width maps keep only the fit control: pinch already zooms, and a
+  // 140 px column of buttons would sit on top of the markers.
+  ".routing-map{container-type:inline-size;container-name:routing-map}",
+  "@container routing-map (max-width: 599px){.routing-zoom{display:none!important}}",
+  ".maplibregl-ctrl-bottom-left,.maplibregl-ctrl-bottom-right,.maplibregl-ctrl-top-left,.maplibregl-ctrl-top-right{position:absolute;pointer-events:none;z-index:2}",
+].join("");

package/src/react/map-elements.ts

@@ -0,0 +1,209 @@
+/**
+ * The DOM each MapLibre marker carries. MapLibre positions plain elements, so
+ * these are built directly — real `<button>`s with accessible names where the
+ * viewer can act, an `img` role with a title where they only read.
+ */
+
+import type { RouteMapCopy } from "./copy";
+import type { RouteMapMarker, RouteMapPlace, RouteMapStop, RouteMapTheme } from "./types";
+
+const SHADOW = "0 2px 6px rgba(0,0,0,.25)";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+/** Stroke glyphs, drawn in the element's own colour (no remote asset). */
+const GLYPHS = {
+  motorbike: ["M5.5 21a3.5 3.5 0 1 0 0-7 3.5 3.5 0 0 0 0 7z", "M18.5 21a3.5 3.5 0 1 0 0-7 3.5 3.5 0 0 0 0 7z", "M15 6h3l3 6", "M5.5 17.5L9 10h6l3.5 7.5"],
+  store: ["M3 9l1-5h16l1 5", "M4 9v11h16V9", "M9 20v-6h6v6"],
+} as const;
+
+function glyph(name: keyof typeof GLYPHS): SVGElement {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  for (const [key, value] of Object.entries({ width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", "aria-hidden": "true" })) {
+    svg.setAttribute(key, value);
+  }
+  for (const d of GLYPHS[name]) {
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", d);
+    svg.appendChild(path);
+  }
+  return svg;
+}
+
+function button(ariaLabel: string, style: Partial<CSSStyleDeclaration>, onClick?: () => void): HTMLButtonElement {
+  const element = document.createElement("button");
+  element.type = "button";
+  element.setAttribute("aria-label", ariaLabel);
+  Object.assign(element.style, { cursor: onClick ? "pointer" : "default", font: "inherit" }, style);
+  if (onClick) {
+    element.addEventListener("click", (event) => {
+      event.stopPropagation();
+      onClick();
+    });
+  }
+  return element;
+}
+
+function span(text: string, style: Partial<CSSStyleDeclaration>): HTMLSpanElement {
+  const element = document.createElement("span");
+  element.textContent = text;
+  Object.assign(element.style, style);
+  return element;
+}
+
+/** Which side of its pin a marker's tag (pill and tail) is drawn on. */
+export type TagSide = "above" | "below" | "right" | "left";
+
+/** How far the tail reaches from the pill to the pin. */
+export const TAG_TAIL_PX = 9;
+
+/** Each tail's colour, so a side change can redraw it pointing elsewhere. */
+const tailColours = new WeakMap<HTMLElement, string>();
+
+/** The tail under a pill, pointing down at the pin (the `above` side). */
+function tailElement(colour: string): HTMLElement {
+  const tail = span("", { width: "0", height: "0", borderLeft: "7px solid transparent", borderRight: "7px solid transparent", borderTop: `${TAG_TAIL_PX}px solid ${colour}` });
+  tailColours.set(tail, colour);
+  return tail;
+}
+
+/**
+ * Per side: how the frame stacks pill and tail (the tail always at the edge
+ * that meets the pin), and which tail border is filled (the triangle points
+ * the opposite way) versus transparent (its two flanks).
+ */
+const SIDE_LAYOUT: Record<TagSide, { flexDirection: string; filled: Edge; flanks: readonly Edge[] }> = {
+  above: { flexDirection: "column", filled: "top", flanks: ["left", "right"] },
+  below: { flexDirection: "column-reverse", filled: "bottom", flanks: ["left", "right"] },
+  right: { flexDirection: "row-reverse", filled: "right", flanks: ["top", "bottom"] },
+  left: { flexDirection: "row", filled: "left", flanks: ["top", "bottom"] },
+};
+
+type Edge = "top" | "bottom" | "left" | "right";
+
+function tailBorder(edge: Edge, side: TagSide, colour: string): string {
+  const layout = SIDE_LAYOUT[side];
+  if (edge === layout.filled) return `${TAG_TAIL_PX}px solid ${colour}`;
+  return layout.flanks.includes(edge) ? "7px solid transparent" : "0";
+}
+
+/**
+ * Lay a marker's (or group's) tag out on `side` of its pin, in place — the
+ * element is never rebuilt, so keyboard focus survives. The caller re-offsets
+ * the MapLibre marker so the tail's tip stays on the point. `false` when the
+ * element is not a tag this module built (nothing changed).
+ */
+export function setTagSide(element: HTMLElement, side: TagSide): boolean {
+  const tail = element.children[1] as HTMLElement | undefined;
+  const colour = tail ? tailColours.get(tail) : undefined;
+  if (!tail || colour === undefined) return false;
+  element.style.flexDirection = SIDE_LAYOUT[side].flexDirection;
+  for (const edge of ["top", "bottom", "left", "right"] as const) tail.style.setProperty(`border-${edge}`, tailBorder(edge, side, colour));
+  element.dataset.tagSide = side;
+  return true;
+}
+
+/**
+ * A marker the viewer can act on is a `<button>` with `aria-pressed` (it
+ * selects); one they can only read is an `img` with a label — never an empty
+ * tab stop that does nothing.
+ */
+export function markerElement(marker: RouteMapMarker, theme: RouteMapTheme, onSelect: (() => void) | null): HTMLElement {
+  const frame = { display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "flex-end", minWidth: "44px", minHeight: "44px", zIndex: marker.emphasized ? "3" : "2" };
+  let element: HTMLElement;
+  if (onSelect) {
+    element = button(marker.ariaLabel, { ...frame, background: "none", border: "0", padding: "0" }, onSelect);
+    element.setAttribute("aria-pressed", marker.emphasized ? "true" : "false");
+  } else {
+    element = span("", frame);
+    element.setAttribute("role", "img");
+    element.setAttribute("aria-label", marker.ariaLabel);
+  }
+  const bubble = span("", {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "6px",
+    padding: marker.emphasized ? "6px 12px" : "5px 9px",
+    borderRadius: "999px",
+    fontSize: "13px",
+    fontWeight: "700",
+    whiteSpace: "nowrap",
+    color: theme.paper,
+    background: marker.color,
+    border: `2px ${marker.faded ? "dashed" : "solid"} ${theme.paper}`,
+    boxShadow: SHADOW,
+    opacity: marker.faded ? "0.75" : "1",
+  });
+  if (marker.icon) bubble.appendChild(glyph(marker.icon));
+  bubble.appendChild(document.createTextNode(marker.text));
+  element.append(bubble, tailElement(marker.color));
+  element.dataset.tagSide = "above";
+  return element;
+}
+
+/**
+ * A group of overlapping markers keeps the MARKER's shape (a pill with a
+ * tail), so it never reads as a numbered stop badge drawn nearby.
+ */
+export function groupElement(count: number, copy: RouteMapCopy, theme: RouteMapTheme, onClick: () => void): HTMLElement {
+  const frame = { display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "flex-end" };
+  const element = button(copy.group(count), { ...frame, background: "none", border: "0", padding: "0", minWidth: "44px", minHeight: "44px" }, onClick);
+  const bubble = span(`+${count}`, {
+    padding: "5px 10px",
+    borderRadius: "999px",
+    fontSize: "13px",
+    fontWeight: "700",
+    color: theme.paper,
+    background: theme.ink,
+    border: `2px solid ${theme.paper}`,
+    boxShadow: SHADOW,
+  });
+  element.append(bubble, tailElement(theme.ink));
+  element.dataset.tagSide = "above";
+  return element;
+}
+
+export function stopElement(stop: RouteMapStop, theme: RouteMapTheme): HTMLElement {
+  const fill = { done: theme.done, next: theme.next, pending: theme.pending }[stop.variant];
+  const element = span(stop.mark, {
+    width: "28px",
+    height: "28px",
+    boxSizing: "border-box",
+    borderRadius: "50%",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    fontSize: "13px",
+    fontWeight: "700",
+    background: fill,
+    color: stop.variant === "pending" ? theme.ink : theme.paper,
+    border: `2px solid ${stop.variant === "done" ? theme.paper : theme.ink}`,
+    boxShadow: SHADOW,
+    // Pins are z 2–3; an emphasised stop sits above them, the rest beneath.
+    zIndex: stop.emphasized ? "4" : "1",
+  });
+  element.setAttribute("role", "img");
+  element.setAttribute("aria-label", stop.title);
+  element.title = stop.title;
+  return element;
+}
+
+/** How far above its point a place's label sits: label (~26) + stem (46) + dot (8). */
+export const PLACE_LIFT = 80;
+
+export function placeElement(spot: RouteMapPlace, theme: RouteMapTheme, lifted = true): HTMLElement {
+  // The label rides ABOVE a pin-high stem, so a courier standing at the place
+  // (a pin anchored on the same point) never covers it. It stays UNDER the
+  // pins (z 1 against their 2–3), so the stem never crosses a pin's name, and
+  // under any host overlay; clicks pass through to whatever is beneath.
+  const element = span("", { display: "flex", flexDirection: "column", alignItems: "center", pointerEvents: "none", zIndex: "1" });
+  const label = span("", { display: "inline-flex", alignItems: "center", gap: "6px", background: theme.place, color: theme.paper, padding: "4px 10px", borderRadius: "10px", fontSize: "13px", fontWeight: "600", whiteSpace: "nowrap" });
+  if (spot.icon) label.appendChild(glyph(spot.icon));
+  label.appendChild(document.createTextNode(spot.label));
+  if (!lifted) {
+    element.append(label);
+    return element;
+  }
+  element.append(label, span("", { width: "2px", height: "46px", background: theme.place }), span("", { width: "8px", height: "8px", borderRadius: "50%", background: theme.place }));
+  return element;
+}