@expofp/floorplan 0.0.0-experimental.cf063fc

package/dist/esm/journey/journey-context.js

@@ -0,0 +1,137 @@
+import { projectLocalToGps } from '@expofp/geometry';
+import { geoAnchors } from '../utils/geo-anchors.js';
+import { isUsableGeo } from './maps-provider.js';
+import { planJourney } from './plan-journey.js';
+const isFiniteAnchor = (anchor) => Number.isFinite(anchor?.x) &&
+    Number.isFinite(anchor?.y) &&
+    Number.isFinite(anchor?.lat) &&
+    Number.isFinite(anchor?.lng);
+/**
+ * Projects a place's plan-local target point onto the ground.
+ *
+ * Anchoring is a property of the plan, not of the individual place: a plan
+ * without usable anchors leaves every place geo-less, which is exactly the
+ * "no route available" case the planner reports.
+ */
+function toGeo(point, gpsConfig) {
+    if (!gpsConfig || !isFiniteAnchor(gpsConfig.p0) || !isFiniteAnchor(gpsConfig.p2))
+        return undefined;
+    const geo = projectLocalToGps(point, ...geoAnchors(gpsConfig));
+    return isUsableGeo(geo) ? geo : undefined;
+}
+function toJourneyPlace(place, gpsConfig) {
+    if (!place)
+        return null;
+    return {
+        id: place.id,
+        name: place.name,
+        placeKind: 'venue',
+        geo: toGeo(place.markerPoint, gpsConfig),
+        // Doors reach the planner in both spaces: plan-local for the indoor cost it
+        // ranks them by, geographic for the handoff. A door the plan cannot place
+        // on the ground is no use to a maps app, so it does not travel. Its level's
+        // layer name travels alongside, which is what turns the door into a route
+        // endpoint once a leg is walked.
+        entrances: (place.entrances ?? []).flatMap((entrance) => {
+            const geo = toGeo(entrance.point, gpsConfig);
+            return geo
+                ? [
+                    {
+                        local: entrance.point,
+                        geo,
+                        name: entrance.name,
+                        layerName: entrance.level?.layer.name,
+                    },
+                ]
+                : [];
+        }),
+    };
+}
+/**
+ * The graph's connectivity answer for the endpoint pair the app just routed.
+ *
+ * The rendered route *is* the probe: the engine reports "no path" by producing
+ * no route lines, so a fully specified route with none is the graph saying
+ * "unreachable" for exactly this pair. Reading the attempt already made keeps
+ * the answer in step with what the map shows, and costs no second search.
+ *
+ * Null until both endpoints are chosen — there is nothing to be connected yet —
+ * and until the engine has routed the pair: a route is selected before it is
+ * routed, and the lines on hand in between are the previous route's, or none
+ * at all. Read as an answer, "none" is "unreachable", and a journey starts for
+ * a pair the graph connects (#1688).
+ */
+export function readGraphConnectivity({ hasOrigin, hasDestination, routed, routeLineCount, }) {
+    if (!hasOrigin || !hasDestination || !routed)
+        return null;
+    return routeLineCount > 0 ? 'routable' : 'unreachable';
+}
+/**
+ * Apple Maps is the default only where it is the platform's own maps app.
+ * iPadOS reports a desktop-class Mac user agent, so it is told apart the one
+ * way that still works: a Mac that accepts touch.
+ */
+export function detectJourneyPlatform({ userAgent, platform, maxTouchPoints = 0, }) {
+    const isIosDevice = /iPhone|iPad|iPod/i.test(userAgent);
+    // `navigator.platform` is deprecated and reports '' in some browsers, so an
+    // empty value falls back to the user agent rather than answering "not a Mac".
+    const isIpadOs = /Mac/i.test(platform || userAgent) && maxTouchPoints > 1;
+    return { isApplePlatform: isIosDevice || isIpadOs };
+}
+/** The platform of the browser this SDK instance runs in. */
+export function currentJourneyPlatform() {
+    return detectJourneyPlatform({
+        userAgent: navigator.userAgent,
+        platform: navigator.platform,
+        maxTouchPoints: navigator.maxTouchPoints,
+    });
+}
+/**
+ * The outdoor PoI an endpoint is, as a journey place.
+ *
+ * A PoI has no doors — not none authored, none possible — so it reaches the
+ * ground the one way a place without doors ever does: its own point, projected
+ * through the plan's georeference, exactly as a venue's marker point is. A
+ * plan that cannot place it there leaves it geo-less, which the planner reports
+ * as an honest dead end rather than a broken journey.
+ *
+ * Null without a point: a PoI is a point on the ground and nothing else, so an
+ * endpoint that has none is not a place the SDK can send anyone to.
+ */
+function toOutdoorPoiPlace(endpoint, gpsConfig) {
+    const { outdoorPoi, point } = endpoint;
+    if (!outdoorPoi || !point)
+        return null;
+    return {
+        id: outdoorPoi.id,
+        name: outdoorPoi.name,
+        placeKind: 'outdoor-poi',
+        geo: toGeo(point, gpsConfig),
+    };
+}
+/**
+ * Adapts the app's venue model and georeference into a planner request, and
+ * returns what the planner decided. The one entry the UI needs; every decision
+ * still belongs to `planJourney`.
+ *
+ * Either end may be a venue or an outdoor PoI (ADR-0011). The venue is tried
+ * first: the two are mutually exclusive by layer — an `Outdoor*` layer is never
+ * a venue level — so the order is defensive rather than load-bearing.
+ */
+export function resolveJourneyPlan({ venues, gpsConfig, enabled, platform, providerOverride }, origin, destination, connectivity) {
+    const venueOfLayer = (layerName) => venues.hasVenueModel && layerName ? venues.venueOfLayer(layerName) : null;
+    const placeOf = (endpoint) => toJourneyPlace(venueOfLayer(endpoint.layerName), gpsConfig) ??
+        toOutdoorPoiPlace(endpoint, gpsConfig);
+    const originPlace = placeOf(origin);
+    return planJourney({
+        enabled,
+        connectivity,
+        origin: originPlace && { kind: origin.kind, place: originPlace },
+        originPoint: origin.point,
+        destination: placeOf(destination),
+        destinationName: destination.name,
+        destinationPoint: destination.point,
+        platform,
+        providerOverride,
+    });
+}

