@expofp/wayfinding 3.11.11

package/dist/renderer/trailManager.js

@@ -0,0 +1,79 @@
+import { Rect } from '@expofp/geometry';
+import { computeTrailPoints } from '../core/index.js';
+/** Distance between trail dots at scale=1, in the same units as route points. */
+const TRAIL_INTERVAL_AT_BASE_SCALE = 40;
+/**
+ * Create a {@link TrailManager} that renders dot trails into layers
+ * managed by the given {@link LayerManager}.
+ * @param layerManager
+ * @param rendererPort
+ */
+export function createTrailManager(layerManager, rendererPort) {
+    const trails = new Map();
+    function removeDotsFromLayer(record) {
+        if (!record.dotDefs.length)
+            return;
+        const layer = layerManager.touchLayer(record.layerName);
+        const oldDots = new Set(record.dotDefs);
+        layer.children = layer.children.filter((child) => !oldDots.has(child));
+        record.dotDefs = [];
+    }
+    function redraw(record, scale) {
+        const layer = layerManager.touchLayer(record.layerName);
+        const interval = TRAIL_INTERVAL_AT_BASE_SCALE * scale;
+        const points = computeTrailPoints(record.from, record.to, interval);
+        const canvas = record.canvas;
+        const newDots = points.map((point) => rendererPort.createImageDef(canvas, new Rect({ x: point.x, y: point.y }, { x: canvas.width * scale, y: canvas.height * scale })));
+        removeDotsFromLayer(record);
+        layer.children.push(...newDots);
+        record.dotDefs = newDots;
+    }
+    function drop(name) {
+        const record = trails.get(name);
+        if (!record)
+            return;
+        removeDotsFromLayer(record);
+        trails.delete(name);
+    }
+    return {
+        setTrail(name, from, to, options) {
+            if (from === null || to === null) {
+                drop(name);
+                return;
+            }
+            if (!options)
+                throw new Error(`renderer: setTrail("${name}") requires options when from/to are non-null`);
+            const existing = trails.get(name);
+            if (existing) {
+                if (existing.canvas !== options.canvas || existing.layerName !== options.layer) {
+                    throw new Error(`renderer: trail "${name}" cannot change canvas or layer after first call`);
+                }
+                existing.from = from;
+                existing.to = to;
+                redraw(existing, rendererPort.getScale());
+                return;
+            }
+            const record = {
+                from,
+                to,
+                canvas: options.canvas,
+                layerName: options.layer,
+                dotDefs: [],
+            };
+            trails.set(name, record);
+            redraw(record, rendererPort.getScale());
+        },
+        applyScale(scale) {
+            const layers = new Set();
+            for (const record of trails.values()) {
+                redraw(record, scale);
+                layers.add(layerManager.touchLayer(record.layerName));
+            }
+            return [...layers];
+        },
+        destroy() {
+            for (const trailName of [...trails.keys()])
+                drop(trailName);
+        },
+    };
+}

package/dist/renderer/types.d.ts

