@expofp/wayfinding 3.11.11

package/README.md

@@ -0,0 +1,84 @@
+# @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 a
+single entry point, `createWayfinding`.
+
+## Install
+
+```sh
+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, 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`) — def factories, current scale, scene layers, 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
+
+```ts
+import { createWayfinding } from '@expofp/wayfinding';
+
+const wayfinding = createWayfinding({
+  dataSource, // GraphDataSource
+  renderer, // RendererPort
+  iconProvider, // IconProvider
+  floorContext, // FloorContext
+  layers, // LayerNames: { points, trail, lines, linesAnimated, currentPosition }
+  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 camera/pointer events:
+wayfinding.applyScale(scale);
+wayfinding.applyRoll(angle);
+wayfinding.handleClick(pickedDefs);
+
+wayfinding.destroy();
+```
+
+`optimizeWaypointOrder` is exported separately to order booth waypoints before a
+`createWayfinding` instance exists (it backs the SDK's `getOptimizedRoutes`).

package/dist/core/createWayfindingEngine.d.ts

@@ -0,0 +1,16 @@
+import type { GraphDataSource, RouteEndpoint, RouteLine } from './types.js';
+export interface Route {
+    readonly lines: RouteLine[];
+    readonly distance: number;
+}
+export interface WayfindingEngine {
+    buildRoute(from: RouteEndpoint, to: RouteEndpoint, options?: {
+        accessible?: boolean;
+    }): Route;
+    buildWaypointsRoute(waypoints: RouteEndpoint[], options?: {
+        accessible?: boolean;
+        fastest?: boolean;
+    }): Route;
+}
+export declare function createWayfindingEngine(dataSource: GraphDataSource): WayfindingEngine;
+//# sourceMappingURL=createWayfindingEngine.d.ts.map

package/dist/core/createWayfindingEngine.js

@@ -0,0 +1,87 @@
+import { createGraphCache } from './graph/graphCache.js';
+import { buildMultiPointRoute } from './routing/buildMultiPointRoute.js';
+import { buildRoute as buildRouteInternal } from './routing/buildRoute.js';
+import { getRouteLength } from './routing/getRouteLength.js';
+import { reorderWaypoints } from './routing/optimizeWaypointOrder.js';
+import { resolveWaypointCandidates, } from './routing/resolveWaypointCandidates.js';
+const POINT_EPS = 1e-6;
+const pointEquals = (a, b) => a.layer === b.layer && Math.abs(a.x - b.x) < POINT_EPS && Math.abs(a.y - b.y) < POINT_EPS;
+/**
+ * Trim/extend the route's FROM tip to land exactly on `entry.projection`.
+ *  The FROM boundary is the first line; `boundary.p0` is its graph node.
+ * @param lines
+ * @param entry
+ */
+function attachFromEntry(lines, entry) {
+    if (!lines.length)
+        return lines;
+    const boundary = lines[0];
+    const chosenEndpoint = boundary.p0;
+    const otherEnd = pointEquals(entry.segment.p0, chosenEndpoint)
+        ? entry.segment.p1
+        : entry.segment.p0;
+    if (pointEquals(boundary.p1, otherEnd)) {
+        return [{ ...boundary, p0: entry.projection }, ...lines.slice(1)];
+    }
+    return [{ ...entry.segment, p0: entry.projection, p1: chosenEndpoint }, ...lines];
+}
+/**
+ * Mirror of {@link attachFromEntry} for the TO side: the TO boundary is the
+ *  last line and `boundary.p1` is its graph node.
+ * @param lines
+ * @param entry
+ */
+function attachToEntry(lines, entry) {
+    if (!lines.length)
+        return lines;
+    const boundary = lines[lines.length - 1];
+    const chosenEndpoint = boundary.p1;
+    const otherEnd = pointEquals(entry.segment.p0, chosenEndpoint)
+        ? entry.segment.p1
+        : entry.segment.p0;
+    if (pointEquals(boundary.p0, otherEnd)) {
+        return [...lines.slice(0, -1), { ...boundary, p1: entry.projection }];
+    }
+    return [...lines, { ...entry.segment, p0: chosenEndpoint, p1: entry.projection }];
+}
+function attachOffGraphEntries(lines, fromEntry, toEntry) {
+    let result = lines;
+    if (fromEntry)
+        result = attachFromEntry(result, fromEntry);
+    if (toEntry)
+        result = attachToEntry(result, toEntry);
+    return result;
+}
+export function createWayfindingEngine(dataSource) {
+    const cache = createGraphCache();
+    return {
+        buildRoute(from, to, options) {
+            const graph = cache.getOrBuild(dataSource, options?.accessible ?? false);
+            const fromResolved = resolveWaypointCandidates(graph, from);
+            const toResolved = resolveWaypointCandidates(graph, to);
+            const result = buildRouteInternal(graph, fromResolved.candidates, toResolved.candidates);
+            const hasOffGraph = !!fromResolved.offGraphEntry || !!toResolved.offGraphEntry;
+            const lines = attachOffGraphEntries(result.lines, fromResolved.offGraphEntry, toResolved.offGraphEntry);
+            return {
+                lines,
+                distance: hasOffGraph ? getRouteLength(lines) : result.totalDistance,
+            };
+        },
+        buildWaypointsRoute(waypoints, options) {
+            if (waypoints.length < 2)
+                return { lines: [], distance: 0 };
+            const graph = cache.getOrBuild(dataSource, options?.accessible ?? false);
+            const ordered = options?.fastest ? reorderWaypoints(waypoints) : waypoints;
+            const resolved = ordered.map((wp) => resolveWaypointCandidates(graph, wp));
+            const result = buildMultiPointRoute(graph, resolved.map((r) => r.candidates));
+            const fromEntry = resolved[0].offGraphEntry;
+            const toEntry = resolved[resolved.length - 1].offGraphEntry;
+            const hasOffGraph = !!fromEntry || !!toEntry;
+            const lines = attachOffGraphEntries(result.lines, fromEntry, toEntry);
+            return {
+                lines,
+                distance: hasOffGraph ? getRouteLength(lines) : result.totalDistance,
+            };
+        },
+    };
+}

package/dist/core/geometry/pointInPolygon.d.ts

@@ -0,0 +1,17 @@
+import { type PolygonVertex } from '../types.js';
+/**
+ * Convex polygon area via fan triangulation from vertex[0].
+ * @param polygon
+ */
+export declare function computePolygonArea(polygon: readonly PolygonVertex[]): number;
+/**
+ * Area-based point-in-polygon test with 1% relative tolerance. Convex polygons only.
+ * Inside ⇒ sum of (point, vertex_i, vertex_{i+1}) triangle areas equals polygon area; outside ⇒ larger.
+ * Tolerance includes points sitting fractionally outside the polygon (editor/float imprecision).
+ * Pass `polygonArea` from {@link computePolygonArea} to skip recomputation in hot loops.
+ * @param point
+ * @param polygon
+ * @param polygonArea
+ */
+export declare function pointInPolygon(point: PolygonVertex, polygon: readonly PolygonVertex[], polygonArea?: number): boolean;
+//# sourceMappingURL=pointInPolygon.d.ts.map

package/dist/core/geometry/pointInPolygon.js

@@ -0,0 +1,50 @@
+/**
+ * Relative area tolerance (1%) for the sum-of-triangles containment test.
+ *
+ * NOTE: this is intentionally NOT migrated to `@expofp/geometry`'s
+ * `polygonContainsPoint`. That function uses a per-triangle barycentric test
+ * whose tolerance is 1% of each triangle's area, which gives different
+ * boundary decisions than this whole-polygon-area test (verified: hundreds of
+ * near-boundary points flip between the two). Booth-bounds containment feeds
+ * graph-candidate selection (`graphPointResolvers`) and snap behavior
+ * (`snapToRoute`), so swapping the algorithm could silently change routing.
+ * Kept as the original sg-free implementation to preserve route selection.
+ */
+const POLYGON_AREA_TOLERANCE = 0.01;
+function triangleArea(vertexA, vertexB, vertexC) {
+    return Math.abs(0.5 *
+        (vertexA.x * (vertexB.y - vertexC.y) +
+            vertexB.x * (vertexC.y - vertexA.y) +
+            vertexC.x * (vertexA.y - vertexB.y)));
+}
+/**
+ * Convex polygon area via fan triangulation from vertex[0].
+ * @param polygon
+ */
+export function computePolygonArea(polygon) {
+    if (polygon.length < 3)
+        return 0;
+    let area = 0;
+    for (let i = 1; i < polygon.length - 1; i++) {
+        area += triangleArea(polygon[0], polygon[i], polygon[i + 1]);
+    }
+    return area;
+}
+/**
+ * Area-based point-in-polygon test with 1% relative tolerance. Convex polygons only.
+ * Inside ⇒ sum of (point, vertex_i, vertex_{i+1}) triangle areas equals polygon area; outside ⇒ larger.
+ * Tolerance includes points sitting fractionally outside the polygon (editor/float imprecision).
+ * Pass `polygonArea` from {@link computePolygonArea} to skip recomputation in hot loops.
+ * @param point
+ * @param polygon
+ * @param polygonArea
+ */
+export function pointInPolygon(point, polygon, polygonArea = computePolygonArea(polygon)) {
+    if (polygonArea === 0)
+        return false;
+    let sumFromPoint = 0;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        sumFromPoint += triangleArea(point, polygon[j], polygon[i]);
+    }
+    return Math.abs(polygonArea - sumFromPoint) < polygonArea * POLYGON_AREA_TOLERANCE;
+}