package/dist/esm/journey/journey-link.d.ts

@@ -0,0 +1,49 @@
+import { type JourneyLink } from '@expofp/schema';
+/**
+ * The journey deep link — how a journey changes devices. A kiosk QR encodes it,
+ * a desktop hands it to a phone, and a native host carries it through the maps
+ * round trip.
+ *
+ * The link is identifiers only (`JourneyLinkSchema`, the schema package's URL
+ * config): opening it REPLAYS the two endpoints and lets the planner recompute
+ * everything else from the plan the receiving device has now. A code printed
+ * beside a kiosk outlives plan edits, so a link carrying legs or coordinates
+ * would hand a phone yesterday's answer with today's confidence.
+ *
+ * The schema is the whole URL grammar here — no parallel mechanism: the query
+ * is the ordinary bracketed config form the rest of the SDK's URL state uses,
+ * and the kiosk anchor keeps riding along in the legacy `kiosk_*` params the
+ * QR-share pattern already smuggles.
+ */
+export type { JourneyLink };
+/** What replaying a journey deep link asks of the app. */
+export interface JourneyLinkTarget {
+    /**
+     * Show the route the link names, resolving both identifiers against the
+     * current plan. An empty `from` leaves the origin to the device — its kiosk
+     * anchor or the visitor's live position.
+     */
+    selectRoute(from: string, to: string): void;
+}
+/** The plan URL a QR encodes: the base page plus the journey's two identifiers. */
+export declare function buildJourneyLink(baseUrl: string, link: JourneyLink): string;
+/**
+ * The journey a query names, or null when it names none — including a link too
+ * damaged to act on. A visitor-edited URL must never break the load, so an
+ * unusable journey key drops out exactly like every other config key
+ * (`parseFromUrlTolerant`).
+ */
+export declare function parseJourneyLink(input: string | URL): JourneyLink | null;
+/**
+ * Replay a journey deep link — the link's two identifiers into the route the
+ * app shows — and return the link that was applied, or null when the query
+ * named none.
+ *
+ * Replaying is the whole of it: nothing about the journey travels in the URL,
+ * so the ordinary journey path re-plans from the route this leaves behind,
+ * against the plan, its places and the position of the device it runs on. That
+ * is what makes a scanned QR answer with today's plan and the scanner's own
+ * origin instead of the kiosk's week-old snapshot.
+ */
+export declare function dispatchJourneyLink(input: string | URL, target: JourneyLinkTarget): JourneyLink | null;
+//# sourceMappingURL=journey-link.d.ts.map

