@expofp/wayfinding

Framework-neutral wayfinding for the ExpoFP SDK: a routing/snapping engine, an imperative runtime orchestrator, and a scene renderer — with no coupling to efp stores or MobX. core and runtime are environment-agnostic; the scene renderer assumes a browser-like environment (requestAnimationFrame, document), so the package is not suitable for Node/SSR as-is. All three layers sit behind two entry points: initWayfindingLayers, which builds the layer block for the host to mount, and createWayfinding, which finds it in the scene and fills it.

Install

pnpm add @expofp/wayfinding @expofp/renderer

@expofp/renderer is a peer dependency and must be installed by the consumer: the package's public types (e.g. RenderableDef on Wayfinding/RendererPort) reference it, so its types must resolve for @expofp/wayfinding's .d.ts to compile.

Layers

| Layer | What it is | | ---------- | -------------------------------------------------------------------------------------------- | | core | Graph build + A* pathfinding, route geometry, snapping, transition points. Pure functions. | | runtime | Imperative orchestrator (setRoute / setPosition / notifyFloorChanged) over the engine. | | renderer | Scene mutator (icons, trails, route lines) against an injected RendererPort. |

These layers are internal. The package exports only the createWayfinding facade, initWayfindingLayers (the layer block it draws into, for the host to mount) with resolveWayfindingLayers (which finds that block in a scene again), the port interfaces the host implements, the boundary data types, the CURRENT_POSITION_POINT_ID protocol sentinel, and the optimizeWaypointOrder helper.

Ports (host implements)

The package knows nothing concrete about the host renderer, graph data, or app state. The host supplies four ports via WayfindingConfig:

• dataSource (GraphDataSource) — graph lines + line ends for pathfinding.
• renderer (RendererPort) — the host's cardinal-snap rule and commit.
• iconProvider (IconProvider) — canvases for icon names.
• floorContext (FloorContext) — active floor / visibility predicates.

@expofp/renderer is a type-only peer (its types appear in the public API; the concrete renderer is injected through RendererPort). @expofp/geometry is a regular runtime dependency (Rect, Box, geometry helpers).

Usage

import { createWayfinding } from '@expofp/wayfinding';

const wayfinding = createWayfinding({
  dataSource, // GraphDataSource
  renderer, // RendererPort
  iconProvider, // IconProvider
  floorContext, // FloorContext
  layers, // WayfindingLayers, from resolveWayfindingLayers(scene.rootLayer)
  gpsConfig, // optional GPS calibration + snap/reroute thresholds
  onTransitionClick: (point) => {
    /* switch active floor */
  },
  onRouteUpdate: (lines, bounds) => {
    /* fit camera, update UI */
  },
  onRouteDistance: (distance) => {
    /* show remaining distance */
  },
});

// Drive it with route/position/floor updates:
wayfinding.setRoute({ from, to, accessible: false });
wayfinding.setPosition(position); // or null to hide
wayfinding.notifyFloorChanged();

// Forward pointer events:
wayfinding.handleClick(pickedDefs);

wayfinding.destroy();

optimizeWaypointOrder is exported separately to order booth waypoints before a createWayfinding instance exists (it backs the SDK's getOptimizedRoutes).