package/dist/core/geometry/projectPointOnSegment.d.ts

@@ -0,0 +1,27 @@
+import { type Point2Like } from '@expofp/geometry';
+export interface SegmentProjection {
+    readonly projected: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly distance: number;
+    readonly t: number;
+}
+/**
+ * Projects `point` onto the segment `a`–`b`, clamping the parameter `t` to
+ * `[0, 1]` so the result always lies on the segment (not its infinite line).
+ *
+ * `t` is the normalized position along the segment: `0` = `a`, `1` = `b`.
+ * For a zero-length segment (`a` equals `b`) the projection collapses to `a`
+ * with `t = 0`.
+ *
+ * Thin wrapper over `@expofp/geometry`'s `lineProjectPoint`; the projected
+ * position is re-shaped to a plain `{ x, y }` to preserve the legacy
+ * {@link SegmentProjection} contract (callers depend on a bare point, not a
+ * `Point` instance).
+ * @param point
+ * @param a
+ * @param b
+ */
+export declare function projectPointOnSegment(point: Point2Like, a: Point2Like, b: Point2Like): SegmentProjection;
+//# sourceMappingURL=projectPointOnSegment.d.ts.map

package/dist/core/geometry/projectPointOnSegment.js

@@ -0,0 +1,21 @@
+import { lineProjectPoint } from '@expofp/geometry';
+/**
+ * Projects `point` onto the segment `a`–`b`, clamping the parameter `t` to
+ * `[0, 1]` so the result always lies on the segment (not its infinite line).
+ *
+ * `t` is the normalized position along the segment: `0` = `a`, `1` = `b`.
+ * For a zero-length segment (`a` equals `b`) the projection collapses to `a`
+ * with `t = 0`.
+ *
+ * Thin wrapper over `@expofp/geometry`'s `lineProjectPoint`; the projected
+ * position is re-shaped to a plain `{ x, y }` to preserve the legacy
+ * {@link SegmentProjection} contract (callers depend on a bare point, not a
+ * `Point` instance).
+ * @param point
+ * @param a
+ * @param b
+ */
+export function projectPointOnSegment(point, a, b) {
+    const { projected, distance, t } = lineProjectPoint({ p0: a, p1: b }, point);
+    return { projected: { x: projected.x, y: projected.y }, distance, t };
+}