package/dist/esm/journey/journey-link.js

@@ -0,0 +1,35 @@
+import { parseFromUrlTolerant, toQueryString } from '@expofp/config';
+import { UrlConfigSchema } from '@expofp/schema';
+/** The plan URL a QR encodes: the base page plus the journey's two identifiers. */
+export function buildJourneyLink(baseUrl, link) {
+    const url = new URL(baseUrl);
+    url.search = toQueryString({ journey: link });
+    return url.toString();
+}
+/**
+ * The journey a query names, or null when it names none — including a link too
+ * damaged to act on. A visitor-edited URL must never break the load, so an
+ * unusable journey key drops out exactly like every other config key
+ * (`parseFromUrlTolerant`).
+ */
+export function parseJourneyLink(input) {
+    return parseFromUrlTolerant(UrlConfigSchema, input).value.journey ?? null;
+}
+/**
+ * Replay a journey deep link — the link's two identifiers into the route the
+ * app shows — and return the link that was applied, or null when the query
+ * named none.
+ *
+ * Replaying is the whole of it: nothing about the journey travels in the URL,
+ * so the ordinary journey path re-plans from the route this leaves behind,
+ * against the plan, its places and the position of the device it runs on. That
+ * is what makes a scanned QR answer with today's plan and the scanner's own
+ * origin instead of the kiosk's week-old snapshot.
+ */
+export function dispatchJourneyLink(input, target) {
+    const link = parseJourneyLink(input);
+    if (!link)
+        return null;
+    target.selectRoute(link.from ?? '', link.to);
+    return link;
+}

package/dist/esm/journey/journey-stage.d.ts

@@ -0,0 +1,35 @@
+import type { ArrivalLeg, ExitLeg, Journey, JourneyLeg } from './types.js';
+/**
+ * Where a visitor is in their journey. One stage per leg, in walking order, and
+ * a journey only has the stages its legs give it: a plan that authored no doors
+ * runs the middle one alone, which is the whole of the journey it has always
+ * been given.
+ */
+export type JourneyStage = JourneyLeg['kind'];
+/** What moves a journey on: the visitor's handoff, and their coming back. */
+export type JourneyStageEvent = 
+/** The external handoff was taken — the visitor is in the maps app now. */
+'handoff'
+/** The floor plan has the visitor's attention again. */
+ | 'return';
+/** The stages this journey actually has, in walking order. */
+export declare const journeyStages: (journey: Journey) => JourneyStage[];
+/** The stage a journey opens on: its exit leg when it has one, else the street leg. */
+export declare const initialJourneyStage: (journey: Journey) => JourneyStage;
+/** The indoor leg of a stage, or nothing — the street leg is not one. */
+export declare function indoorLegOf(journey: Journey, stage: JourneyStage): ExitLeg | ArrivalLeg | undefined;
+/**
+ * Where a journey stands after something happened to it.
+ *
+ * Taking the handoff puts the visitor on the street leg, wherever they were —
+ * they may well skip the walk to the exit and open Maps straight away.
+ *
+ * Coming back only means something on the street leg, and it is the whole point
+ * of the arrival leg: the visitor walked to the other place and put their phone
+ * away, so the floor plan they come back to owes them the walk from the door to
+ * their booth rather than the map they left. A journey with no arrival leg has
+ * nothing to move on to and stays put, and a return that arrives before any
+ * handoff — a tab switched away and back — is not progress at all.
+ */
+export declare function advanceJourneyStage(journey: Journey, stage: JourneyStage, event: JourneyStageEvent): JourneyStage;
+//# sourceMappingURL=journey-stage.d.ts.map

package/dist/esm/journey/journey-stage.js

