@expofp/wayfinding 3.31.4 → 3.32.0

package/README.md

@@ -36,7 +36,7 @@ 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.
+- **`renderer`** (`RendererPort`) — def factories, scene layers, commit.
 - **`iconProvider`** (`IconProvider`) — canvases for icon names.
 - **`floorContext`** (`FloorContext`) — active floor / visibility predicates.
 
@@ -72,9 +72,7 @@ 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);
+// Forward pointer events:
 wayfinding.handleClick(pickedDefs);
 
 wayfinding.destroy();

package/dist/createWayfinding.d.ts

@@ -28,9 +28,9 @@ export interface WayfindingConfig {
     readonly onRouteDistance?: (distance: number) => void;
 }
 /**
- * The single wayfinding instance. Owns the routing engine, the scene renderer,
- * and the runtime; the host drives it with route/position/floor updates and
- * forwards its camera/pointer events to the `apply*`/`handle*` methods.
+ * The single wayfinding instance. Owns the routing engine, the scene renderer, and the runtime; the
+ * host drives it with route/position/floor updates and forwards its pointer events to the
+ * `handle*` methods. Camera moves need nothing from here — the defs carry their own layout rules.
  */
 export interface Wayfinding {
     /** Build (or update) the active route; `false` when no path exists. */
@@ -46,18 +46,16 @@ export interface Wayfinding {
     notifyFloorChanged(): void;
     /** Whether the position has drifted off the active route far enough to reroute. */
     shouldReroute(position: RoutePoint): boolean;
-    /** Forward a camera-zoom change; rescales icons/trails and commits. */
-    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`, and reports whether one claimed it. */
+    /**
+     * 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;
     /**
-     * Place, update, or hide (`config: null`) a host annotation icon — e.g. kiosk
-     * or you-are-here — on the wayfinding icon layer. These icons share the route
-     * icons' scale/roll handling. Buffered — call `flush()` to commit.
+     * Place, update, or hide (`config: null`) a host annotation icon — kiosk, you-are-here — on the
+     * wayfinding icon layer, laid out like the route's own. Buffered — call `flush()` to commit.
      */
     setIcon(name: string, config: IconConfig | null, key?: string | number): void;
     /** Commit buffered scene mutations. */

package/dist/createWayfinding.js

@@ -22,10 +22,6 @@ export function createWayfinding(config) {
         onRouteUpdate: (lines, bounds) => config.onRouteUpdate?.(lines, bounds),
         onRouteDistance: (distance) => config.onRouteDistance?.(distance),
     });
-    const renderDefs = (defs) => {
-        if (defs.length)
-            rendererPort.update(...defs);
-    };
     return {
         setRoute: (input) => runtime.setRoute(input),
         buildRoute: (from, to, options) => engine.buildRoute(from, to, options),
@@ -33,11 +29,6 @@ export function createWayfinding(config) {
         setPosition: (position) => runtime.onPositionChanged(position),
         notifyFloorChanged: () => runtime.onFloorChanged(),
         shouldReroute: (position) => runtime.shouldReroute(position),
-        applyScale: (scale) => renderDefs(renderer.applyScale(scale)),
-        applyRoll: (angle) => renderDefs(renderer.applyRoll(angle)),
-        // 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))

package/dist/renderer/createWayfindingRenderer.d.ts

@@ -1,15 +1,7 @@
 import type { RendererPort, WayfindingRenderer, WayfindingRendererConfig } from './types.js';
 /**
- * Create a {@link WayfindingRenderer} — the composition root that wires
- * together {@link LayerManager}, {@link IconManager}, {@link TrailManager},
- * and {@link RouteLineManager}.
- *
- * 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.
+ * Create a {@link WayfindingRenderer} — the composition root over {@link LayerManager},
+ * {@link IconManager}, {@link TrailManager} and {@link RouteLineManager}.
  */
 export declare function createWayfindingRenderer(port: RendererPort, config?: WayfindingRendererConfig): WayfindingRenderer;
 //# sourceMappingURL=createWayfindingRenderer.d.ts.map

package/dist/renderer/createWayfindingRenderer.js

@@ -8,16 +8,8 @@ const DEFAULT_COLORS = {
     active: '#0794EA',
 };
 /**
- * Create a {@link WayfindingRenderer} — the composition root that wires
- * together {@link LayerManager}, {@link IconManager}, {@link TrailManager},
- * and {@link RouteLineManager}.
- *
- * 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.
+ * Create a {@link WayfindingRenderer} — the composition root over {@link LayerManager},
+ * {@link IconManager}, {@link TrailManager} and {@link RouteLineManager}.
  */
 export function createWayfindingRenderer(port, config = {}) {
     const colors = { ...DEFAULT_COLORS, ...config.colors };
@@ -30,11 +22,6 @@ export function createWayfindingRenderer(port, config = {}) {
         clearIcons: (...args) => iconManager.clearIcons(...args),
         setTrail: (...args) => trailManager.setTrail(...args),
         setRouteLines: (...args) => routeLineManager.setRouteLines(...args),
-        applyScale: (pixelSize) => [
-            ...iconManager.applyScale(pixelSize),
-            ...trailManager.applyScale(pixelSize),
-        ],
-        applyRoll: (cameraAngle) => iconManager.applyRoll(cameraAngle),
         handleClick: (def) => iconManager.handleClick(def),
         handleHover: (def) => iconManager.handleHover(def),
         clearRoute() {

package/dist/renderer/iconManager.d.ts

@@ -2,28 +2,19 @@ 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.
+ * Lays one wayfinding icon out for a new pixel size: an icon holds its on-screen size, so its
+ * bounds are the source's pixel dimensions times the pixel size, about its own centre.
  *
- * 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.
+ * 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. Returns nothing when the size was already right, so
+ * 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.
  *
- * Icons are keyed by `(name, key?)`. First `setIcon` creates the `ImageDef`;
- * subsequent calls mutate in place. Pass `config: null` to hide an icon
- * without destroying it.
- *
- * Exposes pure `applyScale`/`applyRoll`/`handleClick`/`handleHover` that the
- * app glue drives from engine events.
+ * Icons are keyed by `(name, key?)`. First `setIcon` creates the `ImageDef`; later calls mutate in
+ * place. Pass `config: null` to hide an icon without destroying it.
  */
 export interface IconManager {
     /** Place, update, or hide an icon. See {@link WayfindingRenderer.setIcon}. */
@@ -34,21 +25,11 @@ export interface IconManager {
     hideAll(): void;
     /** Clear internal state. */
     destroy(): void;
-    /** 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 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 - Where icons are placed and dirt is tracked.
- * @param port - Supplies the def factories; see {@link RendererPort}.
- * @returns The manager.
- */
+/** Create an {@link IconManager} that places icons into layers the {@link LayerManager} tracks. */
 export declare function createIconManager(layerManager: LayerManager, port: RendererPort): IconManager;
 //# sourceMappingURL=iconManager.d.ts.map

package/dist/renderer/iconManager.js

@@ -1,16 +1,11 @@
 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.
+ * Lays one wayfinding icon out for a new pixel size: an icon holds its on-screen size, so its
+ * bounds are the source's pixel dimensions times the pixel size, about its own centre.
  *
- * 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.
+ * 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. Returns nothing when the size was already right, so
+ * a settled camera costs no slot writes.
  */
 export function rescaleIcon(def, pixelSize) {
     const bounds = def.bounds;
@@ -22,21 +17,12 @@ export function rescaleIcon(def, pixelSize) {
     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 - Where icons are placed and dirt is tracked.
- * @param port - Supplies the def factories; see {@link RendererPort}.
- * @returns The manager.
- */
+/** Create an {@link IconManager} that places icons into layers the {@link LayerManager} tracks. */
 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.
-     */
+    /** The reverse of {@link icons}: a pointer hit names a def, so it is a lookup, not a scan. */
     const iconsByDef = new Map();
     function composeKey(name, key) {
         return key === undefined ? name : `${name}#${key}`;
@@ -68,26 +54,13 @@ export function createIconManager(layerManager, port) {
             hidden: cfg.hidden ?? false,
             dim: cfg.dimmed ? 1 : 0,
             origin: cfg.origin,
+            cardinalSnap: cfg.cardinalSnap,
         });
         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,
             callback: cfg.onClick ?? null,
         };
         icons.set(iconKey, record);
