feat(routing): plan trips around per-waypoint times and dwell

A stop can now carry its own schedule: leave after a time, be there by a
time, an appointment that fixes both, and how long you stay. A pure solver
in @openmapx/core turns those constraints plus a leg-travel oracle into one
canonical trip schedule — arrival, departure, dwell and wait at every stop,
with violations naming the exact waypoint and shortfall.

Ground trips are served by POST /directions/schedule. A dwell-only trip
takes one provider call, mapping dwell onto Valhalla's per-location
`waiting` so the engine's own clock advances across each stop and later legs
are costed for the later hour. Any window constraint switches to explicit
leg chaining — one two-point call per leg, pinned to the instant the solver
computed — concatenated back into a single route so the map, route card and
turn-by-turn consume it unchanged. Multi-stop public transport is served by
POST /transit/plan/chain, which plans one connection per segment and hands
each segment's realtime arrival to the next.

Providers declare per-semantic support as native, emulated, approximate or
unsupported. The worst level across the semantics a request uses becomes the
response fidelity, so an OSRM-only deployment gets a correct schedule
labelled as an estimate rather than a 503. A repo-wide gate keeps those
declarations complete and internally consistent.

Dwell is deliberately excluded from route duration — it belongs to the
schedule, not the driving time. Stop-order optimisation is refused while a
window is set, because reordering could move you past an appointment.

Also moves the trip-level departure time out of DirectionsPanelContent's
local state into directionsStore. The map's independent directions query
never saw it there, so a timed trip made the panel and the map key different
cache entries and draw different routes.

Closes #308

Author: Medformatik

.changeset/transit-chain-plan.md

@@ -0,0 +1,9 @@
+---
+"@openmapx/core": minor
+---
+
+Add the chained transit-plan client surface: `postTransitChainPlan`,
+`useTransitChainPlan` and `transitChainQueryKey` against the new
+`POST /transit/plan/chain` endpoint, which plans a multi-stop public-transport
+trip around per-waypoint time windows and dwell, plus the `ChainedTripPlan`
+types that describe its result.

.changeset/waypoint-schedule-model.md

@@ -0,0 +1,12 @@
+---
+"@openmapx/core": minor
+---
+
+Add the per-waypoint schedule model and solver: `WaypointSchedule` constraints
+on `Waypoint`, `TemporalCapabilities` for declaring provider support,
+`resolveScheduleConstraints` for turning wall clocks into validated instants,
+`composeSchedule` for the canonical `TripSchedule`, and `planScheduledTrip` for
+driving a per-leg travel oracle. Also adds `RoutingOptions.dwellSeconds`, the
+`isoWithOffsetInZone` timezone helper, and the scheduled-directions client
+surface (`ScheduleDirectionsRequest`, `ScheduledDirectionsResult`,
+`postScheduledDirections`) against the new `POST /directions/schedule` endpoint.

.changeset/waypoint-schedule-web.md

@@ -0,0 +1,9 @@
+---
+"@openmapx/core": minor
+---
+
+Move the directions trip time into `directionsStore` (`timeMode` / `tripTime`)
+so every consumer of the directions cache builds the same request, and add
+per-waypoint schedule state (`setWaypointSchedule`, `applyWaypointOrder`,
+`hasScheduleConstraints`) plus the `useScheduledDirections` query hook.
+`RouteSharePayload` gains optional versioned per-waypoint schedules.

apps/api/openapi.json

@@ -4402,6 +4402,23 @@
         "x-openmapx-source": "integrations/routing/index.ts"
       }
     },
+    "/api/integrations/routing/directions/schedule": {
+      "post": {
+        "operationId": "postApiIntegrationsRoutingDirectionsSchedule",
+        "responses": {
+          "default": {
+            "description": "Integration response"
+          }
+        },
+        "summary": "POST /directions/schedule (routing)",
+        "tags": [
+          "integrations"
+        ],
+        "x-openmapx-auth": "public",
+        "x-openmapx-integration": "routing",
+        "x-openmapx-source": "integrations/routing/index.ts"
+      }
+    },
     "/api/integrations/routing/match": {
       "post": {
         "operationId": "postApiIntegrationsRoutingMatch",
@@ -4851,6 +4868,23 @@
         "x-openmapx-source": "integrations/transit/index.ts"
       }
     },