@@ -0,0 +1,28 @@
+/** The stages this journey actually has, in walking order. */
+export const journeyStages = (journey) => journey.legs.map((leg) => leg.kind);
+/** The stage a journey opens on: its exit leg when it has one, else the street leg. */
+export const initialJourneyStage = (journey) => journeyStages(journey)[0] ?? 'external';
+/** The indoor leg of a stage, or nothing — the street leg is not one. */
+export function indoorLegOf(journey, stage) {
+    return journey.legs.find((leg) => leg.kind === stage && leg.kind !== 'external');
+}
+/**
+ * Where a journey stands after something happened to it.
+ *
+ * Taking the handoff puts the visitor on the street leg, wherever they were —
+ * they may well skip the walk to the exit and open Maps straight away.
+ *
+ * Coming back only means something on the street leg, and it is the whole point
+ * of the arrival leg: the visitor walked to the other place and put their phone
+ * away, so the floor plan they come back to owes them the walk from the door to
+ * their booth rather than the map they left. A journey with no arrival leg has
+ * nothing to move on to and stays put, and a return that arrives before any
+ * handoff — a tab switched away and back — is not progress at all.
+ */
+export function advanceJourneyStage(journey, stage, event) {
+    if (event === 'handoff')
+        return 'external';
+    if (stage !== 'external')
+        return stage;
+    return journeyStages(journey).includes('arrival') ? 'arrival' : stage;
+}

package/dist/esm/journey/maps-provider.d.ts

@@ -0,0 +1,36 @@
+import type { LatLng } from '@expofp/geometry';
+import type { JourneyPlatform, MapsProvider } from './types.js';
+/**
+ * The provider the external handoff opens.
+ *
+ * A producer override wins outright and on every platform — a partnership or a
+ * regional preference is a decision about the event, not about the device.
+ * Without one the default is the platform's own maps app, so the user lands
+ * where their taps, saved places and live navigation already are.
+ *
+ * The override is re-checked rather than trusted for its type — see
+ * `isMapsProvider` for why a typed field can still arrive unmodeled. An
+ * unrecognized one degrades to the platform default instead of building a link
+ * that opens nothing.
+ */
+export declare function resolveMapsProvider(platform: JourneyPlatform, override?: MapsProvider): MapsProvider;
+/** Whether a geographic point is usable as a handoff target. */
+export declare function isUsableGeo(geo: LatLng | undefined): geo is LatLng;
+/**
+ * The universal URL that opens directions to `destination` in `provider`,
+ * starting from `origin` when the journey knows one.
+ *
+ * An origin is passed only where it is a real place — a kiosk that stands
+ * still, a from-booth someone picked while planning — and the provider then
+ * previews the whole A-to-B street route. Left out, the provider routes from
+ * the user's real position, which is the whole point of handing a live
+ * navigation leg over. No travel-mode hint is passed either way — an authored
+ * pathway *is* the walkable case, so external legs only exist at distances
+ * where the provider's own default is the sensible start (ADR-0010).
+ *
+ * The literal comma between the coordinates is the form both providers
+ * document; percent-encoding it works too but is needlessly unlike every
+ * example a support engineer will compare against.
+ */
+export declare function buildExternalHandoffUrl(provider: MapsProvider, destination: LatLng, origin?: LatLng): string;
+//# sourceMappingURL=maps-provider.d.ts.map

package/dist/esm/journey/maps-provider.js