@@ -118,19 +91,16 @@ export function createIconManager(layerManager, port) {
         // 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);
+        const rotation = cfg.rotation ?? bounds.rotation;
+        bounds.set(cfg.x, cfg.y, bounds.size.x, bounds.size.y, rotation, bounds.elevation);
         record.imageDef.hidden = cfg.hidden ?? false;
         record.imageDef.dim = cfg.dimmed ? 1 : 0;
         record.callback = cfg.onClick ?? null;
         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.
+     * Hides one icon and records that its **def** changed, not the layer holding it: the layer's
+     * children are unchanged, so a renderer reconciling the layer would never reach this instance.
      */
     function hideIcon(record) {
         record.imageDef.hidden = true;
@@ -175,31 +145,6 @@ export function createIconManager(layerManager, port) {
             iconKeysByName.clear();
             keyToName.clear();
         },
-        applyScale(pixelSize) {
-            const defs = [];
-            for (const record of icons.values()) {
-                if (record.imageDef.hidden)
-                    continue;
-                const changed = rescaleIcon(record.imageDef, pixelSize);
-                if (changed)
-                    defs.push(...changed);
-            }
-            return defs;
-        },
-        applyRoll(cameraAngle) {
-            const defs = [];
-            for (const record of icons.values()) {
-                if (!record.cardinalSnap)
-                    continue;
-                const bounds = record.imageDef.bounds;
-                const delta = port.getRotation(cameraAngle, bounds.rotation);
-                if (delta === undefined)
-                    continue;
-                bounds.rotate(delta, bounds);
-                defs.push(record.imageDef);
-            }
-            return defs;
-        },
         handleClick(def) {
             const record = iconsByDef.get(def);
             if (!record?.callback || record.imageDef.hidden)

package/dist/renderer/trailManager.d.ts

@@ -1,5 +1,4 @@
 import { type Point2Like } from '@expofp/geometry';
-import type { RenderableDef } from '@expofp/renderer';
 import type { LayerManager } from './layerManager.js';
 import type { RendererPort } from './types.js';
 /**
@@ -19,8 +18,6 @@ export interface TrailManager {
         readonly canvas: HTMLCanvasElement;
         readonly layer: string;
     }): void;
-    /** Rebuild all trails for `pixelSize`; returns changed layer defs. */
-    applyScale(pixelSize: number): RenderableDef[];
     /** Remove all trails. */
     destroy(): void;
 }

package/dist/renderer/trailManager.js

@@ -20,57 +20,137 @@ export function createTrailManager(layerManager, port) {
      */
     let currentPixelSize = 1;
     /**
-     * Rebuilds every trail on one layer for a new pixel size — what each trail layer's `onScale`
+     * The layers this manager has declared an `onScale` on.
+     *
+     * Declaring the handler is not enough to be called: `useLayoutTargets` registers a layer as a
+     * layout target from a render, so the layer has to be committed once after the handler appears.
+     * That commit is a membership change, which is why it happens once per layer rather than per
+     * redraw.
+     */
+    const wiredLayers = new Set();
+    /**
+     * Lays every trail on one layer out 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.
+     * @returns The dots that were written, plus the layer when the dot count changed with them.
      */
     function layOutTrails(layer, pixelSize) {
         currentPixelSize = pixelSize;
-        let rebuilt = false;
+        const changed = [];
+        let membershipChanged = false;
         for (const record of trails.values()) {
             if (record.layerName !== layer.name)
                 continue;
-            redraw(record);
-            rebuilt = true;
+            const result = redraw(record);
+            changed.push(...result.changed);
+            membershipChanged ||= result.membershipChanged;
         }
-        if (rebuilt)
-            return [layer];
-        return undefined;
+        // The layer only when the dot count changed: a def write lands in this frame, a membership
+        // change a transition later, so a camera step that only shifts dots stays in this one.
+        if (membershipChanged)
+            changed.push(layer);
+        return changed.length ? changed : undefined;
     }
-    function removeDotsFromLayer(record) {
-        if (!record.dotDefs.length)
+    /**
+     * Takes dots out of their layer, hidden first.
+     *
+     * The hide is not redundant with the removal: the renderer commits a def write synchronously and
+     * defers the membership sweep, so a dot that was only removed stays on screen a frame or more.
+     * @param record - The trail the dots belong to.
+     * @param dots - The dots to take out.
+     */
+    function removeDots(record, dots) {
+        if (!dots.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 = [];
+        const dropped = new Set(dots);
+        for (const dot of dropped)
+            dot.hidden = true;
+        layer.children = layer.children.filter((child) => !dropped.has(child));
     }
-    function redraw(record) {
-        const layer = layerManager.touchLayer(record.layerName);
-        // 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.
+    /**
+     * The trail layer, with this manager's `onScale` declared on it the first time it is asked for.
+     * @param name - The layer's name.
+     * @returns The layer.
+     */
+    function wireLayer(name) {
+        const layer = layerManager.resolveLayer(name);
+        if (wiredLayers.has(name))
+            return layer;
         layer.onScale = ({ pixelSize }) => layOutTrails(layer, pixelSize);
+        wiredLayers.add(name);
+        // Committed with the layer, which is what makes the renderer register the handler.
+        layerManager.touchLayer(name);
+        return layer;
+    }
+    /**
+     * Lays one trail out at the current pixel size, reusing the dots it already holds.
+     *
+     * Spacing is fixed in screen pixels, so a camera step moves every dot and changes how many there
+     * are. Moving the survivors rather than replacing them is what keeps the common case a def write:
+     * only the difference in count reaches the layer's membership.
+     * @param record - The trail to lay out.
+     * @returns The dots that were written, and whether the layer's membership changed with them.
+     */
+    function redraw(record) {
+        const layer = wireLayer(record.layerName);
         const interval = TRAIL_INTERVAL_AT_BASE_PIXEL_SIZE * currentPixelSize;
         const points = computeTrailPoints(record.from, record.to, interval);
         const canvas = record.canvas;
         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;
+        const dots = record.dotDefs;
+        const kept = Math.min(dots.length, points.length);
+        const changed = [];
+        for (let i = 0; i < kept; i++) {
+            const bounds = dots[i].bounds;
+            bounds.set(points[i].x, points[i].y, size.x, size.y, bounds.rotation, bounds.elevation);
+            changed.push(dots[i]);
+        }
+        if (points.length > kept) {
+            const added = points
+                .slice(kept)
+                .map((point) => port.createImageDef(canvas, new Rect({ x: point.x, y: point.y }, size)));
+            layer.children.push(...added);
+            dots.push(...added);
+            layerManager.touchLayer(record.layerName);
+            return { changed, membershipChanged: true };
+        }
+        if (dots.length > kept) {
+            const dropped = dots.splice(kept);
+            removeDots(record, dropped);
+            // Hidden, and reported with the rest: the hide is a def write, and only a def the handler
+            // returns is written in this frame — the removal itself lands a transition later.
+            changed.push(...dropped);
+            return { changed, membershipChanged: true };
+        }
+        return { changed, membershipChanged: false };
     }
     function drop(name) {
         const record = trails.get(name);
         if (!record)
             return;
-        removeDotsFromLayer(record);
+        removeDots(record, record.dotDefs);
+        for (const dot of record.dotDefs)
+            layerManager.touchDef(dot);
+        record.dotDefs = [];
         trails.delete(name);
     }
+    /**
+     * Queues what a redraw wrote for the next {@link LayerManager.flush} — the buffered path only.
+     *
+     * A redraw driven by the camera reports the same defs to the renderer, which writes them in that
+     * frame; queuing them here as well would leave them in the dirty set for an unrelated flush to
+     * commit again.
+     * @param result - What the redraw changed.
+     */
+    function bufferRedraw(result) {
+        for (const def of result.changed)
+            layerManager.touchDef(def);
+    }
     return {
         setTrail(name, from, to, options) {
             if (from === null || to === null) {
@@ -86,7 +166,7 @@ export function createTrailManager(layerManager, port) {
                 }
                 existing.from = from;
                 existing.to = to;
-                redraw(existing);
+                bufferRedraw(redraw(existing));
                 return;
             }
             const record = {
@@ -97,20 +177,16 @@ export function createTrailManager(layerManager, port) {
                 dotDefs: [],
             };
             trails.set(name, record);
-            redraw(record);
-        },
-        applyScale(pixelSize) {
-            currentPixelSize = pixelSize;
-            const layers = new Set();
-            for (const record of trails.values()) {
-                redraw(record);
-                layers.add(layerManager.touchLayer(record.layerName));
-            }
-            return [...layers];
+            bufferRedraw(redraw(record));
         },
         destroy() {
             for (const trailName of [...trails.keys()])
                 drop(trailName);
+            // The layer outlives this manager, so the handler has to go with it: left in place it keeps
+            // the manager, its layers and its canvases reachable, and runs on every camera step.
+            for (const name of wiredLayers)
+                layerManager.resolveLayer(name).onScale = undefined;
+            wiredLayers.clear();
         },
     };
 }

package/dist/renderer/types.d.ts

@@ -1,54 +1,34 @@
 import type { Point2Like, Rect } from '@expofp/geometry';
 import type { ImageDef, ImageSource, LayerDef, LineDef, RenderableDef } from '@expofp/renderer';
 /**
- * What the wayfinding renderer needs from whatever is drawing the scene — the whole of it.
+ * What the wayfinding renderer needs from whatever is drawing the scene.
  *
  * 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.
+ * cycle.
  */
 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.
-     */
+    /** Builds an image def. `bounds` carries a placeholder size until the first `onScale`. */
     createImageDef(source: ImageSource, bounds: Rect, options?: {
         hidden?: boolean;
         dim?: number;
         interactive?: boolean;
         origin?: [number, number];
+        /** Forwarded from {@link IconConfig.cardinalSnap}; the host attaches the rule. */
+        cardinalSnap?: boolean;
     }): ImageDef;
-    /**
-     * Builds a line def between two points.
-     * @param line - Its endpoints.
-     * @param color - Stroke color.
-     * @param width - Stroke width.
-     * @returns The def.
-     */
+    /** Builds a line def between two points. */
     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;
     /** 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.
+     * Injected rather than imported: `@expofp/renderer` is a type-only peer here, so the concrete
+     * `update` comes from the host.
      */
     update(...defs: RenderableDef[]): void;
 }
@@ -80,13 +60,9 @@ export interface IconConfig {
      */
     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.
+     * Keeps the icon readable as the camera rolls; the host's `createImageDef` attaches the rule.
+     * The turn is relative — the icon holds its starting heading plus whole quarters — so do NOT
+     * enable it where `rotation` carries meaning (position arrow, kiosk heading).
      *
      * Set at first setIcon for an icon key; ignored on subsequent updates.
      */
@@ -138,29 +114,11 @@ export interface WayfindingRenderer {
         readonly resetAnimation?: boolean;
     }): void;
     /**
-     * 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[];
-    /**
-     * 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.
+     * Fires the def's `onClick`; reports whether it was a clickable icon, 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.
-     */
+    /** Whether a def is a clickable icon, which is what a pointer cursor hangs off. */
     handleHover(def: RenderableDef): boolean;
     /** Clear route lines, drop trails, hide icons. Buffered — `flush()` to commit. */
     clearRoute(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/wayfinding",
-  "version": "3.31.4",
+  "version": "3.32.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.31.4"
+    "@expofp/geometry": "3.32.0"
   },
   "peerDependencies": {
-    "@expofp/renderer": "3.31.4"
+    "@expofp/renderer": "3.32.0"
   },
   "devDependencies": {
-    "@expofp/renderer": "3.31.4"
+    "@expofp/renderer": "3.32.0"
   }
 }