package/dist/core/graph/buildGraph.d.ts

@@ -0,0 +1,3 @@
+import { type GraphBuildOptions, type GraphDataSource, type GraphInstance, type PathFinder } from '../types.js';
+export declare function buildGraph(dataSource: GraphDataSource, pathFinder: PathFinder, options: GraphBuildOptions): GraphInstance;
+//# sourceMappingURL=buildGraph.d.ts.map

package/dist/core/graph/buildGraph.js

@@ -0,0 +1,7 @@
+export function buildGraph(dataSource, pathFinder, options) {
+    pathFinder.build(dataSource.getLines(), {
+        oriented: options.oriented ?? true,
+        onlyAccessible: options.onlyAccessible ?? false,
+    });
+    return { finder: pathFinder, dataSource, options };
+}

package/dist/core/graph/buildNGraph.d.ts

@@ -0,0 +1,13 @@
+import { type Graph } from 'ngraph.graph';
+import { type GraphLine, type PathFinderOptions } from '../types.js';
+interface LinkData {
+    distance: number;
+}
+/**
+ * Builds an ngraph instance from route lines, filtering and linking per options.
+ * @param lines
+ * @param options
+ */
+export declare function buildNGraph(lines: GraphLine[], options: PathFinderOptions): Graph<unknown, LinkData>;
+export {};
+//# sourceMappingURL=buildNGraph.d.ts.map