@@ -0,0 +1,58 @@
+import { isMapsProvider } from '@expofp/schema';
+/** Six decimals ≈ 0.11 m — finer than any anchor a plan is calibrated with. */
+const COORDINATE_DECIMALS = 6;
+/**
+ * The provider the external handoff opens.
+ *
+ * A producer override wins outright and on every platform — a partnership or a
+ * regional preference is a decision about the event, not about the device.
+ * Without one the default is the platform's own maps app, so the user lands
+ * where their taps, saved places and live navigation already are.
+ *
+ * The override is re-checked rather than trusted for its type — see
+ * `isMapsProvider` for why a typed field can still arrive unmodeled. An
+ * unrecognized one degrades to the platform default instead of building a link
+ * that opens nothing.
+ */
+export function resolveMapsProvider(platform, override) {
+    if (isMapsProvider(override))
+        return override;
+    return platform.isApplePlatform ? 'apple' : 'google';
+}
+/** Whether a geographic point is usable as a handoff target. */
+export function isUsableGeo(geo) {
+    if (!geo)
+        return false;
+    const { lat, lng } = geo;
+    return (Number.isFinite(lat) &&
+        Number.isFinite(lng) &&
+        Math.abs(lat) <= 90 &&
+        Math.abs(lng) <= 180 &&
+        // (0, 0) is the null island every unset anchor projects to — not a venue.
+        !(lat === 0 && lng === 0));
+}
+const formatCoordinate = (value) => String(Number(value.toFixed(COORDINATE_DECIMALS)));
+const formatPoint = ({ lat, lng }) => `${formatCoordinate(lat)},${formatCoordinate(lng)}`;
+/**
+ * The universal URL that opens directions to `destination` in `provider`,
+ * starting from `origin` when the journey knows one.
+ *
+ * An origin is passed only where it is a real place — a kiosk that stands
+ * still, a from-booth someone picked while planning — and the provider then
+ * previews the whole A-to-B street route. Left out, the provider routes from
+ * the user's real position, which is the whole point of handing a live
+ * navigation leg over. No travel-mode hint is passed either way — an authored
+ * pathway *is* the walkable case, so external legs only exist at distances
+ * where the provider's own default is the sensible start (ADR-0010).
+ *
+ * The literal comma between the coordinates is the form both providers
+ * document; percent-encoding it works too but is needlessly unlike every
+ * example a support engineer will compare against.
+ */
+export function buildExternalHandoffUrl(provider, destination, origin) {
+    const target = formatPoint(destination);
+    const start = isUsableGeo(origin) ? formatPoint(origin) : undefined;
+    return provider === 'apple'
+        ? `https://maps.apple.com/?${start ? `saddr=${start}&` : ''}daddr=${target}`
+        : `https://www.google.com/maps/dir/?api=1&${start ? `origin=${start}&` : ''}destination=${target}`;
+}

package/dist/esm/journey/plan-journey.d.ts

@@ -0,0 +1,37 @@
+import type { JourneyPlan, JourneyRequest } from './types.js';
+/**
+ * The journey planner seam: every cross-venue decision — whether a journey
+ * applies at all, which doors it uses, what its external leg targets, which
+ * provider URL the handoff opens, and how a journey degrades when data is
+ * missing — is made here, from plain inputs, and returned as a plain value.
+ *
+ * Connectivity is the sole trigger (ADR-0010): a graph-routable pair keeps the
+ * built-in route at any distance, and only the producer's authoring decision —
+ * pathway or no pathway — moves a pair across the line. There is deliberately
+ * no distance threshold to configure.
+ *
+ * A journey is up to three legs walked in order: out of the origin venue to its
+ * chosen exit, across the gap in the maps app, and from the destination venue's
+ * chosen entrance to the booth. Both indoor legs carry a door and nothing else
+ * — routing them is the engine's job, and a door reaches it as an ordinary
+ * route endpoint.
+ *
+ * A journey degrades with the data it is given rather than failing. A place
+ * with no authored door loses its indoor leg and hands the street leg its
+ * marker point instead of a door; a plan that authors none anywhere gets the
+ * single-leg journey it has always got. None of that is scaffolding — it is
+ * what most plans run on, permanently.
+ *
+ * An outdoor PoI takes the same path through this function without a branch of
+ * its own: it authors no doors because it has none, so the side it stands on
+ * loses its indoor leg exactly as an unauthored venue's would. Only the
+ * external leg's target kind records the difference, because only there does it
+ * matter that nothing is missing (ADR-0011).
+ *
+ * The three journey origins — live position, kiosk anchor, picked from-booth —
+ * are one concept here: the plan is identical whichever the user came in on,
+ * bar the handoff URL, which names the origin only when it is a place rather
+ * than a moving user.
+ */
+export declare function planJourney(request: JourneyRequest): JourneyPlan;
+//# sourceMappingURL=plan-journey.d.ts.map

package/dist/esm/journey/plan-journey.js