@@ -0,0 +1,129 @@
+import type { Point2Like, Rect } from '@expofp/geometry';
+import type { ImageDef, ImageSource, LayerDef, LineDef, Rect as RendererRect, RenderableDef } from '@expofp/renderer';
+/**
+ * The renderer this layer talks to, injected so it stays free of a concrete
+ * renderer. Typed only against `@expofp/renderer` / `@expofp/geometry` so it
+ * carries no dependency on `src/renderer`.
+ */
+export interface RendererPort {
+    createImageDef(source: ImageSource, bounds: Rect, options?: {
+        hidden?: boolean;
+        dim?: boolean;
+        interactive?: boolean;
+        origin?: [number, number];
+    }): ImageDef;
+    createLineDef(line: {
+        p0: Point2Like;
+        p1: Point2Like;
+    }, color?: string, width?: number): LineDef;
+    getRotation(newAngle: number, currentRotation: number): number | undefined;
+    /** Convert a geometry rect to the renderer's `Rect`. */
+    rectToRenderer(rect: Rect): RendererRect;
+    /** Current camera point-scale. */
+    getScale(): number;
+    /** Scene root-layer children, used to resolve wf layers by name. */
+    getLayers(): LayerDef[];
+    /** Commit changed defs/layers to the renderer. */
+    update(...defs: RenderableDef[]): void;
+}
+export interface RouteColors {
+    readonly passed: string;
+    readonly remaining: string;
+    readonly active: string;
+}
+export interface IconConfig {
+    readonly canvas: HTMLCanvasElement;
+    /**
+     * Target layer name in the scene. Renderer locates the layer once per
+     * (name, layer) slot and reuses it.
+     *
+     * TODO(future): when renderer learns to create layers dynamically
+     * inside `createWayfindingRenderer`, this field is removed — renderer
+     * will own layer creation by icon name.
+     */
+    readonly layer: string;
+    readonly x: number;
+    readonly y: number;
+    /** Rotation in radians. */
+    readonly rotation?: number;
+    readonly hidden?: boolean;
+    readonly dimmed?: boolean;
+    /**
+     * Anchor point [0..1, 0..1]. Set at first setIcon for an icon key;
+     * ignored on subsequent updates (origin is fixed in ImageDef at creation).
+     */
+    readonly origin?: [number, number];
+    /**
+     * When true, renderer registers a camera-roll handler that snaps the icon
+     * rotation to the nearest cardinal direction (N/S/E/W, 90° steps) as the
+     * camera rotates past 45° thresholds. Used for label-like icons
+     * (source/destination/transition) that should remain readable.
+     *
+     * Do NOT enable for icons whose `rotation` carries meaning (e.g. position
+     * arrow heading, kiosk heading) — the snap would override that meaning.
+     *
+     * Set at first setIcon for an icon key; ignored on subsequent updates.
+     */
+    readonly cardinalSnap?: boolean;
+    readonly onClick?: () => void;
+}
+export interface WayfindingRendererConfig {
+    /** Optional color overrides; defaults applied if omitted. */
+    readonly colors?: Partial<RouteColors>;
+}
+/**
+ * WayfindingRenderer — generic ImageDef/LineDef renderer for wayfinding visuals.
+ *
+ * Mutators (`setIcon`/`clearIcons`/`setTrail`/`setRouteLines`/`clearRoute`) only
+ * mutate scene state; call `flush()` to commit a batch. The route animation tick
+ * updates the renderer directly, outside any batch.
+ */
+export interface WayfindingRenderer {
+    /**
+     * Place or update an icon by `(name, key)`. First call creates it in
+     * `config.layer`; later calls mutate in place. `config: null` hides it.
+     * `config.layer` must stay stable for a `(name, key)`. Buffered — `flush()` to commit.
+     */
+    setIcon(name: string, config: IconConfig | null, key?: string | number): void;
+    /** Hide every icon sharing one of `names` (kept alive for reuse). Buffered. */
+    clearIcons(names: string | readonly string[]): void;
+    /**
+     * Place or update a named dot trail between two points; `from/to = null`
+     * clears it. `options` required when non-null; `canvas`/`layer` must stay
+     * stable. Buffered — `flush()` to commit.
+     */
+    setTrail(name: string, from: Point2Like | null, to: Point2Like | null, options?: {
+        readonly canvas: HTMLCanvasElement;
+        readonly layer: string;
+    }): void;
+    /**
+     * Replace static route lines (passed + remaining) and (re)start the remaining
+     * animation. Buffered — `flush()` to commit.
+     */
+    setRouteLines(passed: readonly {
+        readonly p0: Point2Like;
+        readonly p1: Point2Like;
+    }[], remaining: readonly {
+        readonly p0: Point2Like;
+        readonly p1: Point2Like;
+    }[], options: {
+        readonly linesLayer: string;
+        readonly animatedLinesLayer: string;
+        readonly resetAnimation?: boolean;
+    }): void;
+    /** Recompute icon/trail bounds for `scale`; returns changed defs to render. */
+    applyScale(scale: number): RenderableDef[];
+    /** Apply camera roll to cardinal-snap icons; returns changed defs to render. */
+    applyRoll(cameraAngle: number): RenderableDef[];
+    /** Fire the hit clickable icon's `onClick` from already-picked defs. */
+    handleClick(defs: readonly RenderableDef[]): void;
+    /** Whether a clickable icon is under the already-picked defs (for cursor). */
+    handleHover(defs: readonly RenderableDef[]): boolean;
+    /** Clear route lines, drop trails, hide icons. Buffered — `flush()` to commit. */
+    clearRoute(): void;
+    /** Commit buffered mutations to the renderer (via the injected port). */
+    flush(): void;
+    /** Full teardown (managers cleared). Does NOT flush. */
+    destroy(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/renderer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/createWayfindingRuntime.d.ts

@@ -0,0 +1,3 @@
+import type { WayfindingRuntime, WayfindingRuntimeConfig } from './types.js';
+export declare function createWayfindingRuntime({ engine, renderer, iconProvider, floorContext, layers, snapThreshold, rerouteThreshold, onTransitionClick, onRouteUpdate, onRouteDistance, }: WayfindingRuntimeConfig): WayfindingRuntime;
+//# sourceMappingURL=createWayfindingRuntime.d.ts.map

package/dist/runtime/createWayfindingRuntime.js

@@ -0,0 +1,248 @@
+import { Box } from '@expofp/geometry';
+import { createRerouteController, getRouteLength, } from '../core/index.js';
+import { createEndpointView } from './endpointView.js';
+import { getRouteLines } from './getRouteLines.js';
+import { createPositionTrailView } from './positionTrailView.js';
+import { CURRENT_POSITION_POINT_ID } from './positionView.js';
+import { createRouteLinesView } from './routeLinesView.js';
+import { computeRouteRenderData } from './routeRenderData.js';
+import { computeRouteUpdate } from './routeUpdate.js';
+import { snapPositionToRoute } from './snapPositionToRoute.js';
+import { createTrailView } from './trailView.js';
+import { createTransitionView } from './transitionView.js';
+const linesToPoints = (lines) => lines.flatMap((line) => [line.p0, line.p1]);
+export function createWayfindingRuntime({ engine, renderer, iconProvider, floorContext, layers, snapThreshold, rerouteThreshold, onTransitionClick, onRouteUpdate, onRouteDistance, }) {
+    const rerouteController = createRerouteController(rerouteThreshold);
+    const endpoints = createEndpointView({
+        renderer,
+        iconProvider,
+        floorContext,
+        layer: layers.points,
+    });
+    const transitions = createTransitionView({
+        renderer,
+        iconProvider,
+        floorContext,
+        onTransitionClick,
+        layer: layers.points,
+    });
+    const trails = createTrailView({ renderer, iconProvider, floorContext, layer: layers.trail });
+    const positionTrails = createPositionTrailView({
+        renderer,
+        iconProvider,
+        floorContext,
+        trails,
+        iconLayer: layers.currentPosition,
+        snapThreshold,
+    });
+    const routeLinesView = createRouteLinesView({
+        renderer,
+        linesLayer: layers.lines,
+        animatedLinesLayer: layers.linesAnimated,
+    });
+    let routeLines = [];
+    let currentFrom = null;
+    let currentTo = null;
+    let currentPosition = null;
+    let lastVisibleDistance = 0;
+    // Sticky-snap: flips to true the first time a CP for the current route snaps. Suppresses the
+    // user-location off-graph trail on later drifts back into the snap-gap zone. Reset on setRoute.
+    let hasSnappedCurrentRoute = false;
+    // Live snap state of the latest tick (not sticky) — drives the greyed-out source variant.
+    let snappedToRoute = false;
+    function getCurrentRouteLayer() {
+        if (floorContext.showAllFloors())
+            return null;
+        return floorContext.getActiveFloor();
+    }
+    function getVisibleLines() {
+        const layer = getCurrentRouteLayer();
+        if (layer === null)
+            return routeLines.filter((line) => !line.virtual);
+        return routeLines.filter((line) => line.p0.layer === layer && !line.virtual);
+    }
+    // Non-virtual lines across all floors — the same set emitted via `onRouteUpdate`
+    // (see `computeRouteUpdate`), so reroute drift is measured against the full route.
+    function shouldReroute(position) {
+        return rerouteController.shouldReroute(position, routeLines.filter((line) => !line.virtual));
+    }
+    function getRouteSnapshot() {
+        if (!currentFrom || !currentTo)
+            return null;
+        const visibleLines = getVisibleLines();
+        if (!visibleLines.length)
+            return null;
+        return {
+            from: currentFrom,
+            to: currentTo,
+            routePoints: linesToPoints(visibleLines),
+            visibleLines,
+        };
+    }
+    function renderVisibleRoute(snap = null, preserveProgress = false) {
+        if (!currentFrom || !currentTo)
+            return;
+        const data = computeRouteRenderData({
+            routeLines,
+            currentRouteLayer: getCurrentRouteLayer(),
+            snap,
+        });
+        routeLinesView.draw(data, preserveProgress);
+        lastVisibleDistance = data.distance;
+    }
+    function syncTrail(snap) {
+        const route = getRouteSnapshot();
+        if (!route) {
+            positionTrails.setTrail(null, null);
+            return;
+        }
+        // CP and kiosk are mutually exclusive in practice. Pick FROM first; fall through to TO.
+        // Sticky-snap suppression only applies to live-CP FROM — kiosk anchors are static.
+        const livePosition = currentPosition && snap && !snap.snapped ? currentPosition : null;
+        const pickAnchor = (endpoint) => {
+            if (endpoint.bounds?.length)
+                return null;
+            if (endpoint.id === CURRENT_POSITION_POINT_ID)
+                return livePosition;
+            return endpoint;
+        };
+        // `hasSnappedCurrentRoute` only flips for a live-CP FROM (booth/kiosk origins never snap),
+        // so it already implies a CP origin — no need to re-check the endpoint id here.
+        const fromAnchor = hasSnappedCurrentRoute ? null : pickAnchor(route.from);
+        // The trail tip is the route's graph endpoint on the same side as its
+        // off-graph anchor: first point for FROM, last point for TO.
+        if (fromAnchor) {
+            positionTrails.setTrail(route.routePoints[0], fromAnchor);
+            return;
+        }
+        const toAnchor = pickAnchor(route.to);
+        positionTrails.setTrail(toAnchor ? route.routePoints[route.routePoints.length - 1] : null, toAnchor);
+    }
+    function syncRouteVisuals() {
+        if (!currentFrom || !currentTo)
+            return;
+        const route = getRouteSnapshot();
+        if (!route) {
+            endpoints.hide();
+            transitions.clear();
+            positionTrails.clearTrail();
+            renderVisibleRoute();
+            return;
+        }
+        endpoints.place(currentFrom, currentTo, route.routePoints, snappedToRoute);
+        transitions.place(routeLines);
+        renderVisibleRoute();
+        syncTrail(null);
+    }
+    /**
+     * Re-applies source/destination icons only — used when the CP appears/disappears or snaps onto
+     *  the route, since the source icon's visibility (CP vs kiosk) and grey variant depend on both.
+     */
+    function syncEndpoints() {
+        if (!currentFrom || !currentTo)
+            return;
+        const route = getRouteSnapshot();
+        if (route)
+            endpoints.place(currentFrom, currentTo, route.routePoints, snappedToRoute);
+    }
+    function snapPosition() {
+        snappedToRoute = false;
+        if (!currentPosition || !currentFrom || !currentTo)
+            return null;
+        const nonVirtual = routeLines.filter((line) => !line.virtual);
+        if (!nonVirtual.length)
+            return null;
+        const route = getRouteSnapshot();
+        const result = route
+            ? positionTrails.applyToRoute(currentPosition, route, nonVirtual)
+            : // Selected floor doesn't pass through the route — view has nothing
+                // to draw, but distance must still update. Snap against the full
+                // non-virtual route directly.
+                snapPositionToRoute(currentPosition, nonVirtual, currentFrom, currentTo, snapThreshold);
+        if (result.snapped)
+            hasSnappedCurrentRoute = true;
+        snappedToRoute = result.snapped;
+        return result;
+    }
+    function emitRouteUpdate() {
+        const route = computeRouteUpdate(routeLines, getVisibleLines());
+        onRouteUpdate(route.lines, route.bounds);
+        return route;
+    }
+    function setRoute({ from, to, waypoints, accessible }) {
+        const newRouteLines = getRouteLines({ engine, from, to, waypoints, accessible });
+        if (!newRouteLines.length) {
+            clearRoute();
+            return false;
+        }
+        hasSnappedCurrentRoute = false;
+        currentFrom = from;
+        currentTo = to;
+        routeLines = newRouteLines;
+        syncRouteVisuals();
+        const { lines } = emitRouteUpdate();
+        const snap = snapPosition();
+        syncEndpoints(); // snapPosition may have flipped the snap state — refresh the source variant
+        syncTrail(snap);
+        if (snap)
+            renderVisibleRoute(snap, true);
+        onRouteDistance(snap ? lastVisibleDistance : getRouteLength(lines));
+        renderer.flush();
+        return true;
+    }
+    function onPositionChanged(position) {
+        const hadPosition = currentPosition !== null;
+        currentPosition = position;
+        if (!position) {
+            snappedToRoute = false; // no CP → the source reverts from greyed to full-colour
+            positionTrails.hideIcon();
+            syncTrail(null);
+            if (hadPosition)
+                syncEndpoints();
+            renderVisibleRoute();
+            onRouteDistance(lastVisibleDistance);
+            renderer.flush();
+            return;
+        }
+        positionTrails.placeIcon(position);
+        const snap = snapPosition();
+        syncEndpoints(); // CP presence / snap state may have changed — refresh source visibility + variant
+        syncTrail(snap);
+        if (snap)
+            renderVisibleRoute(snap, true);
+        onRouteDistance(lastVisibleDistance);
+        renderer.flush();
+    }
+    function onFloorChanged() {
+        syncRouteVisuals();
+        const snap = snapPosition();
+        syncEndpoints(); // snap state may differ on the new floor — refresh the source variant
+        syncTrail(snap);
+        if (snap)
+            renderVisibleRoute(snap, true);
+        if (routeLines.length)
+            emitRouteUpdate();
+        onRouteDistance(lastVisibleDistance);
+        renderer.flush();
+    }
+    function clearRoute() {
+        hasSnappedCurrentRoute = false;
+        routeLines = [];
+        currentFrom = null;
+        currentTo = null;
+        lastVisibleDistance = 0;
+        endpoints.hide();
+        transitions.clear();
+        positionTrails.clearTrail();
+        routeLinesView.clear();
+        onRouteUpdate([], new Box());
+        onRouteDistance(0);
+        renderer.flush();
+    }
+    function destroy() {
+        clearRoute();
+        currentPosition = null;
+        renderer.destroy();
+    }
+    return { setRoute, onPositionChanged, onFloorChanged, shouldReroute, clearRoute, destroy };
+}

package/dist/runtime/endpointView.d.ts

@@ -0,0 +1,20 @@
+import { type RouteEndpoint, type RoutePoint } from '../core/index.js';
+import { type WayfindingRenderer } from '../renderer/index.js';
+import { type FloorContext, type IconProvider } from './types.js';
+interface EndpointView {
+    /**
+     * Place source/destination icons. `snapped` — the live CP is currently on the route, so its
+     *  source shows greyed-out. A kiosk anchor (off-graph origin that isn't the CP) stays hidden;
+     *  everything else (booth, CP off-route, no live CP) shows full-colour.
+     */
+    place(from: RouteEndpoint, to: RouteEndpoint, visibleRoutePoints: readonly RoutePoint[], snapped: boolean): void;
+    hide(): void;
+}
+export declare function createEndpointView({ renderer, iconProvider, floorContext, layer, }: {
+    renderer: Pick<WayfindingRenderer, 'setIcon'>;
+    iconProvider: Pick<IconProvider, 'getIcon'>;
+    floorContext: Pick<FloorContext, 'isLayerVisible'>;
+    layer: string;
+}): EndpointView;
+export {};
+//# sourceMappingURL=endpointView.d.ts.map

package/dist/runtime/endpointView.js

@@ -0,0 +1,40 @@
+import { CURRENT_POSITION_POINT_ID } from './positionView.js';
+function isSourceIconHidden(from, onFloor) {
+    // Hide only a kiosk anchor — an off-graph origin that isn't the live current position.
+    return !onFloor || (!from.bounds && from.id !== CURRENT_POSITION_POINT_ID);
+}
+export function createEndpointView({ renderer, iconProvider, floorContext, layer, }) {
+    return {
+        place(from, to, visibleRoutePoints, snapped) {
+            if (!visibleRoutePoints.length)
+                return;
+            const fromOnFloor = floorContext.isLayerVisible(from.layer);
+            const toOnFloor = floorContext.isLayerVisible(to.layer);
+            const sourcePosition = visibleRoutePoints[0];
+            const destPosition = visibleRoutePoints[visibleRoutePoints.length - 1];
+            const sourceInactive = from.id === CURRENT_POSITION_POINT_ID && snapped;
+            renderer.setIcon('source', {
+                canvas: iconProvider.getIcon(sourceInactive ? 'source_inactive' : 'source').canvas,
+                layer,
+                x: sourcePosition.x,
+                y: sourcePosition.y,
+                hidden: isSourceIconHidden(from, fromOnFloor),
+                dimmed: !fromOnFloor,
+                cardinalSnap: true,
+            });
+            renderer.setIcon('destination', {
+                canvas: iconProvider.getIcon('destination').canvas,
+                layer,
+                x: destPosition.x,
+                y: destPosition.y,
+                hidden: !toOnFloor || !to.bounds,
+                dimmed: !toOnFloor,
+                cardinalSnap: true,
+            });
+        },
+        hide() {
+            renderer.setIcon('source', null);
+            renderer.setIcon('destination', null);
+        },
+    };
+}

package/dist/runtime/getRouteLines.d.ts

@@ -0,0 +1,19 @@
+import { type RouteEndpoint, type RouteLine, type WayfindingEngine } from '../core/index.js';
+/**
+ * Choose between `engine.buildRoute` and `engine.buildWaypointsRoute` based on
+ * whether intermediate waypoints are supplied, and return the resulting route lines.
+ * @param root0
+ * @param root0.engine
+ * @param root0.from
+ * @param root0.to
+ * @param root0.waypoints
+ * @param root0.accessible
+ */
+export declare function getRouteLines({ engine, from, to, waypoints, accessible, }: {
+    readonly engine: WayfindingEngine;
+    readonly from: RouteEndpoint;
+    readonly to: RouteEndpoint;
+    readonly waypoints?: readonly RouteEndpoint[];
+    readonly accessible: boolean;
+}): RouteLine[];
+//# sourceMappingURL=getRouteLines.d.ts.map

package/dist/runtime/getRouteLines.js

@@ -0,0 +1,16 @@
+/**
+ * Choose between `engine.buildRoute` and `engine.buildWaypointsRoute` based on
+ * whether intermediate waypoints are supplied, and return the resulting route lines.
+ * @param root0
+ * @param root0.engine
+ * @param root0.from
+ * @param root0.to
+ * @param root0.waypoints
+ * @param root0.accessible
+ */
+export function getRouteLines({ engine, from, to, waypoints, accessible, }) {
+    if (waypoints?.length) {
+        return engine.buildWaypointsRoute([from, ...waypoints, to], { accessible }).lines;
+    }
+    return engine.buildRoute(from, to, { accessible }).lines;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+export { createWayfindingRuntime } from './createWayfindingRuntime.js';
+export { CURRENT_POSITION_POINT_ID } from './positionView.js';
+export type { FloorContext, IconAsset, IconName, IconProvider, LayerNames, PositionInput, SetRouteInput, WayfindingRuntime, WayfindingRuntimeConfig, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,2 @@
+export { createWayfindingRuntime } from './createWayfindingRuntime.js';
+export { CURRENT_POSITION_POINT_ID } from './positionView.js';

package/dist/runtime/positionTrailView.d.ts

@@ -0,0 +1,52 @@
+import { type RouteEndpoint, type RouteLine, type RoutePoint, type RouteSnapResult } from '../core/index.js';
+import type { WayfindingRenderer } from '../renderer/index.js';
+import type { TrailView } from './trailView.js';
+import type { FloorContext, IconProvider, PositionInput } from './types.js';
+/**
+ * Snapshot of the visible route the position-trail view operates on. The runtime computes it
+ * (visibility filtering, route-points derivation) and passes it in so the view stays free of
+ * route-state knowledge.
+ */
+export interface RouteSnapshot {
+    readonly from: RouteEndpoint;
+    readonly to: RouteEndpoint;
+    readonly routePoints: readonly RoutePoint[];
+    readonly visibleLines: readonly RouteLine[];
+}
+/**
+ * Owns the user-position icon and the single off-graph trail slot. The runtime decides which end of
+ * the route needs a trail (kiosk FROM, kiosk TO, or off-route CP FROM — never both at once in
+ * practice) and passes the corresponding `tip` + `anchor` here.
+ */
+interface PositionTrailView {
+    /** Place the position icon at the raw position. */
+    placeIcon(position: PositionInput): void;
+    /** Hide the position icon. */
+    hideIcon(): void;
+    /**
+     * Snap the position to `routeLines` (caller-provided — typically the full non-virtual route
+     * across all floors) and place the position icon at the snap point or at the raw position.
+     * Returns the snap result; the trail is **not** touched — call `setTrail` separately.
+     *
+     * `routeLines` is decoupled from `route.visibleLines` so the snap stays correct regardless of
+     * which floor is currently selected in the UI.
+     */
+    applyToRoute(position: PositionInput, route: RouteSnapshot, routeLines: readonly RouteLine[]): RouteSnapResult;
+    /**
+     * Draw the trail from `tip` (a route's graph endpoint) to `anchor` (the off-graph point).
+     *  Passing either as null hides the trail.
+     */
+    setTrail(tip: RoutePoint | null, anchor: RoutePoint | null): void;
+    /** Clear the trail slot (does not touch the icon). */
+    clearTrail(): void;
+}
+export declare function createPositionTrailView({ renderer, iconProvider, floorContext, trails, iconLayer, snapThreshold, }: {
+    renderer: Pick<WayfindingRenderer, 'setIcon'>;
+    iconProvider: Pick<IconProvider, 'getIcon'>;
+    floorContext: Pick<FloorContext, 'isLayerVisible'>;
+    trails: TrailView;
+    iconLayer: string;
+    snapThreshold: number;
+}): PositionTrailView;
+export {};
+//# sourceMappingURL=positionTrailView.d.ts.map

package/dist/runtime/positionTrailView.js

@@ -0,0 +1,35 @@
+import { createPositionView } from './positionView.js';
+import { snapPositionToRoute } from './snapPositionToRoute.js';
+const TRAIL_SLOT = 'trail';
+export function createPositionTrailView({ renderer, iconProvider, floorContext, trails, iconLayer, snapThreshold, }) {
+    const positionIcon = createPositionView({ renderer, iconProvider, layer: iconLayer });
+    return {
+        placeIcon(position) {
+            const hidden = !floorContext.isLayerVisible(position.layer);
+            positionIcon.place(position, hidden);
+        },
+        hideIcon() {
+            positionIcon.hide();
+        },
+        applyToRoute(position, route, routeLines) {
+            const snap = snapPositionToRoute(position, routeLines, route.from, route.to, snapThreshold);
+            const hidden = !floorContext.isLayerVisible(position.layer);
+            if (snap.snapped) {
+                positionIcon.place({ ...position, x: snap.snappedPoint.x, y: snap.snappedPoint.y }, hidden);
+            }
+            else {
+                positionIcon.place(position, hidden);
+            }
+            return snap;
+        },
+        setTrail(tip, anchor) {
+            if (tip && anchor)
+                trails.place(TRAIL_SLOT, tip, anchor);
+            else
+                trails.clear(TRAIL_SLOT);
+        },
+        clearTrail() {
+            trails.clear(TRAIL_SLOT);
+        },
+    };
+}