package/dist/core/graph/buildNGraph.js

@@ -0,0 +1,24 @@
+import createGraph from 'ngraph.graph';
+import { toNodeId } from './graphHelpers.js';
+import { linkCost } from './linkCost.js';
+/**
+ * Builds an ngraph instance from route lines, filtering and linking per options.
+ * @param lines
+ * @param options
+ */
+export function buildNGraph(lines, options) {
+    const { oriented, onlyAccessible } = options;
+    const graph = createGraph();
+    for (const line of lines) {
+        if (onlyAccessible && line.unaccessible)
+            continue;
+        const fromId = toNodeId(line.p0);
+        const toId = toNodeId(line.p1);
+        const distance = linkCost(line);
+        graph.addLink(fromId, toId, { distance });
+        if (oriented && !line.unidirection) {
+            graph.addLink(toId, fromId, { distance });
+        }
+    }
+    return graph;
+}

package/dist/core/graph/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Default A* cost for an unset virtual link that changes layers. Being far
+ * larger than any physical segment cost, it makes the pathfinder minimize the
+ * number of floor changes, so a route only crosses a floor when needed to reach
+ * the destination. A per-line `virtualLength` overrides it (designer control).
+ */
+export declare const FLOOR_TRANSITION_PENALTY = 10000;
+/** Default A* cost for a virtual link that stays on the same layer (free). */
+export declare const VIRTUAL_LINE_PENALTY = 0;
+/**
+ * Fallback line weight when `line.weight` is 0 (meaning "not set" in floorplan data,
+ * not "free passage").
+ */
+export declare const DEFAULT_LINE_WEIGHT = 4;
+/**
+ * Multiplier applied to a graph edge cost whenever the route changes direction at a node
+ * (A* turn penalty).
+ */
+export declare const TURN_PENALTY = 1.01;
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/graph/constants.js

@@ -0,0 +1,19 @@
+/**
+ * Default A* cost for an unset virtual link that changes layers. Being far
+ * larger than any physical segment cost, it makes the pathfinder minimize the
+ * number of floor changes, so a route only crosses a floor when needed to reach
+ * the destination. A per-line `virtualLength` overrides it (designer control).
+ */
+export const FLOOR_TRANSITION_PENALTY = 10000;
+/** Default A* cost for a virtual link that stays on the same layer (free). */
+export const VIRTUAL_LINE_PENALTY = 0;
+/**
+ * Fallback line weight when `line.weight` is 0 (meaning "not set" in floorplan data,
+ * not "free passage").
+ */
+export const DEFAULT_LINE_WEIGHT = 4;
+/**
+ * Multiplier applied to a graph edge cost whenever the route changes direction at a node
+ * (A* turn penalty).
+ */
+export const TURN_PENALTY = 1.01;