@@ -0,0 +1,176 @@
+import { haversineDistance, pointDistance } from '@expofp/geometry';
+import { buildExternalHandoffUrl, isUsableGeo, resolveMapsProvider } from './maps-provider.js';
+const placeRef = ({ id, name, placeKind }) => ({ id, name, placeKind });
+const originRef = ({ kind, place }) => ({ ...placeRef(place), kind });
+/**
+ * A plan-local point the planner can measure against, or undefined.
+ *
+ * A point that is not on the plan cannot rank anything, and a NaN cost would
+ * silently lose every comparison below rather than tie: read it as no point at
+ * all, which leaves the tie-break to decide on its own.
+ */
+const rankablePoint = (point) => point && Number.isFinite(point.x) && Number.isFinite(point.y) ? point : undefined;
+/**
+ * The door a visitor should use, chosen for them.
+ *
+ * Cost is the indoor walk the choice actually changes — from `from` to the
+ * door, in plan-local units. Straight-line, not routed: the wayfinding engine
+ * never learns what an entrance is, and asking it to rank doors would teach it
+ * (ADR-0010, contract §6.1).
+ *
+ * Flat, too: a door's level is deliberately not part of the cost. Doors are
+ * where a building meets the street, so they cluster on the ground floor, and
+ * charging a door for the storeys between it and the booth would push a journey
+ * away from the door a visitor can actually walk through. The levels a visitor
+ * climbs belong to the indoor leg, which routes them properly.
+ *
+ * Doors that tie indoors are separated by `toward` — the other end of the
+ * street leg, so the visitor leaves by the door facing the place they are
+ * heading for and walks into the one facing the place they came from. Doors
+ * that tie on both are separated by authored order, so the same plan always
+ * picks the same door. An end with no point of its own leaves every door tied
+ * on cost, which quietly makes the direction the only criterion — and that is
+ * the right answer for it too.
+ *
+ * Undefined when the place authored no door the plan can place on the ground —
+ * the permanent state of every plan that authors none.
+ */
+function chooseEntrance(place, from, toward) {
+    const rankAgainst = rankablePoint(from);
+    let chosen;
+    let chosenCost = Number.POSITIVE_INFINITY;
+    let chosenDirection = Number.POSITIVE_INFINITY;
+    for (const entrance of place.entrances ?? []) {
+        if (!isUsableGeo(entrance.geo))
+            continue;
+        const cost = rankAgainst ? pointDistance(entrance.local, rankAgainst) : 0;
+        if (cost > chosenCost)
+            continue;
+        const direction = haversineDistance(toward, entrance.geo);
+        if (cost === chosenCost && direction >= chosenDirection)
+            continue;
+        chosen = entrance;
+        chosenCost = cost;
+        chosenDirection = direction;
+    }
+    return chosen;
+}
+/**
+ * An indoor leg of a journey, or nothing when its venue authored no usable door.
+ *
+ * `venue`, not `place`: a leg only exists where a door was authored, and only a
+ * venue has doors — the narrower word is the precise one on this side.
+ */
+function indoorLeg(kind, venue, door) {
+    return door ? [{ kind, venue: placeRef(venue), door, label: door.name ?? venue.name }] : [];
+}
+/**
+ * The journey planner seam: every cross-venue decision — whether a journey
+ * applies at all, which doors it uses, what its external leg targets, which
+ * provider URL the handoff opens, and how a journey degrades when data is
+ * missing — is made here, from plain inputs, and returned as a plain value.
+ *
+ * Connectivity is the sole trigger (ADR-0010): a graph-routable pair keeps the
+ * built-in route at any distance, and only the producer's authoring decision —
+ * pathway or no pathway — moves a pair across the line. There is deliberately
+ * no distance threshold to configure.
+ *
+ * A journey is up to three legs walked in order: out of the origin venue to its
+ * chosen exit, across the gap in the maps app, and from the destination venue's
+ * chosen entrance to the booth. Both indoor legs carry a door and nothing else
+ * — routing them is the engine's job, and a door reaches it as an ordinary
+ * route endpoint.
+ *
+ * A journey degrades with the data it is given rather than failing. A place
+ * with no authored door loses its indoor leg and hands the street leg its
+ * marker point instead of a door; a plan that authors none anywhere gets the
+ * single-leg journey it has always got. None of that is scaffolding — it is
+ * what most plans run on, permanently.
+ *
+ * An outdoor PoI takes the same path through this function without a branch of
+ * its own: it authors no doors because it has none, so the side it stands on
+ * loses its indoor leg exactly as an unauthored venue's would. Only the
+ * external leg's target kind records the difference, because only there does it
+ * matter that nothing is missing (ADR-0011).
+ *
+ * The three journey origins — live position, kiosk anchor, picked from-booth —
+ * are one concept here: the plan is identical whichever the user came in on,
+ * bar the handoff URL, which names the origin only when it is a place rather
+ * than a moving user.
+ */
+export function planJourney(request) {
+    const { enabled, connectivity, origin, originPoint, destination, destinationName, destinationPoint, platform, providerOverride, } = request;
+    // The flag decides first: off means no behavioral change anywhere.
+    if (!enabled)
+        return { outcome: 'none', reason: 'disabled' };
+    if (connectivity === 'routable')
+        return { outcome: 'none', reason: 'graph-connected' };
+    if (!origin || !destination)
+        return { outcome: 'none', reason: 'place-unknown' };
+    // Kind as well as id: a venue id and a booth slug are both slug-shaped and
+    // are drawn from different namespaces, so `id` alone would occasionally
+    // report two genuinely different places as one and swallow the journey.
+    if (origin.place.id === destination.id && origin.place.placeKind === destination.placeKind) {
+        return { outcome: 'none', reason: 'same-place' };
+    }
+    // A place we cannot put on the ground cannot be handed to a maps app; say so
+    // plainly rather than presenting a journey that goes nowhere.
+    if (!isUsableGeo(origin.place.geo) || !isUsableGeo(destination.geo)) {
+        return { outcome: 'no-route', reason: 'place-not-geo-anchored' };
+    }
+    const provider = resolveMapsProvider(platform, providerOverride);
+    // The exit is chosen first, because it is where the street leg begins: from
+    // where the visitor stands now, facing the place they are heading for. A
+    // place that authored no door keeps its marker point — the degraded exit
+    // every unauthored plan runs on.
+    const exitDoor = chooseEntrance(origin.place, originPoint, destination.geo);
+    const departure = exitDoor?.geo ?? origin.place.geo;
+    // Then the arrival door, approached from wherever the visitor is leaving —
+    // the exit door if there is one — and ranked by the walk that follows it.
+    const arrivalDoor = chooseEntrance(destination, destinationPoint, departure);
+    const target = arrivalDoor
+        ? {
+            geo: arrivalDoor.geo,
+            kind: 'venue-entrance',
+            label: arrivalDoor.name ?? destination.name,
+            entrance: arrivalDoor.name,
+        }
+        : {
+            geo: destination.geo,
+            // A PoI is aimed at itself, which is not the same admission as aiming
+            // at a venue's marker: the venue is missing a door an author could have
+            // drawn, the PoI has nothing to be missing.
+            kind: destination.placeKind === 'outdoor-poi' ? 'outdoor-poi' : 'venue-marker',
+            label: destination.name,
+        };
+    const externalLeg = {
+        kind: 'external',
+        target,
+        // The gap itself, measured over the ground — the map sketches it and the
+        // label states its scale, so the user can judge the trip before handing off.
+        connector: {
+            from: departure,
+            to: target.geo,
+            distanceMeters: haversineDistance(departure, target.geo),
+        },
+        provider,
+        // A live position is the user's to tell the maps app, not ours: it moves,
+        // and the provider already tracks it. Every other origin stands still long
+        // enough to be worth naming, so the street preview runs A to B.
+        url: buildExternalHandoffUrl(provider, target.geo, origin.kind === 'live-position' ? undefined : departure),
+    };
+    const legs = [
+        ...indoorLeg('exit', origin.place, exitDoor),
+        externalLeg,
+        ...indoorLeg('arrival', destination, arrivalDoor),
+    ];
+    return {
+        outcome: 'journey',
+        journey: {
+            origin: originRef(origin),
+            destination: placeRef(destination),
+            destinationName: destinationName ?? destination.name,
+            legs,
+        },
+    };
+}