+    "/api/integrations/transit/plan/chain": {
+      "post": {
+        "operationId": "postApiIntegrationsTransitPlanChain",
+        "responses": {
+          "default": {
+            "description": "Integration response"
+          }
+        },
+        "summary": "POST /plan/chain (transit)",
+        "tags": [
+          "integrations"
+        ],
+        "x-openmapx-auth": "public",
+        "x-openmapx-integration": "transit",
+        "x-openmapx-source": "integrations/transit/index.ts"
+      }
+    },
     "/api/integrations/transit/plan/refresh": {
       "post": {
         "operationId": "postApiIntegrationsTransitPlanRefresh",

apps/api/src/services/__tests__/share-links.test.ts

@@ -195,3 +195,64 @@ describe("toOwnerShare", () => {
     expect(JSON.stringify(owner)).not.toMatch(/HASH|user-1|snapshot/);
   });
 });
+
+describe("validateRouteShare with per-waypoint schedules", () => {
+  it("accepts an aligned schedules array and records the version", () => {
+    const parsed = validateRouteShare({
+      ...ROUTE,
+      schedules: [
+        null,
+        { arriveBy: "2026-09-01T14:00", dwellSeconds: 1800, timeZone: "Europe/Berlin" },
+      ],
+    });
+    expect(parsed?.scheduleVersion).toBe(1);
+    expect(parsed?.schedules).toEqual([
+      null,
+      { arriveBy: "2026-09-01T14:00", dwellSeconds: 1800, timeZone: "Europe/Berlin" },
+    ]);
+  });
+
+  it("omits the schedules entirely when every entry is unconstrained", () => {
+    const parsed = validateRouteShare({ ...ROUTE, schedules: [null, null] });
+    expect(parsed?.schedules).toBeUndefined();
+    expect(parsed?.scheduleVersion).toBeUndefined();
+  });
+
+  it("rejects a schedules array that does not align with the waypoints", () => {
+    expect(validateRouteShare({ ...ROUTE, schedules: [null] })).toBeNull();
+  });
+
+  it("rejects a malformed wall clock", () => {
+    expect(
+      validateRouteShare({ ...ROUTE, schedules: [null, { arriveBy: "tomorrow" }] }),
+    ).toBeNull();
+  });
+
+  it("rejects an unrecognized time zone", () => {
+    expect(
+      validateRouteShare({ ...ROUTE, schedules: [null, { timeZone: "Not/AZone" }] }),
+    ).toBeNull();
+  });
+
+  it("rejects an out-of-range or fractional dwell", () => {
+    expect(
+      validateRouteShare({ ...ROUTE, schedules: [null, { dwellSeconds: 100_000 }] }),
+    ).toBeNull();
+    expect(validateRouteShare({ ...ROUTE, schedules: [null, { dwellSeconds: 90.5 }] })).toBeNull();
+    expect(validateRouteShare({ ...ROUTE, schedules: [null, { dwellSeconds: -1 }] })).toBeNull();
+  });
+
+  it("rejects an unknown schedule field", () => {
+    expect(validateRouteShare({ ...ROUTE, schedules: [null, { leaveWhenever: true }] })).toBeNull();
+  });
+
+  it("rejects an unknown schedule version", () => {
+    expect(
+      validateRouteShare({ ...ROUTE, scheduleVersion: 2, schedules: [null, null] }),
+    ).toBeNull();
+  });
+
+  it("leaves an ordinary payload untouched", () => {
+    expect(validateRouteShare(ROUTE)).toEqual(ROUTE);
+  });
+});

apps/api/src/services/__tests__/temporal-capability-conformance.test.ts