package/dist/core/graph/findShortestPath.d.ts

@@ -0,0 +1,23 @@
+import { type GraphInstance, type GraphLine, type RoutePoint, type ShortestPathResult } from '../types.js';
+/**
+ * Computes the weighted path cost matching the graph link distance formula.
+ * Floor-change surcharges are already baked into `linkCost`, so this simply
+ * sums the per-edge cost.
+ * @param points
+ * @param lines
+ */
+export declare function computeWeightedPathCost(points: RoutePoint[], lines: GraphLine[]): number;
+/**
+ * Finds the shortest path between candidate point sets by trying all from×to
+ * pairs and picking the one with the lowest weighted cost.
+ *
+ * Complexity is O(N×M × A*) where N = |from|, M = |to|. In practice N, M ≤ 5
+ * (rect-based booth candidates) or = 1 (nearest-point fallback), so the brute
+ * force approach is acceptable. Multi-source A* would reduce this to a single
+ * traversal but adds significant implementation complexity.
+ * @param graph
+ * @param from
+ * @param to
+ */
+export declare function findShortestPath(graph: GraphInstance, from: RoutePoint[], to: RoutePoint[]): ShortestPathResult | null;
+//# sourceMappingURL=findShortestPath.d.ts.map

package/dist/core/graph/findShortestPath.js

@@ -0,0 +1,65 @@
+import { getRouteLength } from '../routing/getRouteLength.js';
+import { buildRouteSegments, findLineByEndpoints, toNodeId } from './graphHelpers.js';
+import { linkCost } from './linkCost.js';
+function createRoutePoint(layer, x, y) {
+    return { layer, x, y };
+}
+/**
+ * Computes the weighted path cost matching the graph link distance formula.
+ * Floor-change surcharges are already baked into `linkCost`, so this simply
+ * sums the per-edge cost.
+ * @param points
+ * @param lines
+ */
+export function computeWeightedPathCost(points, lines) {
+    let cost = 0;
+    for (let index = 1; index < points.length; index++) {
+        const line = findLineByEndpoints(lines, points[index - 1], points[index]);
+        if (!line)
+            continue;
+        cost += linkCost(line);
+    }
+    return cost;
+}
+/**
+ * Finds the shortest path between candidate point sets by trying all from×to
+ * pairs and picking the one with the lowest weighted cost.
+ *
+ * Complexity is O(N×M × A*) where N = |from|, M = |to|. In practice N, M ≤ 5
+ * (rect-based booth candidates) or = 1 (nearest-point fallback), so the brute
+ * force approach is acceptable. Multi-source A* would reduce this to a single
+ * traversal but adds significant implementation complexity.
+ * @param graph
+ * @param from
+ * @param to
+ */
+export function findShortestPath(graph, from, to) {
+    const lines = graph.dataSource.getLines();
+    let bestResult = null;
+    let bestWeightedCost = Infinity;
+    for (const fromPt of from) {
+        for (const toPt of to) {
+            const fromId = toNodeId(fromPt);
+            const toId = toNodeId(toPt);
+            if (!graph.finder.hasNode(fromId) || !graph.finder.hasNode(toId)) {
+                console.debug(`WF. findShortestPath: node not in graph, skipping pair ${fromId} → ${toId}`);
+                continue;
+            }
+            const nodes = graph.finder.find(fromId, toId);
+            if (!nodes.length)
+                continue;
+            const points = nodes.map((node) => createRoutePoint(node.layer, node.x, node.y));
+            const routeLines = buildRouteSegments(points, lines);
+            if (!routeLines.length)
+                continue;
+            // Compare by weighted cost (consistent with A* graph link distance formula),
+            // but store physical distance in the result
+            const weightedCost = computeWeightedPathCost(points, lines);
+            if (weightedCost < bestWeightedCost) {
+                bestWeightedCost = weightedCost;
+                bestResult = { lines: routeLines, distance: getRouteLength(routeLines) };
+            }
+        }
+    }
+    return bestResult;
+}

