@12-apps/routing 0.0.0-stage → 1.0.0

package/src/react/pt-BR.ts

@@ -0,0 +1,12 @@
+import type { RouteMapCopy } from "./copy";
+
+export const PT_BR_ROUTE_MAP_COPY: RouteMapCopy = {
+  zoomIn: "Aproximar",
+  zoomOut: "Afastar",
+  fitAll: "Mostrar todos",
+  mapLabel: "Mapa",
+  mapError: "Não foi possível carregar o mapa.",
+  retry: "Tentar de novo",
+  group: (count) => `${count} aqui — toque para escolher`,
+  attribution: "© OpenFreeMap © OpenMapTiles © colaboradores do OpenStreetMap",
+};

package/src/react/route-map.tsx

@@ -0,0 +1,149 @@
+/**
+ * `RouteMap` — a geographic map that draws what the host hands it: markers
+ * (people, vehicles), places (a shop), numbered stops, a planned line (dashed)
+ * and a travelled line (solid). It fetches nothing and decides nothing: every
+ * point, word and colour is a prop or config, so the same component serves a
+ * fleet overview and a single order's card.
+ *
+ * - **Real projection.** MapLibre GL over a vector style (OpenFreeMap by
+ *   default), loaded lazily the first time a map mounts.
+ * - **The viewport is the viewer's.** It fits once, and again only when
+ *   `fitKey` changes or the fit control is pressed.
+ * - **Overlapping markers stay reachable** as one group button.
+ * - **Failure is visible, not blank**: the host's error copy and a retry.
+ */
+
+import { useRef, type CSSProperties, type JSX } from "react";
+
+import type { RouteMapCopy } from "./copy";
+import type { MapLibreLike } from "./maplibre-types";
+import type { RouteMapConfig, RouteMapProps, RouteMapTheme } from "./types";
+import { useMapInstance } from "./use-map";
+import { useOverlays, useOverlaySync } from "./use-overlays";
+
+export const DEFAULT_STYLE_URL = "https://tiles.openfreemap.org/styles/liberty";
+
+/** How long a map may take to load its style before it shows the error state. */
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+
+const defaultLoader = async (): Promise<MapLibreLike> => {
+  const lib = (await import("maplibre-gl")) as unknown as { default?: MapLibreLike } & MapLibreLike;
+  return lib.default ?? lib;
+};
+
+export function buildRouteMap(config: RouteMapConfig): (props: RouteMapProps) => JSX.Element {
+  const { copy, theme } = config;
+  const baseLoad = config.loadMapLibre ?? defaultLoader;
+  const load = async (): Promise<MapLibreLike> => {
+    const lib = await baseLoad();
+    if (config.workerUrl) lib.setWorkerUrl?.(config.workerUrl);
+    return lib;
+  };
+  const styleUrl = config.styleUrl ?? DEFAULT_STYLE_URL;
+  const readyTimeoutMs = config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+
+  return function RouteMap(props: RouteMapProps): JSX.Element {
+    const container = useRef<HTMLDivElement | null>(null);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const overlaysRef = useRef<ReturnType<typeof useOverlays> | null>(null);
+    const handle = useMapInstance({
+      load,
+      styleUrl,
+      readyTimeoutMs,
+      theme,
+      container,
+      propsRef,
+      onMoveEnd: () => overlaysRef.current?.draw(),
+      onDispose: () => overlaysRef.current?.clear(),
+    });
+    const overlays = useOverlays(handle, propsRef, copy, theme);
+    overlaysRef.current = overlays;
+    useOverlaySync(handle.status === "ready", handle, props, overlays, theme);
+
+    const height = typeof props.height === "number" ? `${props.height}px` : props.height;
+    return (
+      <div className="routing-map" data-testid={props.testId} data-state={handle.status} role="region" aria-label={copy.mapLabel} style={{ position: "relative", height, width: "100%", overflow: "hidden", borderRadius: "inherit" }}>
+        <div ref={container} style={{ position: "absolute", inset: 0 }} />
+        {handle.status === "error" ? (
+          <MapError copy={copy} theme={theme} onRetry={handle.retry} />
+        ) : (
+          <MapControls
+            copy={copy}
+            theme={theme}
+            zoom={props.controls?.zoom ?? true}
+            fit={props.controls?.fit ?? true}
+            onZoomIn={() => handle.mapRef.current?.zoomIn()}
+            onZoomOut={() => handle.mapRef.current?.zoomOut()}
+            onFit={() => {
+              overlays.fitAll();
+              propsRef.current.onFitAll?.();
+            }}
+          />
+        )}
+        {props.overlay ? <div style={{ position: "absolute", left: 12, right: 12, bottom: 28, zIndex: 2 }}>{props.overlay}</div> : null}
+        <small style={{ position: "absolute", right: 6, bottom: 4, fontSize: 10, color: theme.ink, background: theme.paper, padding: "0 4px", borderRadius: 4, zIndex: 2 }}>{copy.attribution}</small>
+      </div>
+    );
+  };
+}
+
+interface ControlsProps {
+  copy: RouteMapCopy;
+  theme: RouteMapTheme;
+  zoom: boolean;
+  fit: boolean;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onFit: () => void;
+}
+
+function MapControls({ copy, theme, zoom, fit, onZoomIn, onZoomOut, onFit }: ControlsProps): JSX.Element | null {
+  if (!zoom && !fit) return null;
+  return (
+    <div style={{ position: "absolute", top: 12, right: 12, display: "flex", flexDirection: "column", gap: 8, zIndex: 2 }}>
+      {zoom ? (
+        <>
+          <button type="button" className="routing-zoom" aria-label={copy.zoomIn} onClick={onZoomIn} style={controlStyle(theme)}>
+            +
+          </button>
+          <button type="button" className="routing-zoom" aria-label={copy.zoomOut} onClick={onZoomOut} style={controlStyle(theme)}>
+            −
+          </button>
+        </>
+      ) : null}
+      {fit ? (
+        <button type="button" aria-label={copy.fitAll} onClick={onFit} style={controlStyle(theme)}>
+          <FitIcon />
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+function MapError({ copy, theme, onRetry }: { copy: RouteMapCopy; theme: RouteMapTheme; onRetry: () => void }): JSX.Element {
+  const style: CSSProperties = { position: "absolute", inset: 0, display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center", gap: 12, background: theme.paper, color: theme.ink, textAlign: "center", padding: 16 };
+  return (
+    <div role="alert" style={style}>
+      <span>{copy.mapError}</span>
+      <button type="button" onClick={onRetry} style={{ ...controlStyle(theme), width: "auto", padding: "0 14px", fontSize: 14 }}>
+        {copy.retry}
+      </button>
+    </div>
+  );
+}
+
+function FitIcon(): JSX.Element {
+  return (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M8 3H5a2 2 0 0 0-2 2v3" />
+      <path d="M21 8V5a2 2 0 0 0-2-2h-3" />
+      <path d="M3 16v3a2 2 0 0 0 2 2h3" />
+      <path d="M16 21h3a2 2 0 0 0 2-2v-3" />
+    </svg>
+  );
+}
+
+function controlStyle(theme: RouteMapTheme): CSSProperties {
+  return { minWidth: 44, width: 44, height: 44, padding: 0, borderRadius: 10, border: `1px solid ${theme.controlBorder}`, background: theme.control, color: theme.ink, fontSize: 20, display: "flex", alignItems: "center", justifyContent: "center", cursor: "pointer" };
+}

package/src/react/types.ts

@@ -0,0 +1,100 @@
+import type { ReactNode } from "react";
+
+import type { LngLat, Position } from "../core/types";
+
+import type { RouteMapCopy } from "./copy";
+import type { MapLibreLike } from "./maplibre-types";
+
+export interface RouteMapMarker {
+  id: string;
+  position: LngLat;
+  /** What the marker reads — initials, or a name when emphasised. */
+  text: string;
+  ariaLabel: string;
+  color: string;
+  /** The selected marker: larger, on top, never grouped. */
+  emphasized?: boolean;
+  /** An old position: dashed outline, translucent. */
+  faded?: boolean;
+  /** A glyph before the text: a motorbike for a courier. */
+  icon?: "motorbike";
+  onSelect?: () => void;
+}
+
+export interface RouteMapStop {
+  id: string;
+  position: LngLat;
+  /** "✓", "2", … */
+  mark: string;
+  /** Accessible title, e.g. "Parada 2 — Av. Vilarinho, 1731". */
+  title: string;
+  variant: "done" | "next" | "pending";
+}
+
+export interface RouteMapPlace {
+  id: string;
+  position: LngLat;
+  label: string;
+  /** A glyph before the label: a shopfront for a store. */
+  icon?: "store";
+}
+
+/** Colours, from the host's theme — the component never picks one itself. */
+export interface RouteMapTheme {
+  planned: string;
+  travelled: string;
+  done: string;
+  next: string;
+  pending: string;
+  ink: string;
+  paper: string;
+  place: string;
+  control: string;
+  controlBorder: string;
+}
+
+export interface RouteMapProps {
+  markers?: readonly RouteMapMarker[];
+  stops?: readonly RouteMapStop[];
+  places?: readonly RouteMapPlace[];
+  /** The dashed line, `[lng, lat][]`. */
+  planned?: readonly Position[];
+  /** The solid line, `[lng, lat][]`. */
+  travelled?: readonly Position[];
+  /** Overrides `theme.travelled` (a status colour). */
+  travelledColor?: string;
+  /** Change it to refit the viewport to everything drawn. */
+  fitKey?: string;
+  /** CSS height of the map area. */
+  height: number | string;
+  controls?: { zoom?: boolean; fit?: boolean };
+  /** Called when the viewer presses the fit control (after it fits). */
+  onFitAll?: () => void;
+  /** Called with the ids of a pressed group of overlapping markers. */
+  onGroupSelect?: (markerIds: string[]) => void;
+  /** Rendered over the map (a legend), bottom edge. */
+  overlay?: ReactNode;
+  testId?: string;
+}
+
+export interface RouteMapConfig {
+  copy: RouteMapCopy;
+  theme: RouteMapTheme;
+  /** A MapLibre style URL. Defaults to OpenFreeMap "liberty". */
+  styleUrl?: string;
+  /**
+   * Where MapLibre's worker file is served from. MapLibre 6 ships the worker
+   * as its own module (`maplibre-gl/dist/maplibre-gl-worker.mjs`) and cannot
+   * guess its bundled URL; a Vite host passes
+   * `import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?url"`.
+   */
+  workerUrl?: string;
+  /** How to load MapLibre — swapped in tests, or for a host that preloads it. */
+  loadMapLibre?: () => Promise<MapLibreLike>;
+  /**
+   * How long the map may take to become ready (its style loaded) before it
+   * shows the error state with Retry. Default 15 000 ms. A style request that
+   * hangs fires no error, so without this the map would stay blank forever.
+   */
+  readyTimeoutMs?: number;
+}

package/src/react/use-map.ts

@@ -0,0 +1,104 @@
+/**
+ * The MapLibre instance behind one `RouteMap`: load the library lazily, build
+ * the map with both line layers, report `loading | ready | error`, and tear it
+ * down on unmount or before a retry. A failure before the first `load` (no
+ * WebGL, a library or style that fails or does not arrive within
+ * `readyTimeoutMs`, counted from mount) is `error`; a tile failing later is not.
+ * Readiness is the style's, not the tiles' (`style.load`).
+ */
+
+import { useEffect, useRef, useState, type MutableRefObject } from "react";
+
+import { MAP_CSS, MAP_CSS_ID } from "./map-css";
+import { addLines, centreOf } from "./map-geometry";
+import type { MapLibreLike, MapLike } from "./maplibre-types";
+import type { RouteMapProps, RouteMapTheme } from "./types";
+
+export type MapStatus = "loading" | "ready" | "error";
+
+export interface MapHandle {
+  mapRef: MutableRefObject<MapLike | null>;
+  libRef: MutableRefObject<MapLibreLike | null>;
+  status: MapStatus;
+  retry: () => void;
+}
+
+interface MapSetup {
+  load: () => Promise<MapLibreLike>;
+  styleUrl: string;
+  /** Not ready by then is `error`: a hung style request fires no error event. */
+  readyTimeoutMs: number;
+  theme: RouteMapTheme;
+  container: MutableRefObject<HTMLDivElement | null>;
+  propsRef: MutableRefObject<RouteMapProps>;
+  /** Called after each pan or zoom, to regroup markers. */
+  onMoveEnd: () => void;
+  /** Called before the map goes away, to drop markers. */
+  onDispose: () => void;
+}
+
+function injectCss(): void {
+  if (typeof document === "undefined" || document.getElementById(MAP_CSS_ID)) return;
+  const style = document.createElement("style");
+  style.id = MAP_CSS_ID;
+  style.textContent = MAP_CSS;
+  document.head.appendChild(style);
+}
+
+export function useMapInstance(setup: MapSetup): MapHandle {
+  const mapRef = useRef<MapLike | null>(null);
+  const libRef = useRef<MapLibreLike | null>(null);
+  const setupRef = useRef(setup);
+  setupRef.current = setup;
+  const [status, setStatus] = useState<MapStatus>("loading");
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    injectCss();
+    let disposed = false;
+    let ready = false;
+    setStatus("loading");
+    const current = setupRef.current;
+    // From the START, not from when the library arrives: a library chunk that
+    // never finishes downloading must reach the error state too.
+    const readyTimer = setTimeout(() => {
+      if (!ready && !disposed) setStatus("error");
+    }, current.readyTimeoutMs);
+    void current
+      .load()
+      .then((lib) => {
+        if (disposed || !current.container.current) return;
+        libRef.current = lib;
+        const map = new lib.Map({ container: current.container.current, style: current.styleUrl, attributionControl: false, center: centreOf(current.propsRef.current), zoom: 13 });
+        mapRef.current = map;
+        map.on("error", () => {
+          if (!ready && !disposed) setStatus("error");
+        });
+        // Ready as soon as the STYLE is in: sources, layers and markers need
+        // nothing more. `load` waits for every first tile too, which over a
+        // slow link can be many seconds of an empty map; it stays as a backstop.
+        const onReady = (): void => {
+          if (disposed || ready) return;
+          ready = true;
+          clearTimeout(readyTimer);
+          addLines(map, current.theme);
+          setStatus("ready");
+        };
+        map.on("style.load", onReady);
+        map.on("load", onReady);
+        map.on("moveend", () => setupRef.current.onMoveEnd());
+      })
+      .catch(() => {
+        if (!disposed) setStatus("error");
+      });
+    return () => {
+      disposed = true;
+      clearTimeout(readyTimer);
+      setupRef.current.onDispose();
+      mapRef.current?.remove();
+      mapRef.current = null;
+    };
+  }, [attempt]);
+
+  return { mapRef, libRef, status, retry: () => setAttempt((n) => n + 1) };
+}

package/src/react/use-overlays.ts

@@ -0,0 +1,162 @@
+/**
+ * Everything `RouteMap` draws on top of the basemap, kept in step with the
+ * props: the two lines, the markers (regrouped after every pan or zoom), the
+ * stops and places, and the viewport fit — once when ready, then only when
+ * `fitKey` changes or the viewer asks.
+ *
+ * ## Reconciled by key, never rebuilt
+ *
+ * Every drawn element has a key (`m:<id>`, `g:<ids>`, `s:<id>`, `p:<id>`)
+ * and a signature of what it shows. A redraw moves elements whose signature is
+ * unchanged, replaces the ones that changed and removes the ones that left —
+ * so a refresh every few seconds, a pan, or the host re-rendering with a new
+ * array never drops the keyboard focus a viewer put on a marker. Click
+ * handlers read the host's CURRENT callback by key, so a kept element never
+ * calls a stale one.
+ */
+
+import { useEffect, useRef, type MutableRefObject } from "react";
+
+import { isValidPoint } from "../core/geo";
+import type { LngLat } from "../core/types";
+
+import type { RouteMapCopy } from "./copy";
+import { groupElement, markerElement, placeElement, stopElement } from "./map-elements";
+import { boundsOf, groupMarkers, PLANNED_LAYER, pointsOf, setLine, TRAVELLED_LAYER } from "./map-geometry";
+import type { MarkerLike } from "./maplibre-types";
+import type { MapHandle } from "./use-map";
+import type { RouteMapMarker, RouteMapProps, RouteMapTheme } from "./types";
+
+interface Overlays {
+  draw: () => void;
+  clear: () => void;
+  fitAll: () => void;
+}
+
+interface Drawn {
+  marker: MarkerLike;
+  element: HTMLElement;
+  signature: string;
+}
+
+interface Wanted {
+  key: string;
+  signature: string;
+  position: LngLat;
+  anchor: "bottom" | "center";
+  build: () => HTMLElement;
+}
+
+export function useOverlays(
+  handle: Pick<MapHandle, "mapRef" | "libRef">,
+  propsRef: MutableRefObject<RouteMapProps>,
+  copy: RouteMapCopy,
+  theme: RouteMapTheme,
+): Overlays {
+  const drawn = useRef(new Map<string, Drawn>());
+  /** The current action per key, read at click time. */
+  const actions = useRef(new Map<string, () => void>());
+
+  const clear = (): void => {
+    for (const item of drawn.current.values()) item.marker.remove();
+    drawn.current.clear();
+  };
+
+  const onGroup = (group: readonly RouteMapMarker[]): void => {
+    const handler = propsRef.current.onGroupSelect;
+    if (handler) return handler(group.map((marker) => marker.id));
+    const bounds = boundsOf(group.map((marker) => marker.position));
+    if (bounds) handle.mapRef.current?.fitBounds(bounds, { padding: 64, maxZoom: 19, duration: 300 });
+  };
+
+  const wanted = (props: RouteMapProps): Wanted[] => {
+    const map = handle.mapRef.current;
+    if (!map) return [];
+    actions.current.clear();
+    const out: Wanted[] = [];
+    for (const spot of (props.places ?? []).filter((item) => isValidPoint(item.position))) {
+      out.push({ key: `p:${spot.id}`, signature: JSON.stringify([spot.label, spot.icon]), position: spot.position, anchor: "bottom", build: () => placeElement(spot, theme) });
+    }
+    for (const stop of (props.stops ?? []).filter((item) => isValidPoint(item.position))) {
+      out.push({ key: `s:${stop.id}`, signature: JSON.stringify([stop.mark, stop.title, stop.variant]), position: stop.position, anchor: "center", build: () => stopElement(stop, theme) });
+    }
+    const valid = (props.markers ?? []).filter((marker) => isValidPoint(marker.position));
+    for (const group of groupMarkers(valid, map)) out.push(group.length === 1 ? markerWanted(group[0]!) : groupWanted(group));
+    return out;
+  };
+
+  const markerWanted = (marker: RouteMapMarker): Wanted => {
+    const key = `m:${marker.id}`;
+    if (marker.onSelect) actions.current.set(key, marker.onSelect);
+    const act = marker.onSelect ? () => actions.current.get(key)?.() : null;
+    const signature = JSON.stringify([marker.text, marker.ariaLabel, marker.color, !!marker.emphasized, !!marker.faded, marker.icon, !!marker.onSelect]);
+    return { key, signature, position: marker.position, anchor: "bottom", build: () => markerElement(marker, theme, act) };
+  };
+
+  const groupWanted = (group: RouteMapMarker[]): Wanted => {
+    const key = `g:${group.map((marker) => marker.id).join(",")}`;
+    actions.current.set(key, () => onGroup(group));
+    return { key, signature: String(group.length), position: group[0]!.position, anchor: "bottom", build: () => groupElement(group.length, copy, theme, () => actions.current.get(key)?.()) };
+  };
+
+  const draw = (): void => {
+    const lib = handle.libRef.current;
+    const map = handle.mapRef.current;
+    if (lib && map) reconcile(drawn.current, wanted(propsRef.current), (element, anchor, at) => new lib.Marker({ element, anchor }).setLngLat(at).addTo(map));
+  };
+
+  const fitAll = (): void => {
+    // The control column sits on the right edge: keep fitted content clear of
+    // it, or the farthest stop lands under the fit button.
+    const controls = propsRef.current.controls;
+    const right = (controls?.zoom ?? true) || (controls?.fit ?? true) ? 76 : 40;
+    const bounds = boundsOf(pointsOf(propsRef.current));
+    if (bounds) handle.mapRef.current?.fitBounds(bounds, { padding: { top: 40, bottom: 48, left: 40, right }, maxZoom: 16, duration: 0 });
+  };
+
+  return { draw, clear, fitAll };
+}
+
+type Place = (element: HTMLElement, anchor: Wanted["anchor"], at: [number, number]) => MarkerLike;
+
+/** Remove what left, move what is unchanged, replace what changed — keeping focus. */
+function reconcile(drawn: Map<string, Drawn>, next: readonly Wanted[], place: Place): void {
+  const keep = new Set(next.map((item) => item.key));
+  for (const [key, item] of drawn) {
+    if (keep.has(key)) continue;
+    item.marker.remove();
+    drawn.delete(key);
+  }
+  for (const item of next) {
+    const at: [number, number] = [item.position.lng, item.position.lat];
+    const current = drawn.get(item.key);
+    if (current?.signature === item.signature) {
+      current.marker.setLngLat(at);
+      continue;
+    }
+    const hadFocus = !!current && current.element.contains(document.activeElement);
+    current?.marker.remove();
+    const element = item.build();
+    drawn.set(item.key, { marker: place(element, item.anchor, at), element, signature: item.signature });
+    if (hadFocus) element.focus();
+  }
+}
+
+/** Keep lines, markers and the fit in step with the props once the map is ready. */
+export function useOverlaySync(ready: boolean, handle: Pick<MapHandle, "mapRef">, props: RouteMapProps, overlays: Overlays, theme: RouteMapTheme): void {
+  useEffect(() => {
+    const map = handle.mapRef.current;
+    if (!ready || !map) return;
+    setLine(map, PLANNED_LAYER, props.planned);
+    setLine(map, TRAVELLED_LAYER, props.travelled);
+    map.setPaintProperty(TRAVELLED_LAYER, "line-color", props.travelledColor ?? theme.travelled);
+  }, [ready, props.planned, props.travelled, props.travelledColor]);
+
+  useEffect(() => {
+    if (ready) overlays.draw();
+  }, [ready, props.markers, props.stops, props.places]);
+
+  useEffect(() => {
+    if (ready) overlays.fitAll();
+  }, [ready, props.fitKey]);
+}

package/src/server/index.ts

@@ -0,0 +1,108 @@
+/**
+ * `@12-apps/routing/server` — the one thing this package exposes to a BACKEND
+ * host: `createApiRouting(config) → { routes, planRoute }`.
+ *
+ * - `planRoute` is the planner itself, for a host that plans in-process (a job
+ *   that saves a route when a trip starts): no HTTP hop, same fallback.
+ * - `routes` is one framework-neutral descriptor, `POST /route`, for a host
+ *   that lets a client ask for a route. Who may ask is the host's
+ *   `authorize` — the package has no idea what a caller is.
+ *
+ * Which services are tried, and in what order, is the provider list the host
+ * passes: swapping openrouteservice for OSRM, or adding a new adapter, is a
+ * config change here and nowhere else.
+ */
+
+import { isValidPoint } from "../core/geo";
+import { createRoutePlanner, type RoutePlanner, type RoutePlannerConfig } from "../core/planner";
+import type { LngLat, RouteRequest } from "../core/types";
+
+export interface RoutingRequest<TActor> {
+  actor: TActor;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+  body?: unknown;
+}
+
+export interface RoutingResponse {
+  status: number;
+  body: unknown;
+}
+
+export interface RoutingRoute<TActor> {
+  method: "POST";
+  path: string;
+  handle(request: RoutingRequest<TActor>): Promise<RoutingResponse>;
+}
+
+export interface RoutingServerConfig<TActor = unknown> extends RoutePlannerConfig {
+  /** Answer whether this actor may plan a route. Required: there is no default. */
+  authorize(actor: TActor): boolean | Promise<boolean>;
+  /** Upper bound on stops per request (default 25) — a provider bills per waypoint. */
+  maxStops?: number;
+}
+
+export interface RoutingApi<TActor> {
+  routes: RoutingRoute<TActor>[];
+  planRoute: RoutePlanner;
+}
+
+const DEFAULT_MAX_STOPS = 25;
+
+export function createApiRouting<TActor = unknown>(config: RoutingServerConfig<TActor>): RoutingApi<TActor> {
+  if (typeof config.authorize !== "function") throw new TypeError("createApiRouting: `authorize` is required");
+  const planRoute = createRoutePlanner(config);
+  const maxStops = config.maxStops ?? DEFAULT_MAX_STOPS;
+  const route: RoutingRoute<TActor> = {
+    method: "POST",
+    path: "/route",
+    async handle(request) {
+      if (!(await config.authorize(request.actor))) return { status: 403, body: { error: "forbidden" } };
+      const parsed = parseRouteRequest(request.body, maxStops);
+      if (!parsed.ok) return { status: 400, body: { error: parsed.error } };
+      const route = await planRoute(parsed.request);
+      // `detail` is for the host's logs (it can name an internal host); the
+      // caller gets which provider failed and how, never the raw text.
+      const failures = route.failures.map(({ provider, kind, status }) => ({ provider, kind, ...(status === undefined ? {} : { status }) }));
+      return { status: 200, body: { ...route, failures } };
+    },
+  };
+  return { routes: [route], planRoute };
+}
+
+type Parsed = { ok: true; request: RouteRequest } | { ok: false; error: string };
+
+/** A finite, non-0,0 point from an untrusted value, or `null`. */
+function pointOf(value: unknown): LngLat | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { lng, lat } = value as Record<string, unknown>;
+  if (typeof lng !== "number" || typeof lat !== "number") return null;
+  const candidate = { lng, lat };
+  return isValidPoint(candidate) ? candidate : null;
+}
+
+function stopsOf(value: unknown, maxStops: number): LngLat[] | string {
+  if (!Array.isArray(value) || value.length === 0) return "stops must be a non-empty array";
+  if (value.length > maxStops) return `at most ${maxStops} stops`;
+  const stops = value.map(pointOf);
+  return stops.every((stop): stop is LngLat => stop !== null) ? stops : "every stop must be a valid point";
+}
+
+/** Validate an untrusted body into a request; never trust a client's points. */
+export function parseRouteRequest(body: unknown, maxStops = DEFAULT_MAX_STOPS): Parsed {
+  if (typeof body !== "object" || body === null) return { ok: false, error: "body must be an object" };
+  const { origin, stops, returnTo } = body as Record<string, unknown>;
+  const from = pointOf(origin);
+  if (!from) return { ok: false, error: "origin must be a valid point" };
+  const parsedStops = stopsOf(stops, maxStops);
+  if (typeof parsedStops === "string") return { ok: false, error: parsedStops };
+  const back = returnTo === undefined || returnTo === null ? undefined : pointOf(returnTo);
+  if (back === null) return { ok: false, error: "returnTo must be a valid point" };
+  return { ok: true, request: { origin: from, stops: parsedStops, ...(back ? { returnTo: back } : {}) } };
+}
+
+export { openRouteServiceProvider, type OpenRouteServiceOptions } from "../providers/openrouteservice";
+export { osrmProvider, type OsrmOptions } from "../providers/osrm";
+export { googleRoutesProvider, type GoogleRoutesOptions } from "../providers/google";
+export { createRoutePlanner, DEFAULT_PROVIDER_TIMEOUT_MS, RouteRequestError } from "../core/planner";
+export type { RoutePlanner, RoutePlannerConfig } from "../core/planner";