@@ -0,0 +1,110 @@
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { TemporalCapabilities, TemporalSupport } from "@openmapx/core";
+import { createMockIntegrationContext } from "@openmapx/integration-framework/testing";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INTEGRATIONS_DIR = resolve(__dirname, "../../../../../integrations");
+
+const SEMANTICS: (keyof TemporalCapabilities)[] = [
+  "tripDepartAt",
+  "tripArriveBy",
+  "dwell",
+  "waypointDepartAfter",
+  "waypointArriveBy",
+  "timeDependentTravel",
+];
+const LEVELS: TemporalSupport[] = ["native", "emulated", "approximate", "unsupported"];
+
+function backendIntegrationDirs(): string[] {
+  if (!existsSync(INTEGRATIONS_DIR)) return [];
+  return readdirSync(INTEGRATIONS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("_"))
+    .map((entry) => entry.name)
+    .filter((name) => existsSync(join(INTEGRATIONS_DIR, name, "index.ts")));
+}
+
+function assertComplete(label: string, temporal: Partial<TemporalCapabilities>): void {
+  for (const semantic of SEMANTICS) {
+    const level = temporal[semantic];
+    expect(
+      LEVELS.includes(level as TemporalSupport),
+      `${label}: temporal.${semantic} must be one of ${LEVELS.join(", ")}`,
+    ).toBe(true);
+  }
+  // Claiming a time-dependent semantic while admitting travel time is not
+  // time-dependent is self-contradictory, and would label estimated wall clocks
+  // as "exact" fidelity.
+  if (temporal.timeDependentTravel === "unsupported") {
+    for (const semantic of SEMANTICS) {
+      if (semantic === "timeDependentTravel") continue;
+      expect(
+        temporal[semantic],
+        `${label}: temporal.${semantic} cannot be "native" while travel time ignores the departure instant`,
+      ).not.toBe("native");
+    }
+  }
+}
+
+/**
+ * A partial `temporal` block is worse than none: the schedule planner reads
+ * every semantic, and a missing key becomes `undefined` rather than falling back
+ * to the documented default. This drives each integration's real `setup()`
+ * through a capturing mock context and checks whatever it registers.
+ */
+describe("Temporal capability conformance", () => {
+  const dirs = backendIntegrationDirs();
+
+  beforeAll(() => {
+    vi.stubGlobal("fetch", () =>
+      Promise.reject(new Error("network disabled in temporal capability conformance test")),
+    );
+  });
+  afterAll(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("finds backend integrations to check", () => {
+    expect(dirs.length).toBeGreaterThan(0);
+  });
+
+  it("checks at least one real declaration", async () => {
+    const ctx = createMockIntegrationContext({ id: "routing-valhalla" });
+    const mod = await import(
+      pathToFileURL(join(INTEGRATIONS_DIR, "routing-valhalla", "index.ts")).href
+    );
+    await mod.setup?.(ctx);
+    const declared = ctx.registered.routing.filter(
+      (provider) => (provider as { temporal?: TemporalCapabilities }).temporal !== undefined,
+    );
+    expect(declared.length).toBeGreaterThan(0);
+  });
+
+  for (const dir of dirs) {
+    it(`${dir}: declared temporal capabilities are complete and consistent`, async () => {
+      const ctx = createMockIntegrationContext({ id: dir });
+      const mod = await import(pathToFileURL(join(INTEGRATIONS_DIR, dir, "index.ts")).href);
+      if (typeof mod.setup !== "function") return;
+      try {
+        await mod.setup(ctx);
+      } catch {
+        // Tolerated: setup() may require real config/services. Assert on what
+        // registered before the throw.
+      }
+
+      for (const provider of ctx.registered.routing) {
+        const temporal = (provider as { temporal?: Partial<TemporalCapabilities> }).temporal;
+        if (!temporal) continue;
+        assertComplete(`${dir}/${(provider as { id?: string }).id ?? "routing"}`, temporal);
+      }
+
+      for (const provider of ctx.registered.transit) {
+        const temporal = provider.capabilities.planningFeatures?.temporal;
+        if (!temporal) continue;
+        assertComplete(`${dir}/${provider.id}`, temporal);
+      }
+    });
+  }
+});

apps/api/src/services/share-links.ts

@@ -21,12 +21,26 @@ export interface RouteShareWaypoint {
   label?: string;
 }
 
+/** Mirrors `WaypointSchedule` in `@openmapx/core`; kept structural so this
+ * service does not depend on the web package's type graph. */
+export interface ShareWaypointSchedule {
+  departAfter?: string;
+  arriveBy?: string;
+  fixedAt?: string;
+  dwellSeconds?: number;
+  timeZone?: string;
+}
+
 export interface RouteSharePayload {
   waypoints: RouteShareWaypoint[];
   mode: RouteShareMode;
   avoidHighways?: boolean;
   avoidTolls?: boolean;
   avoidFerries?: boolean;
+  /** Bumped when the schedule encoding changes; readers reject an unknown value. */
+  scheduleVersion?: 1;
+  /** Per-waypoint constraints, aligned to `waypoints`. */
+  schedules?: (ShareWaypointSchedule | null)[];
 }
 
 export interface StoredListSnapshot {
@@ -70,6 +84,52 @@ export function isExpired(row: { expiresAt: Date | null }, now: Date): boolean {
   return row.expiresAt !== null && row.expiresAt.getTime() <= now.getTime();
 }
 
+const SHARE_WALL_CLOCK = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
+const MAX_SHARE_DWELL_SECONDS = 86_400;
+
+/**
+ * `undefined` means "reject the whole payload"; `null` means "this waypoint is
+ * unconstrained". A malformed schedule is never trimmed away — a share link
+ * that silently dropped an appointment would be worse than no link.
+ */
+function validSchedule(value: unknown): ShareWaypointSchedule | null | undefined {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return undefined;
+  const source = value as Record<string, unknown>;
+  const known = new Set(["departAfter", "arriveBy", "fixedAt", "dwellSeconds", "timeZone"]);
+  if (Object.keys(source).some((key) => !known.has(key))) return undefined;
+
+  const schedule: ShareWaypointSchedule = {};
+  for (const field of ["departAfter", "arriveBy", "fixedAt"] as const) {
+    const raw = source[field];
+    if (raw === undefined) continue;
+    if (typeof raw !== "string" || !SHARE_WALL_CLOCK.test(raw)) return undefined;
+    schedule[field] = raw;
+  }
+  if (source.timeZone !== undefined) {
+    if (typeof source.timeZone !== "string") return undefined;
+    try {
+      new Intl.DateTimeFormat("en-US", { timeZone: source.timeZone });
+    } catch {
+      return undefined;
+    }
+    schedule.timeZone = source.timeZone;
+  }
+  if (source.dwellSeconds !== undefined) {
+    const dwell = source.dwellSeconds;
+    if (
+      typeof dwell !== "number" ||
+      !Number.isInteger(dwell) ||
+      dwell < 0 ||
+      dwell > MAX_SHARE_DWELL_SECONDS
+    ) {
+      return undefined;
+    }
+    schedule.dwellSeconds = dwell;
+  }
+  return Object.keys(schedule).length > 0 ? schedule : null;
+}
+
 function validWaypoint(value: unknown): RouteShareWaypoint | null {
   if (typeof value !== "object" || value === null) return null;
   const { lat, lng, label } = value as Record<string, unknown>;
@@ -88,10 +148,8 @@ function validWaypoint(value: unknown): RouteShareWaypoint | null {
  */
 export function validateRouteShare(input: unknown): RouteSharePayload | null {
   if (typeof input !== "object" || input === null) return null;
-  const { waypoints, mode, avoidHighways, avoidTolls, avoidFerries } = input as Record<
-    string,
-    unknown
-  >;
+  const { waypoints, mode, avoidHighways, avoidTolls, avoidFerries, scheduleVersion, schedules } =
+    input as Record<string, unknown>;
   if (!ROUTE_SHARE_MODES.includes(mode as RouteShareMode)) return null;
   if (!Array.isArray(waypoints) || waypoints.length < 2 || waypoints.length > MAX_WAYPOINTS) {
     return null;
@@ -109,6 +167,21 @@ export function validateRouteShare(input: unknown): RouteSharePayload | null {
   if (avoidHighways !== undefined) payload.avoidHighways = avoidHighways as boolean;
   if (avoidTolls !== undefined) payload.avoidTolls = avoidTolls as boolean;
   if (avoidFerries !== undefined) payload.avoidFerries = avoidFerries as boolean;
+
+  if (scheduleVersion !== undefined && scheduleVersion !== 1) return null;
+  if (schedules !== undefined) {
+    if (!Array.isArray(schedules) || schedules.length !== parsed.length) return null;
+    const parsedSchedules: (ShareWaypointSchedule | null)[] = [];
+    for (const candidate of schedules) {
+      const schedule = validSchedule(candidate);
+      if (schedule === undefined) return null;
+      parsedSchedules.push(schedule);
+    }
+    if (parsedSchedules.some((schedule) => schedule !== null)) {
+      payload.scheduleVersion = 1;
+      payload.schedules = parsedSchedules;
+    }
+  }
   return payload;
 }