package/dist/core/graph/graphCache.d.ts

@@ -0,0 +1,7 @@
+import { type GraphDataSource, type GraphInstance } from '../types.js';
+interface GraphCache {
+    getOrBuild(dataSource: GraphDataSource, onlyAccessible: boolean): GraphInstance;
+}
+export declare function createGraphCache(): GraphCache;
+export {};
+//# sourceMappingURL=graphCache.d.ts.map

package/dist/core/graph/graphCache.js

@@ -0,0 +1,20 @@
+import { buildGraph } from './buildGraph.js';
+import { createAStarPathFinder } from './pathfinder/aStarPathFinder.js';
+export function createGraphCache() {
+    let cached = null;
+    let cachedOnlyAccessible = false;
+    return {
+        getOrBuild(dataSource, onlyAccessible) {
+            // Cache is keyed only on `onlyAccessible`, not on dataSource identity, so it
+            // never invalidates if the floorplan data changes. Safe because each floorplan
+            // loads a fresh engine (hence a fresh cache) — a cached graph never outlives
+            // its dataSource. Add an identity check + invalidation if that ever stops holding.
+            if (cached && cachedOnlyAccessible === onlyAccessible)
+                return cached;
+            const pathFinder = createAStarPathFinder();
+            cached = buildGraph(dataSource, pathFinder, { oriented: true, onlyAccessible });
+            cachedOnlyAccessible = onlyAccessible;
+            return cached;
+        },
+    };
+}

package/dist/core/graph/graphHelpers.d.ts

@@ -0,0 +1,8 @@
+import { type GraphLine, type RouteLine, type RoutePoint } from '../types.js';
+export declare const toNodeId: (p: RoutePoint) => string;
+export declare const arePointsClose: (p1: RoutePoint, p2: RoutePoint) => boolean;
+export declare const matchesLine: (line: GraphLine, p0: RoutePoint, p1: RoutePoint) => boolean;
+export declare function findLineByEndpoints(lines: GraphLine[], p0: RoutePoint, p1: RoutePoint): GraphLine | undefined;
+export declare function canMergeSegments(lastSegment: RouteLine, segment: RouteLine): boolean;
+export declare function buildRouteSegments(points: RoutePoint[], lines: GraphLine[]): RouteLine[];
+//# sourceMappingURL=graphHelpers.d.ts.map

package/dist/core/graph/graphHelpers.js

