@expofp/wayfinding 3.26.0 → 3.27.0

package/dist/createWayfinding.d.ts

@@ -50,8 +50,8 @@ export interface Wayfinding {
     applyScale(scale: number): void;
     /** Forward a camera-roll change; re-orients cardinal-snap icons and commits. */
     applyRoll(angle: number): void;
-    /** Forward a pointer click (already picked scene defs); fires icon `onClick`. */
-    handleClick(defs: readonly RenderableDef[]): void;
+    /** Forward a pointer click (already picked scene defs); fires icon `onClick`, and reports whether one claimed it. */
+    handleClick(defs: readonly RenderableDef[]): boolean;
     /** Forward a pointer move (already picked scene defs); `true` over a clickable icon. */
     handleHover(defs: readonly RenderableDef[]): boolean;
     /**

package/dist/createWayfinding.js

@@ -35,8 +35,17 @@ export function createWayfinding(config) {
         shouldReroute: (position) => runtime.shouldReroute(position),
         applyScale: (scale) => renderDefs(renderer.applyScale(scale)),
         applyRoll: (angle) => renderDefs(renderer.applyRoll(angle)),
-        handleClick: (defs) => renderer.handleClick(defs),
-        handleHover: (defs) => renderer.handleHover(defs),
+        // The renderer answers per def (it holds a def → icon map, so a pointer event
+        // costs a lookup rather than a scan); the picked list is walked here, stopping
+        // at the first icon that claims the click.
+        handleClick: (defs) => {
+            for (const def of defs) {
+                if (renderer.handleClick(def))
+                    return true;
+            }
+            return false;
+        },
+        handleHover: (defs) => defs.some((def) => renderer.handleHover(def)),
         setIcon: (name, config, key) => renderer.setIcon(name, config, key),
         flush: () => renderer.flush(),
         destroy: () => runtime.destroy(),

package/dist/renderer/createWayfindingRenderer.d.ts

@@ -4,11 +4,12 @@ import type { RendererPort, WayfindingRenderer, WayfindingRendererConfig } from
  * together {@link LayerManager}, {@link IconManager}, {@link TrailManager},
  * and {@link RouteLineManager}.
  *
- * Exposes `applyScale`/`applyRoll`/`handleClick`/`handleHover` for the app glue
- * to drive from engine events.
- * @param rendererPort
- * @param config
- * @throws If `rendererPort.getLayers()` throws (e.g. the scene is not started).
+ * Exposes `handleClick`/`handleHover` for the app glue to drive from pointer events, and
+ * `applyScale`/`applyRoll` for the deprecated imperative path, which has no handler dispatch of its
+ * own (see {@link WayfindingRenderer.applyScale}).
+ * @param port - The scene layers, def factories and commit function.
+ * @param config - Optional color overrides.
+ * @returns The renderer.
  */
-export declare function createWayfindingRenderer(rendererPort: RendererPort, config?: WayfindingRendererConfig): WayfindingRenderer;
+export declare function createWayfindingRenderer(port: RendererPort, config?: WayfindingRendererConfig): WayfindingRenderer;
 //# sourceMappingURL=createWayfindingRenderer.d.ts.map

package/dist/renderer/createWayfindingRenderer.js

@@ -12,27 +12,31 @@ const DEFAULT_COLORS = {
  * together {@link LayerManager}, {@link IconManager}, {@link TrailManager},
  * and {@link RouteLineManager}.
  *
- * Exposes `applyScale`/`applyRoll`/`handleClick`/`handleHover` for the app glue
- * to drive from engine events.
- * @param rendererPort
- * @param config
- * @throws If `rendererPort.getLayers()` throws (e.g. the scene is not started).
+ * Exposes `handleClick`/`handleHover` for the app glue to drive from pointer events, and
+ * `applyScale`/`applyRoll` for the deprecated imperative path, which has no handler dispatch of its
+ * own (see {@link WayfindingRenderer.applyScale}).
+ * @param port - The scene layers, def factories and commit function.
+ * @param config - Optional color overrides.
+ * @returns The renderer.
  */
-export function createWayfindingRenderer(rendererPort, config = {}) {
+export function createWayfindingRenderer(port, config = {}) {
     const colors = { ...DEFAULT_COLORS, ...config.colors };
-    const layerManager = createLayerManager(rendererPort);
-    const iconManager = createIconManager(layerManager, rendererPort);
-    const trailManager = createTrailManager(layerManager, rendererPort);
-    const routeLineManager = createRouteLineManager(layerManager, colors, rendererPort);
+    const layerManager = createLayerManager(port);
+    const iconManager = createIconManager(layerManager, port);
+    const trailManager = createTrailManager(layerManager, port);
+    const routeLineManager = createRouteLineManager(layerManager, colors, port);
     const wfRenderer = {
         setIcon: (...args) => iconManager.setIcon(...args),
         clearIcons: (...args) => iconManager.clearIcons(...args),
         setTrail: (...args) => trailManager.setTrail(...args),
         setRouteLines: (...args) => routeLineManager.setRouteLines(...args),
-        applyScale: (scale) => [...iconManager.applyScale(scale), ...trailManager.applyScale(scale)],
+        applyScale: (pixelSize) => [
+            ...iconManager.applyScale(pixelSize),
+            ...trailManager.applyScale(pixelSize),
+        ],
         applyRoll: (cameraAngle) => iconManager.applyRoll(cameraAngle),
-        handleClick: (defs) => iconManager.handleClick(defs),
-        handleHover: (defs) => iconManager.handleHover(defs),
+        handleClick: (def) => iconManager.handleClick(def),
+        handleHover: (def) => iconManager.handleHover(def),
         clearRoute() {
             routeLineManager.clearLines();
             trailManager.destroy();

package/dist/renderer/iconManager.d.ts

@@ -1,6 +1,20 @@
-import type { RenderableDef } from '@expofp/renderer';
+import type { ImageDef, RenderableDef } from '@expofp/renderer';
 import type { LayerManager } from './layerManager.js';
 import type { IconConfig, RendererPort } from './types.js';
+/**
+ * Lays one wayfinding icon out for a new pixel size: it holds its on-screen size, so its bounds are
+ * the source's pixel dimensions times the pixel size, about its own centre — rotation and elevation
+ * untouched.
+ *
+ * The **only** writer of an icon's bounds size, which is what lets everything else here write logical
+ * fields alone and never track a scale. One function for every icon in the plan, reached through
+ * each icon's own `onScale` closure and called directly by `applyScale`.
+ * @param def - The icon to lay out.
+ * @param pixelSize - Plan units per device pixel.
+ * @returns The def when it resized, nothing when the size was already right — a settled camera costs
+ *   no slot writes.
+ */
+export declare function rescaleIcon(def: ImageDef, pixelSize: number): readonly RenderableDef[] | undefined;
 /**
  * Manages `ImageDef` icons in the scene graph.
  *
@@ -20,20 +34,21 @@ export interface IconManager {
     hideAll(): void;
     /** Clear internal state. */
     destroy(): void;
-    /** Recompute bounds of all visible icons for `scale`; returns changed defs. */
-    applyScale(scale: number): RenderableDef[];
+    /** Lay every visible icon out for `pixelSize`; returns changed defs. See {@link rescaleIcon}. */
+    applyScale(pixelSize: number): RenderableDef[];
     /** Apply camera roll to cardinal-snap icons; returns changed defs. */
     applyRoll(cameraAngle: number): RenderableDef[];
-    /** Fire the first hit clickable icon's `onClick` from already-picked defs. */
-    handleClick(defs: readonly RenderableDef[]): void;
-    /** Whether a clickable icon is under the already-picked defs. */
-    handleHover(defs: readonly RenderableDef[]): boolean;
+    /** Fire a clicked icon's `onClick`; returns whether the def was one. */
+    handleClick(def: RenderableDef): boolean;
+    /** Whether a def is a clickable icon. */
+    handleHover(def: RenderableDef): boolean;
 }
 /**
  * Create an {@link IconManager} that places `ImageDef` icons into layers
  * managed by the given {@link LayerManager}.
- * @param layerManager
- * @param rendererPort
+ * @param layerManager - Where icons are placed and dirt is tracked.
+ * @param port - Supplies the def factories; see {@link RendererPort}.
+ * @returns The manager.
  */
-export declare function createIconManager(layerManager: LayerManager, rendererPort: RendererPort): IconManager;
+export declare function createIconManager(layerManager: LayerManager, port: RendererPort): IconManager;
 //# sourceMappingURL=iconManager.d.ts.map

package/dist/renderer/iconManager.js

@@ -1,14 +1,43 @@
 import { Rect } from '@expofp/geometry';
+/**
+ * Lays one wayfinding icon out for a new pixel size: it holds its on-screen size, so its bounds are
+ * the source's pixel dimensions times the pixel size, about its own centre — rotation and elevation
+ * untouched.
+ *
+ * The **only** writer of an icon's bounds size, which is what lets everything else here write logical
+ * fields alone and never track a scale. One function for every icon in the plan, reached through
+ * each icon's own `onScale` closure and called directly by `applyScale`.
+ * @param def - The icon to lay out.
+ * @param pixelSize - Plan units per device pixel.
+ * @returns The def when it resized, nothing when the size was already right — a settled camera costs
+ *   no slot writes.
+ */
+export function rescaleIcon(def, pixelSize) {
+    const bounds = def.bounds;
+    const source = def.source;
+    const width = source.width * pixelSize;
+    const height = source.height * pixelSize;
+    if (bounds.size.x === width && bounds.size.y === height)
+        return undefined;
+    bounds.set(bounds.center.x, bounds.center.y, width, height, bounds.rotation, bounds.elevation);
+    return [def];
+}
 /**
  * Create an {@link IconManager} that places `ImageDef` icons into layers
  * managed by the given {@link LayerManager}.
- * @param layerManager
- * @param rendererPort
+ * @param layerManager - Where icons are placed and dirt is tracked.
+ * @param port - Supplies the def factories; see {@link RendererPort}.
+ * @returns The manager.
  */
-export function createIconManager(layerManager, rendererPort) {
+export function createIconManager(layerManager, port) {
     const icons = new Map();
     const iconKeysByName = new Map();
     const keyToName = new Map();
+    /**
+     * The reverse of {@link icons}: a pointer event names the def that was hit, and this is what turns
+     * it back into the icon that owns it — rather than scanning every record per event.
+     */
+    const iconsByDef = new Map();
     function composeKey(name, key) {
         return key === undefined ? name : `${name}#${key}`;
     }
@@ -32,18 +61,37 @@ export function createIconManager(layerManager, rendererPort) {
     }
     function createIcon(iconKey, name, cfg) {
         const layer = layerManager.touchLayer(cfg.layer);
-        const scale = rendererPort.getScale();
-        const def = rendererPort.createImageDef(cfg.canvas, new Rect({ x: cfg.x, y: cfg.y }, { x: cfg.canvas.width * scale, y: cfg.canvas.height * scale }, cfg.rotation), { hidden: cfg.hidden ?? false, dim: cfg.dimmed ?? false, origin: cfg.origin });
+        // Size zero on purpose: an icon's size is only expressible in terms of the current pixel size, and
+        // `rescaleIcon` is its one writer. The renderer lays a def out as it registers, hidden or not, so
+        // it is never drawn at this placeholder.
+        const def = port.createImageDef(cfg.canvas, new Rect({ x: cfg.x, y: cfg.y }, ZERO, cfg.rotation), {
+            hidden: cfg.hidden ?? false,
+            dim: cfg.dimmed ? 1 : 0,
+            origin: cfg.origin,
+        });
+        def.onScale = ({ pixelSize }) => rescaleIcon(def, pixelSize);
+        // Cardinal-snap icons also declare the roll rule, so a renderer that dispatches def handlers
+        // keeps them square to the screen; `applyRoll` drives the same arithmetic for the path that
+        // dispatches nothing.
+        if (cfg.cardinalSnap) {
+            def.onRoll = ({ roll }) => {
+                const bounds = def.bounds;
+                const delta = port.getRotation(roll, bounds.rotation);
+                if (delta === undefined)
+                    return undefined;
+                bounds.rotate(delta, bounds);
+                return [def];
+            };
+        }
         layer.children.push(def);
         const record = {
             imageDef: def,
             layerName: cfg.layer,
             cardinalSnap: cfg.cardinalSnap ?? false,
-            center: { x: cfg.x, y: cfg.y },
-            rotation: cfg.rotation,
             callback: cfg.onClick ?? null,
         };
         icons.set(iconKey, record);
+        iconsByDef.set(def, record);
         trackKey(name, iconKey);
         return record;
     }
@@ -55,6 +103,7 @@ export function createIconManager(layerManager, rendererPort) {
             oldChildren.splice(idx, 1);
         layerManager.touchedLayers.set(record.layerName, oldLayer);
         icons.delete(iconKey);
+        iconsByDef.delete(record.imageDef);
         untrackKey(iconKey);
         createIcon(iconKey, name, cfg);
     }
@@ -66,25 +115,35 @@ export function createIconManager(layerManager, rendererPort) {
             recreateIcon(iconKey, name, record, cfg);
             return;
         }
-        const scale = rendererPort.getScale();
-        record.imageDef.bounds = rendererPort.rectToRenderer(new Rect({ x: cfg.x, y: cfg.y }, { x: cfg.canvas.width * scale, y: cfg.canvas.height * scale }, cfg.rotation));
+        // Logical fields only — where the icon is, which way it faces. The size it already carries is
+        // correct for the camera it was laid out at, and moving an icon does not change that.
+        const bounds = record.imageDef.bounds;
+        bounds.set(cfg.x, cfg.y, bounds.size.x, bounds.size.y, cfg.rotation ?? 0, bounds.elevation);
         record.imageDef.hidden = cfg.hidden ?? false;
-        record.imageDef.dim = cfg.dimmed ?? false;
-        record.center = { x: cfg.x, y: cfg.y };
-        record.rotation = cfg.rotation;
+        record.imageDef.dim = cfg.dimmed ? 1 : 0;
         record.callback = cfg.onClick ?? null;
-        layerManager.touchLayer(cfg.layer);
+        layerManager.touchDef(record.imageDef);
+    }
+    /**
+     * Hides one icon and records that its def changed.
+     *
+     * The def, not the layer that holds it: the layer's children are unchanged, so a renderer
+     * reconciling the layer would find nothing to do and never reach this instance. That is exactly
+     * how a cleared route left its endpoint pins on screen.
+     * @param record - The icon to hide.
+     */
+    function hideIcon(record) {
+        record.imageDef.hidden = true;
+        record.callback = null;
+        layerManager.touchDef(record.imageDef);
     }
     return {
         setIcon(name, cfg, key) {
             const iconKey = composeKey(name, key);
             if (cfg === null) {
                 const record = icons.get(iconKey);
-                if (record) {
-                    record.imageDef.hidden = true;
-                    record.callback = null;
-                    layerManager.touchLayer(record.layerName);
-                }
+                if (record)
+                    hideIcon(record);
                 return;
             }
             const existing = icons.get(iconKey);
@@ -101,33 +160,29 @@ export function createIconManager(layerManager, rendererPort) {
                     continue;
                 for (const iconKey of nameKeys) {
                     const record = icons.get(iconKey);
-                    if (record) {
-                        record.imageDef.hidden = true;
-                        record.callback = null;
-                        layerManager.touchLayer(record.layerName);
-                    }
+                    if (record)
+                        hideIcon(record);
                 }
             }
         },
         hideAll() {
-            for (const record of icons.values()) {
-                record.imageDef.hidden = true;
-                record.callback = null;
-                layerManager.touchedLayers.set(record.layerName, layerManager.resolveLayer(record.layerName));
-            }
+            for (const record of icons.values())
+                hideIcon(record);
         },
         destroy() {
             icons.clear();
+            iconsByDef.clear();
             iconKeysByName.clear();
             keyToName.clear();
         },
-        applyScale(scale) {
+        applyScale(pixelSize) {
             const defs = [];
             for (const record of icons.values()) {
                 if (record.imageDef.hidden)
                     continue;
-                record.imageDef.bounds = rendererPort.rectToRenderer(new Rect(record.center, { x: record.imageDef.source.width * scale, y: record.imageDef.source.height * scale }, record.rotation));
-                defs.push(record.imageDef);
+                const changed = rescaleIcon(record.imageDef, pixelSize);
+                if (changed)
+                    defs.push(...changed);
             }
             return defs;
         },
@@ -136,31 +191,27 @@ export function createIconManager(layerManager, rendererPort) {
             for (const record of icons.values()) {
                 if (!record.cardinalSnap)
                     continue;
-                const currentRotation = record.rotation ?? 0;
-                const delta = rendererPort.getRotation(cameraAngle, currentRotation);
+                const bounds = record.imageDef.bounds;
+                const delta = port.getRotation(cameraAngle, bounds.rotation);
                 if (delta === undefined)
                     continue;
-                record.rotation = currentRotation + delta;
-                record.imageDef.bounds.rotation = record.rotation;
+                bounds.rotate(delta, bounds);
                 defs.push(record.imageDef);
             }
             return defs;
         },
-        handleClick(defs) {
-            for (const record of icons.values()) {
-                if (record.callback && !record.imageDef.hidden && defs.includes(record.imageDef)) {
-                    record.callback();
-                    return;
-                }
-            }
+        handleClick(def) {
+            const record = iconsByDef.get(def);
+            if (!record?.callback || record.imageDef.hidden)
+                return false;
+            record.callback();
+            return true;
         },
-        handleHover(defs) {
-            for (const record of icons.values()) {
-                if (record.callback && !record.imageDef.hidden && defs.includes(record.imageDef)) {
-                    return true;
-                }
-            }
-            return false;
+        handleHover(def) {
+            const record = iconsByDef.get(def);
+            return Boolean(record?.callback) && !record?.imageDef.hidden;
         },
     };
 }
+/** The size a new icon is created at, before its handler gives it a real one. */
+const ZERO = { x: 0, y: 0 };

package/dist/renderer/layerManager.d.ts

@@ -1,27 +1,38 @@
-import type { LayerDef } from '@expofp/renderer';
+import type { LayerDef, RenderableDef } from '@expofp/renderer';
 import type { RendererPort } from './types.js';
 /**
  * Manages scene layer resolution, caching, dirty-tracking, and flush.
  *
- * Layers are resolved by name from `rendererPort.getLayers()` and cached. `touchLayer`
- * marks a layer as dirty; `flush` commits all dirty layers via `rendererPort.update`
- * in a single call.
+ * Layers are resolved by name from the scene layers handed in and cached. `touchLayer` marks a
+ * layer's **membership** as dirty and `touchDef` marks one def's **fields**; `flush` commits both
+ * through the injected `update` in a single call.
+ *
+ * The distinction is not cosmetic. A renderer reconciles a layer's children but writes a def's slot,
+ * so a def whose `hidden` or `bounds` moved is only drawn correctly if the def itself is committed —
+ * updating the layer that holds it reconciles a membership that did not change and reaches the def's
+ * instance not at all.
  */
 export interface LayerManager {
-    /** Layers modified since the last {@link flush}. */
+    /** Layers whose membership changed since the last {@link flush}. */
     readonly touchedLayers: Map<string, LayerDef>;
     /** Resolve a layer by name (cached). Throws if not found. */
     resolveLayer(name: string): LayerDef;
-    /** Resolve a layer and mark it as dirty for the next {@link flush}. */
+    /** Resolve a layer and mark its membership as dirty for the next {@link flush}. */
     touchLayer(name: string): LayerDef;
-    /** Commit all dirty layers to `RendererService` and clear the dirty set. */
+    /**
+     * Mark one def's fields as dirty for the next {@link flush}.
+     * @param def - The def whose fields were mutated.
+     */
+    touchDef(def: RenderableDef): void;
+    /** Commit everything dirty and clear the dirty sets. */
     flush(): void;
-    /** Clear caches and dirty set. */
+    /** Clear caches and dirty sets. */
     destroy(): void;
 }
 /**
- * Create a {@link LayerManager} bound to the given {@link RendererPort}.
- * @param rendererPort
+ * Create a {@link LayerManager} over the scene layers the caller resolved.
+ * @param port - The scene layers and the commit function; see {@link RendererPort}.
+ * @returns The manager.
  */
-export declare function createLayerManager(rendererPort: RendererPort): LayerManager;
+export declare function createLayerManager(port: RendererPort): LayerManager;
 //# sourceMappingURL=layerManager.d.ts.map

package/dist/renderer/layerManager.js

@@ -1,11 +1,13 @@
 /**
- * Create a {@link LayerManager} bound to the given {@link RendererPort}.
- * @param rendererPort
+ * Create a {@link LayerManager} over the scene layers the caller resolved.
+ * @param port - The scene layers and the commit function; see {@link RendererPort}.
+ * @returns The manager.
  */
-export function createLayerManager(rendererPort) {
-    const allLayers = rendererPort.getLayers();
+export function createLayerManager(port) {
+    const allLayers = port.layers;
     const layerCache = new Map();
     const touchedLayers = new Map();
+    const touchedDefs = new Set();
     return {
         touchedLayers,
         resolveLayer(name) {
@@ -23,17 +25,22 @@ export function createLayerManager(rendererPort) {
             touchedLayers.set(name, layer);
             return layer;
         },
+        touchDef(def) {
+            touchedDefs.add(def);
+        },
         flush() {
-            if (touchedLayers.size === 0)
+            if (touchedLayers.size === 0 && touchedDefs.size === 0)
                 return;
             for (const layer of touchedLayers.values()) {
                 layer.children = [...layer.children];
             }
-            rendererPort.update(...touchedLayers.values());
+            port.update(...touchedLayers.values(), ...touchedDefs);
             touchedLayers.clear();
+            touchedDefs.clear();
         },
         destroy() {
             touchedLayers.clear();
+            touchedDefs.clear();
             layerCache.clear();
         },
     };

package/dist/renderer/lineAnimation.d.ts

@@ -1,11 +1,25 @@
-import type { Point2Like } from '@expofp/geometry';
 import type { LineDef } from '@expofp/renderer';
 export interface AnimationHandle {
     stop: () => void;
     getProgress: () => number;
 }
-export type AnimatedLineDef = Omit<LineDef, 'points'> & {
-    points: [Point2Like, Point2Like];
-};
-export declare function animateLineSegments(lineSegments: AnimatedLineDef[], callback: (segment: AnimatedLineDef, segmentIndex: number, reset: boolean) => void, getScale: () => number, startProgress?: number): AnimationHandle | undefined;
+/**
+ * Runs the chase animation over route segments that are already in the scene, **moving them in
+ * place**: the segments behind the head are drawn whole, the one under it is drawn part-way, and the
+ * ones ahead are hidden.
+ *
+ * The membership never changes, which is the point. Rebuilding the layer's children every frame —
+ * with a fresh def for the partial segment — remounted an instance and churned a batch slot sixty
+ * times a second, and the overlay lost everything but the newest chunk. `LineDef.points` is re-read
+ * on every update precisely so an animation can move a line instead of replacing it.
+ *
+ * Only what actually changed is reported: normally the single segment under the head, and every
+ * segment once per lap, when the chase wraps.
+ * @param segments - The defs to animate, in route order. Their `points` are moved in place.
+ * @param onChange - Called with the defs that changed, for the caller to commit.
+ * @param getPixelSize - Plan units per device pixel, which the speed is modulated by.
+ * @param startProgress - Where in the lap to resume, in `[0, 1)`.
+ * @returns A handle, or nothing when there is no route to animate.
+ */
+export declare function animateLineSegments(segments: LineDef[], onChange: (changed: readonly LineDef[]) => void, getPixelSize: () => number, startProgress?: number): AnimationHandle | undefined;
 //# sourceMappingURL=lineAnimation.d.ts.map

package/dist/renderer/lineAnimation.js

@@ -1,15 +1,48 @@
-export function animateLineSegments(lineSegments, callback, getScale, startProgress = 0) {
+/** How much of a segment is drawn: the whole of it, or none. */
+const WHOLE = 1;
+const NOTHING = 0;
+/**
+ * Runs the chase animation over route segments that are already in the scene, **moving them in
+ * place**: the segments behind the head are drawn whole, the one under it is drawn part-way, and the
+ * ones ahead are hidden.
+ *
+ * The membership never changes, which is the point. Rebuilding the layer's children every frame —
+ * with a fresh def for the partial segment — remounted an instance and churned a batch slot sixty
+ * times a second, and the overlay lost everything but the newest chunk. `LineDef.points` is re-read
+ * on every update precisely so an animation can move a line instead of replacing it.
+ *
+ * Only what actually changed is reported: normally the single segment under the head, and every
+ * segment once per lap, when the chase wraps.
+ * @param segments - The defs to animate, in route order. Their `points` are moved in place.
+ * @param onChange - Called with the defs that changed, for the caller to commit.
+ * @param getPixelSize - Plan units per device pixel, which the speed is modulated by.
+ * @param startProgress - Where in the lap to resume, in `[0, 1)`.
+ * @returns A handle, or nothing when there is no route to animate.
+ */
+export function animateLineSegments(segments, onChange, getPixelSize, startProgress = 0) {
     let currentSegmentIndex = 0;
     let segmentProgress = 0;
     let lastTimestamp = null;
     let animationFrameId = null;
-    if (!lineSegments.length)
+    if (!segments.length)
         return;
-    const segmentLengths = lineSegments.map((s) => {
-        const dx = s.points[1].x - s.points[0].x;
-        const dy = s.points[1].y - s.points[0].y;
+    // Captured before anything is moved: from here on a def's own `p1` is wherever the chase left it.
+    // Copied rather than aliased, since the def's `points` is what gets replaced; `elevation` rides
+    // along so a segment on a raised plane does not drop to the floor the first time it is redrawn.
+    const ends = segments.map((segment) => ({
+        p0: { x: segment.points.p0.x, y: segment.points.p0.y },
+        p1: { x: segment.points.p1.x, y: segment.points.p1.y },
+        elevation: segment.points.elevation,
+    }));
+    const segmentLengths = ends.map((end) => {
+        const dx = end.p1.x - end.p0.x;
+        const dy = end.p1.y - end.p0.y;
         return Math.sqrt(dx * dx + dy * dy);
     });
+    /** The fraction each segment is currently drawn at; `-1` until it has been written even once. */
+    const drawn = segments.map(() => -1);
+    /** What the frame being rendered moved, refilled per frame so a frame allocates nothing. */
+    const changed = [];
     const totalLength = segmentLengths.reduce((a, b) => a + b, 0);
     // A zero-length route would spin the per-frame while-loop forever.
     if (!totalLength)
@@ -33,51 +66,79 @@ export function animateLineSegments(lineSegments, callback, getScale, startProgr
             }
         }
     }
-    function updateSegment(segment, progress) {
-        const start = segment.points[0];
-        const end = segment.points[1];
-        const dx = end.x - start.x;
-        const dy = end.y - start.y;
-        const length = Math.sqrt(dx * dx + dy * dy);
-        const t = Math.min(progress / length, 1);
-        return {
-            points: [
-                { x: start.x, y: start.y },
-                { x: start.x + dx * t, y: start.y + dy * t },
-            ],
-            color: segment.color,
-            width: segment.width,
-        };
+    /**
+     * Brings one segment to a fraction of its length — hidden at `0`, whole at `1`, cut short between
+     * — and records it as changed if that moved it. A segment already drawn at this fraction costs
+     * nothing, which is what keeps a frame to the one segment under the head.
+     *
+     * `points` is replaced rather than mutated, because a `LineLike`'s coordinates are readonly. The
+     * def stays the same object throughout, which is all the renderer keys anything on.
+     * @param index - The segment to draw.
+     * @param fraction - How much of it to draw, in `[0, 1]`.
+     */
+    function draw(index, fraction) {
+        if (drawn[index] === fraction)
+            return;
+        drawn[index] = fraction;
+        const segment = segments[index];
+        const end = ends[index];
+        segment.hidden = fraction <= NOTHING;
+        if (!segment.hidden) {
+            const { p0, p1 } = end;
+            segment.points =
+                fraction >= WHOLE
+                    ? end
+                    : {
+                        p0,
+                        p1: { x: p0.x + (p1.x - p0.x) * fraction, y: p0.y + (p1.y - p0.y) * fraction },
+                        elevation: end.elevation,
+                    };
+        }
+        changed.push(segment);
+    }
+    /**
+     * Brings every segment to the state the head's position implies: everything behind it is whole,
+     * the one under it is part-drawn, everything ahead of it is empty.
+     */
+    function render() {
+        changed.length = 0;
+        const head = currentSegmentIndex;
+        for (let i = 0; i < head; i++)
+            draw(i, WHOLE);
+        // A zero-length segment divides to `Infinity` and so is whole the moment the head reaches it.
+        draw(head, Math.min(segmentProgress / segmentLengths[head], WHOLE));
+        for (let i = head + 1; i < segments.length; i++)
+            draw(i, NOTHING);
+        if (changed.length)
+            onChange(changed);
     }
     function animate(timestamp) {
         lastTimestamp ??= timestamp;
         const delta = (timestamp - lastTimestamp) / 1000;
         lastTimestamp = timestamp;
-        const scale = getScale();
-        // A detached canvas (host element removed from the DOM on SPA navigation)
-        // reports a bogus ptScale (Infinity on a zero-size canvas). Anything but a
-        // positive finite scale poisons segmentProgress and spins the loop below,
-        // freezing the tab — skip the frame until a usable scale returns.
-        if (!(Number.isFinite(scale) && scale > 0)) {
+        const pixelSize = getPixelSize();
+        // A detached canvas (host element removed from the DOM on SPA navigation) reports a bogus pixel
+        // size (Infinity on a zero-size canvas). Anything but a positive finite value poisons
+        // segmentProgress and spins the loop below, freezing the tab — skip the frame until a usable one
+        // returns.
+        if (!(Number.isFinite(pixelSize) && pixelSize > 0)) {
             animationFrameId = requestAnimationFrame(animate);
             return;
         }
-        const adjustedSpeed = baseSpeed * Math.sqrt(scale);
+        const adjustedSpeed = baseSpeed * Math.sqrt(pixelSize);
         segmentProgress += adjustedSpeed * delta;
         // Keep progress within a single lap. totalLength > 0 is guaranteed above, so
-        // the loop can advance at most lineSegments.length steps — it can never spin,
-        // whatever scale/delta the engine feeds in.
+        // the loop can advance at most segments.length steps — it can never spin,
+        // whatever pixel size/delta the camera feeds in.
         segmentProgress %= totalLength;
         while (segmentProgress >= segmentLengths[currentSegmentIndex]) {
             segmentProgress -= segmentLengths[currentSegmentIndex];
             currentSegmentIndex++;
-            if (currentSegmentIndex >= lineSegments.length) {
+            if (currentSegmentIndex >= segments.length) {
                 currentSegmentIndex = 0;
             }
         }
-        const currentSegment = lineSegments[currentSegmentIndex];
-        const updatedSegment = updateSegment(currentSegment, segmentProgress);
-        callback(updatedSegment, currentSegmentIndex, false);
+        render();
         animationFrameId = requestAnimationFrame(animate);
     }
     function start() {

package/dist/renderer/routeLineManager.d.ts

@@ -36,9 +36,10 @@ export interface RouteLineManager {
 /**
  * Create a {@link RouteLineManager} that renders `LineDef` segments
  * into layers managed by the given {@link LayerManager}.
- * @param layerManager
- * @param colors
- * @param rendererPort
+ * @param layerManager - Where the lines are placed and dirt is tracked.
+ * @param colors - The route palette.
+ * @param port - The commit function the animation ticks through.
+ * @returns The manager.
  */
-export declare function createRouteLineManager(layerManager: LayerManager, colors: RouteColors, rendererPort: RendererPort): RouteLineManager;
+export declare function createRouteLineManager(layerManager: LayerManager, colors: RouteColors, port: RendererPort): RouteLineManager;
 //# sourceMappingURL=routeLineManager.d.ts.map

package/dist/renderer/routeLineManager.js

@@ -1,19 +1,64 @@
-import { animateLineSegments, } from './lineAnimation.js';
+import { animateLineSegments } from './lineAnimation.js';
 /**
  * Create a {@link RouteLineManager} that renders `LineDef` segments
  * into layers managed by the given {@link LayerManager}.
- * @param layerManager
- * @param colors
- * @param rendererPort
+ * @param layerManager - Where the lines are placed and dirt is tracked.
+ * @param colors - The route palette.
+ * @param port - The commit function the animation ticks through.
+ * @returns The manager.
  */
-export function createRouteLineManager(layerManager, colors, rendererPort) {
+export function createRouteLineManager(layerManager, colors, port) {
     let animationHandle = null;
     let lastLinesLayer = null;
     let lastAnimatedLayer = null;
+    /**
+     * The pixel size the chase animation modulates its speed by. Route lines need no layout of their
+     * own — `LineDef.width` is already in screen pixels — so this is the one thing the animated layer's
+     * handler exists to deliver.
+     */
+    let currentPixelSize = 1;
+    /**
+     * Reports the pixel size to the chase animation — the animated-lines layer's `onScale`.
+     *
+     * Lays nothing out and returns nothing, so it never costs a write. It is here because the speed
+     * term reads a scale and there is no other channel that carries one.
+     * @param pixelSize - Plan units per device pixel.
+     */
+    function readPixelSize(pixelSize) {
+        currentPixelSize = pixelSize;
+    }
+    /**
+     * Empties one lines layer, hiding each def in place first.
+     *
+     * The hide is not redundant with the removal. The renderer commits a def write synchronously but
+     * defers a membership sweep — renderer's `useStagedChildren` (`objects/layer/
+     * mount-scheduler.ts`) pipes a layer's children through `useDeferredValue`, so the unmount that
+     * releases the removed instances lands a transition commit later. Lines that were only removed
+     * therefore outlived the route's icons — which `hideIcon` hides in place — by a frame or more,
+     * and the cleared route's line visibly lingered behind its pins. Hiding first puts the whole
+     * teardown in the same synchronous commit; the deferred sweep then releases slots that are
+     * already invisible. Drop the hides if the renderer ever hides departed defs urgently itself
+     * (the place to do it is `useStagedChildren`, where the fresh snapshot and the deferred children
+     * are both at hand).
+     * @param layer - The layer to empty, when it is known yet.
+     */
+    function wipe(layer) {
+        if (!layer)
+            return;
+        for (const def of layer.children) {
+            def.hidden = true;
+            layerManager.touchDef(def);
+        }
+        layer.children = [];
+        layerManager.touchedLayers.set(layer.name, layer);
+    }
     return {
         setRouteLines(passed, remaining, options) {
             const linesLayer = layerManager.touchLayer(options.linesLayer);
             const animatedLayer = layerManager.touchLayer(options.animatedLinesLayer);
+            // Declared here rather than at construction, because this is where the layer is first known.
+            // The `update(layer)` a flush performs is what makes it register under this.
+            animatedLayer.onScale = ({ pixelSize }) => readPixelSize(pixelSize);
             lastLinesLayer = linesLayer;
             lastAnimatedLayer = animatedLayer;
             const reset = options.resetAnimation ?? true;
@@ -24,36 +69,33 @@ export function createRouteLineManager(layerManager, colors, rendererPort) {
                 animationHandle.stop();
                 animationHandle = null;
             }
-            const passedDefs = passed.map((seg) => rendererPort.createLineDef(seg, colors.passed));
-            const remainingDefs = remaining.map((seg) => rendererPort.createLineDef(seg, colors.remaining));
+            const passedDefs = passed.map((seg) => port.createLineDef(seg, colors.passed));
+            const remainingDefs = remaining.map((seg) => port.createLineDef(seg, colors.remaining));
             linesLayer.children = [...passedDefs, ...remainingDefs];
             if (!remainingDefs.length) {
                 animatedLayer.children = [];
                 return;
             }
-            const animatedDefs = remainingDefs.map((def) => ({
-                ...def,
-                color: colors.active,
+            // Built from the segments rather than copied off `remainingDefs`, so the two never share a
+            // `points` object: the chase moves these in place, and the static line beneath must not move
+            // with them. They start hidden, and the animation shows each as the head reaches it.
+            const animatedDefs = remaining.map((seg) => ({
+                ...port.createLineDef(seg, colors.active),
+                hidden: true,
             }));
+            // Mounted once. The chase moves these defs rather than rewriting this array, so no instance is
+            // remounted and no batch slot churns while it runs.
+            animatedLayer.children = animatedDefs;
             animationHandle =
-                animateLineSegments(animatedDefs, (line, idx, justReset) => {
-                    animatedLayer.children = justReset ? [] : [...animatedDefs.slice(0, idx), line];
-                    rendererPort.update(animatedLayer);
-                }, () => rendererPort.getScale(), resumeFrom) ?? null;
+                animateLineSegments(animatedDefs, (changed) => port.update(...changed), () => currentPixelSize, resumeFrom) ?? null;
         },
         clearLines() {
             if (animationHandle) {
                 animationHandle.stop();
                 animationHandle = null;
             }
-            if (lastLinesLayer) {
-                lastLinesLayer.children = [];
-                layerManager.touchedLayers.set(lastLinesLayer.name, lastLinesLayer);
-            }
-            if (lastAnimatedLayer) {
-                lastAnimatedLayer.children = [];
-                layerManager.touchedLayers.set(lastAnimatedLayer.name, lastAnimatedLayer);
-            }
+            wipe(lastLinesLayer);
+            wipe(lastAnimatedLayer);
         },
         destroy() {
             this.clearLines();

package/dist/renderer/trailManager.d.ts

@@ -5,8 +5,10 @@ import type { RendererPort } from './types.js';
 /**
  * Manages named trails of evenly-spaced dots between two points.
  *
- * On camera zoom the app glue calls `applyScale` so dots are recalculated and
- * visual spacing stays constant.
+ * A trail's spacing is fixed in screen pixels, so zooming out does not shrink its dots — it holds
+ * fewer of them. That makes a camera move a **membership** change, which is why the layout rule is
+ * declared on the trail layer rather than on the dots: the defs that have to disappear cannot be the
+ * ones asked to lay themselves out.
  */
 export interface TrailManager {
     /**
@@ -17,16 +19,16 @@ export interface TrailManager {
         readonly canvas: HTMLCanvasElement;
         readonly layer: string;
     }): void;
-    /** Redraw all trails for `scale`; returns changed layer defs. */
-    applyScale(scale: number): RenderableDef[];
+    /** Rebuild all trails for `pixelSize`; returns changed layer defs. */
+    applyScale(pixelSize: number): RenderableDef[];
     /** Remove all trails. */
     destroy(): void;
 }
 /**
  * Create a {@link TrailManager} that renders dot trails into layers
  * managed by the given {@link LayerManager}.
- * @param layerManager
- * @param rendererPort
+ * @param layerManager - Where the trails are placed and dirt is tracked.
+ * @returns The manager.
  */
-export declare function createTrailManager(layerManager: LayerManager, rendererPort: RendererPort): TrailManager;
+export declare function createTrailManager(layerManager: LayerManager, port: RendererPort): TrailManager;
 //# sourceMappingURL=trailManager.d.ts.map

package/dist/renderer/trailManager.js

@@ -1,15 +1,47 @@
 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;
+/** Distance between trail dots at a pixel size of 1, in the same units as route points. */
+const TRAIL_INTERVAL_AT_BASE_PIXEL_SIZE = 40;
 /**
  * Create a {@link TrailManager} that renders dot trails into layers
  * managed by the given {@link LayerManager}.
- * @param layerManager
- * @param rendererPort
+ * @param layerManager - Where the trails are placed and dirt is tracked.
+ * @returns The manager.
  */
-export function createTrailManager(layerManager, rendererPort) {
+export function createTrailManager(layerManager, port) {
     const trails = new Map();
+    /**
+     * The pixel size the trails currently hold their spacing for.
+     *
+     * The one place the wayfinding side remembers a pixel size, and it has to: a trail's membership
+     * changes for two reasons and only one of them is a camera move — `setTrail` rebuilds when the
+     * route changes, at a moment no `onScale` is delivering a size. Seeded at `1` and corrected by the
+     * layer handler's first run, which registration performs before anything is drawn.
+     */
+    let currentPixelSize = 1;
+    /**
+     * Rebuilds every trail on one layer for a new pixel size — what each trail layer's `onScale`
+     * closure delegates to.
+     *
+     * One function per manager, not per def: what it reads is this manager's trails, and the closure
+     * hands it the one layer it serves.
+     * @param layer - The trail layer.
+     * @param pixelSize - Plan units per device pixel.
+     * @returns The layer when its membership changed, so the renderer reconciles it.
+     */
+    function layOutTrails(layer, pixelSize) {
+        currentPixelSize = pixelSize;
+        let rebuilt = false;
+        for (const record of trails.values()) {
+            if (record.layerName !== layer.name)
+                continue;
+            redraw(record);
+            rebuilt = true;
+        }
+        if (rebuilt)
+            return [layer];
+        return undefined;
+    }
     function removeDotsFromLayer(record) {
         if (!record.dotDefs.length)
             return;
@@ -18,12 +50,16 @@ export function createTrailManager(layerManager, rendererPort) {
         layer.children = layer.children.filter((child) => !oldDots.has(child));
         record.dotDefs = [];
     }
-    function redraw(record, scale) {
+    function redraw(record) {
         const layer = layerManager.touchLayer(record.layerName);
-        const interval = TRAIL_INTERVAL_AT_BASE_SCALE * scale;
+        // Declared here rather than at construction, because this is where the layer is first known. The
+        // `update(layer)` that a flush or a re-layout performs is what makes the layer register under it.
+        layer.onScale = ({ pixelSize }) => layOutTrails(layer, pixelSize);
+        const interval = TRAIL_INTERVAL_AT_BASE_PIXEL_SIZE * currentPixelSize;
         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 })));
+        const size = { x: canvas.width * currentPixelSize, y: canvas.height * currentPixelSize };
+        const newDots = points.map((point) => port.createImageDef(canvas, new Rect({ x: point.x, y: point.y }, size)));
         removeDotsFromLayer(record);
         layer.children.push(...newDots);
         record.dotDefs = newDots;
@@ -50,7 +86,7 @@ export function createTrailManager(layerManager, rendererPort) {
                 }
                 existing.from = from;
                 existing.to = to;
-                redraw(existing, rendererPort.getScale());
+                redraw(existing);
                 return;
             }
             const record = {
@@ -61,12 +97,13 @@ export function createTrailManager(layerManager, rendererPort) {
                 dotDefs: [],
             };
             trails.set(name, record);
-            redraw(record, rendererPort.getScale());
+            redraw(record);
         },
-        applyScale(scale) {
+        applyScale(pixelSize) {
+            currentPixelSize = pixelSize;
             const layers = new Set();
             for (const record of trails.values()) {
-                redraw(record, scale);
+                redraw(record);
                 layers.add(layerManager.touchLayer(record.layerName));
             }
             return [...layers];

package/dist/renderer/types.d.ts

@@ -1,29 +1,55 @@
 import type { Point2Like, Rect } from '@expofp/geometry';
-import type { ImageDef, ImageSource, LayerDef, LineDef, Rect as RendererRect, RenderableDef } from '@expofp/renderer';
+import type { ImageDef, ImageSource, LayerDef, LineDef, 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`.
+ * What the wayfinding renderer needs from whatever is drawing the scene — the whole of it.
+ *
+ * The def factories are injected rather than imported because they live in the host
+ * (floorplan's `src/renderer`), which depends on this package — importing them back would close a
+ * cycle. What the port no longer carries is the camera: sizes are pushed in by the layout handlers
+ * the defs declare (`onScale`), never pulled through a `getScale()`, and a geometry `Rect` is the
+ * bounds type, so nothing needs converting on the way in either.
  */
 export interface RendererPort {
+    /**
+     * Builds an image def. Its bounds are laid out for the camera later, by `onScale`.
+     * @param source - The canvas or image to draw.
+     * @param bounds - Where it sits; size is a placeholder until the first layout.
+     * @param options - Initial visibility, dimming and anchor.
+     * @returns The def.
+     */
     createImageDef(source: ImageSource, bounds: Rect, options?: {
         hidden?: boolean;
-        dim?: boolean;
+        dim?: number;
         interactive?: boolean;
         origin?: [number, number];
     }): ImageDef;
+    /**
+     * Builds a line def between two points.
+     * @param line - Its endpoints.
+     * @param color - Stroke color.
+     * @param width - Stroke width.
+     * @returns The def.
+     */
     createLineDef(line: {
         p0: Point2Like;
         p1: Point2Like;
     }, color?: string, width?: number): LineDef;
+    /**
+     * The cardinal-snap delta for a camera angle.
+     * @param newAngle - The camera's angle.
+     * @param currentRotation - The def's current rotation.
+     * @returns The delta to apply, or nothing while the camera is under the 45° threshold.
+     */
     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. */
+    /** The scene's root layers; the `wf-*` layers are resolved out of these by name. */
+    readonly layers: readonly LayerDef[];
+    /**
+     * Commits changed defs.
+     *
+     * Injected rather than imported for one reason: the deprecated imperative path must reach an
+     * imperative renderer as well as renderer's `update`, and only its caller knows which.
+     * @param defs - The defs that changed.
+     */
     update(...defs: RenderableDef[]): void;
 }
 export interface RouteColors {
@@ -111,17 +137,34 @@ export interface WayfindingRenderer {
         readonly animatedLinesLayer: string;
         readonly resetAnimation?: boolean;
     }): void;
-    /** Recompute icon/trail bounds for `scale`; returns changed defs to render. */
-    applyScale(scale: number): RenderableDef[];
+    /**
+     * Lays every icon and trail out for `pixelSize`, returning the defs that changed.
+     *
+     * **Not the mechanism** — the defs declare their own `onScale` and a renderer that dispatches them
+     * needs nothing from here. This runs those same handlers in a loop, for the deprecated imperative
+     * path, which has neither dispatch nor the "laid out before first drawn" guarantee registration
+     * gives.
+     * @param pixelSize - Plan units per device pixel.
+     * @returns The defs that changed.
+     */
+    applyScale(pixelSize: 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;
+    /**
+     * Fires the def's `onClick`, if it is a clickable icon.
+     * @param def - The def that was clicked.
+     * @returns Whether it was one — so a caller can stop the click going any further.
+     */
+    handleClick(def: RenderableDef): boolean;
+    /**
+     * Whether a def is a clickable icon, which is what a pointer cursor hangs off.
+     * @param def - The def under the pointer.
+     * @returns Whether it is clickable.
+     */
+    handleHover(def: 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). */
+    /** Commit buffered mutations to the renderer (via the injected `update`). */
     flush(): void;
     /** Full teardown (managers cleared). Does NOT flush. */
     destroy(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/wayfinding",
-  "version": "3.26.0",
+  "version": "3.27.0",
   "type": "module",
   "description": "ExpoFP SDK internal: framework-neutral wayfinding (routing, snapping, scene rendering)",
   "homepage": "https://developer.expofp.com/",
@@ -34,12 +34,12 @@
   "dependencies": {
     "ngraph.graph": "^19.1.0",
     "tslib": "^2.3.0",
-    "@expofp/geometry": "3.26.0"
+    "@expofp/geometry": "3.27.0"
   },
   "peerDependencies": {
-    "@expofp/renderer": "^3.2.4"
+    "@expofp/renderer": "3.27.0"
   },
   "devDependencies": {
-    "@expofp/renderer": "^3.2.4"
+    "@expofp/renderer": "3.27.0"
   }
 }