@@ -0,0 +1,52 @@
+import { degToRad, lineAngle, pointDistance } from '@expofp/geometry';
+export const toNodeId = (p) => `${p.layer ?? ''}_${p.x}_${p.y}`;
+/** Maximum distance (SVG units) to consider two graph nodes as the same point. */
+const POINT_PROXIMITY_THRESHOLD = 1;
+// `RoutePoint.layer` is typed as a string, but external data may still supply a
+// nullish/invalid layer. Normalize it to '' so point comparisons stay consistent
+// with the ids that toNodeId/parseNodeId round-trip to.
+export const arePointsClose = (p1, p2) => (p1.layer ?? '') === (p2.layer ?? '') && pointDistance(p1, p2) <= POINT_PROXIMITY_THRESHOLD;
+export const matchesLine = (line, p0, p1) => (arePointsClose(line.p0, p0) && arePointsClose(line.p1, p1)) ||
+    (arePointsClose(line.p0, p1) && arePointsClose(line.p1, p0));
+export function findLineByEndpoints(lines, p0, p1) {
+    return lines.find((line) => matchesLine(line, p0, p1));
+}
+// Threshold expressed in radians (was 5° under simple-geometry's degree-based
+// lineAngle; @expofp/geometry's lineAngle returns radians via atan2).
+const MERGE_ANGLE_THRESHOLD = degToRad(5);
+export function canMergeSegments(lastSegment, segment) {
+    if (lastSegment.virtual !== segment.virtual)
+        return false;
+    const lastAngle = lineAngle(lastSegment.p0, lastSegment.p1);
+    const angle = lineAngle(segment.p0, segment.p1);
+    let diff = Math.abs(angle - lastAngle);
+    // Wrap across the ±π discontinuity (was ±180° / 360° under degrees).
+    if (diff > Math.PI)
+        diff = 2 * Math.PI - diff;
+    return diff <= MERGE_ANGLE_THRESHOLD;
+}
+export function buildRouteSegments(points, lines) {
+    const result = [];
+    for (let i = 1; i < points.length; i++) {
+        const previousPoint = points[i - 1];
+        const currentPoint = points[i];
+        const line = findLineByEndpoints(lines, previousPoint, currentPoint);
+        if (!line) {
+            console.warn(`WF: buildRouteSegments — no line found between ${toNodeId(previousPoint)} and ${toNodeId(currentPoint)}`);
+            continue;
+        }
+        const segment = {
+            p0: previousPoint,
+            p1: currentPoint,
+            virtual: line.virtual,
+        };
+        const lastSegment = result[result.length - 1];
+        if (lastSegment && canMergeSegments(lastSegment, segment)) {
+            result[result.length - 1] = { ...lastSegment, p1: segment.p1 };
+        }
+        else {
+            result.push(segment);
+        }
+    }
+    return result;
+}

package/dist/core/graph/linkCost.d.ts

@@ -0,0 +1,13 @@
+import { type GraphLine } from '../types.js';
+export declare function changesLayer(line: GraphLine): boolean;
+/**
+ * Weighted cost of a graph edge for A*.
+ *
+ * Physical links cost their weighted length. A virtual link uses its configured
+ * `virtualLength` when set (designer control); otherwise a layer-changing link
+ * costs `FLOOR_TRANSITION_PENALTY` (routes avoid needless floor changes) and a
+ * same-layer link is free (`VIRTUAL_LINE_PENALTY`).
+ * @param line
+ */
+export declare function linkCost(line: GraphLine): number;
+//# sourceMappingURL=linkCost.d.ts.map

package/dist/core/graph/linkCost.js

@@ -0,0 +1,24 @@
+import { pointDistance } from '@expofp/geometry';
+import { DEFAULT_LINE_WEIGHT, FLOOR_TRANSITION_PENALTY, VIRTUAL_LINE_PENALTY, } from './constants.js';
+function physicalCost(line) {
+    return pointDistance(line.p0, line.p1) / (line.weight || DEFAULT_LINE_WEIGHT);
+}
+export function changesLayer(line) {
+    return (line.p0.layer ?? '') !== (line.p1.layer ?? '');
+}
+/**
+ * Weighted cost of a graph edge for A*.
+ *
+ * Physical links cost their weighted length. A virtual link uses its configured
+ * `virtualLength` when set (designer control); otherwise a layer-changing link
+ * costs `FLOOR_TRANSITION_PENALTY` (routes avoid needless floor changes) and a
+ * same-layer link is free (`VIRTUAL_LINE_PENALTY`).
+ * @param line
+ */
+export function linkCost(line) {
+    if (!line.virtual)
+        return physicalCost(line);
+    if (line.virtualLength != null)
+        return line.virtualLength;
+    return changesLayer(line) ? FLOOR_TRANSITION_PENALTY : VIRTUAL_LINE_PENALTY;
+}

package/dist/core/graph/pathfinder/aStarPathFinder.d.ts

@@ -0,0 +1,3 @@
+import { type PathFinder } from '../../types.js';
+export declare function createAStarPathFinder(): PathFinder;
+//# sourceMappingURL=aStarPathFinder.d.ts.map