@expofp/wayfinding 3.33.0 → 3.34.1

package/README.md

@@ -4,8 +4,9 @@ Framework-neutral wayfinding for the ExpoFP SDK: a routing/snapping engine, an
 imperative runtime orchestrator, and a scene renderer — with **no** coupling to
 efp stores or MobX. `core` and `runtime` are environment-agnostic; the scene
 renderer assumes a browser-like environment (`requestAnimationFrame`, `document`),
-so the package is not suitable for Node/SSR as-is. All three layers sit behind a
-single entry point, `createWayfinding`.
+so the package is not suitable for Node/SSR as-is. All three layers sit behind two
+entry points: `initWayfindingLayers`, which builds the layer block for the host
+to mount, and `createWayfinding`, which finds it in the scene and fills it.
 
 ## Install
 
@@ -26,7 +27,9 @@ reference it, so its types must resolve for `@expofp/wayfinding`'s `.d.ts` to co
 | `renderer` | Scene mutator (icons, trails, route lines) against an injected `RendererPort`.               |
 
 These layers are internal. The package exports only the `createWayfinding`
-facade, the port interfaces the host implements, the boundary data types, the
+facade, `initWayfindingLayers` (the layer block it draws into, for the host to
+mount) with `resolveWayfindingLayers` (which finds that block in a scene again),
+the port interfaces the host implements, the boundary data types, the
 `CURRENT_POSITION_POINT_ID` protocol sentinel, and the `optimizeWaypointOrder`
 helper.
 
@@ -36,7 +39,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, scene layers, commit.
+- **`renderer`** (`RendererPort`) — the host's cardinal-snap rule and commit.
 - **`iconProvider`** (`IconProvider`) — canvases for icon names.
 - **`floorContext`** (`FloorContext`) — active floor / visibility predicates.
 
@@ -54,7 +57,7 @@ const wayfinding = createWayfinding({
   renderer, // RendererPort
   iconProvider, // IconProvider
   floorContext, // FloorContext
-  layers, // LayerNames: { points, trail, lines, linesAnimated, currentPosition }
+  layers, // WayfindingLayers, from resolveWayfindingLayers(scene.rootLayer)
   gpsConfig, // optional GPS calibration + snap/reroute thresholds
   onTransitionClick: (point) => {
     /* switch active floor */

package/dist/createWayfinding.d.ts

@@ -1,8 +1,8 @@
 import type { Box } from '@expofp/geometry';
 import type { RenderableDef } from '@expofp/renderer';
 import { type GpsProjectionConfig, type GraphDataSource, type Route, type RouteEndpoint, type RouteLine, type RoutePoint, type TransitionPointDef } from './core/index.js';
-import { type IconConfig, type RendererPort } from './renderer/index.js';
-import { type FloorContext, type IconProvider, type LayerNames, type PositionInput, type SetRouteInput } from './runtime/index.js';
+import { type IconConfig, type RendererPort, type WayfindingLayers } from './renderer/index.js';
+import { type FloorContext, type IconProvider, type PositionInput, type SetRouteInput } from './runtime/index.js';
 /** Plan GPS calibration plus optional snap / reroute distance overrides (meters). */
 export type GpsConfig = GpsProjectionConfig & {
     snapThreshold?: number;
@@ -18,7 +18,8 @@ export interface WayfindingConfig {
     readonly renderer: RendererPort;
     readonly iconProvider: IconProvider;
     readonly floorContext: FloorContext;
-    readonly layers: LayerNames;
+    /** The layers from `initWayfindingLayers()` — the block the host mounted, which this fills. */
+    readonly layers: WayfindingLayers;
     /** Plan GPS calibration; the snap and reroute thresholds are derived from it. */
     readonly gpsConfig?: GpsConfig;
     readonly onTransitionClick?: (point: TransitionPointDef) => void;

package/dist/createWayfinding.js

@@ -1,10 +1,10 @@
 import { createWayfindingEngine, getThresholdFromMetersToSvg, getThresholdOrDefault, resolveRerouteThresholdSvg, SNAP_THRESHOLD_METERS, } from './core/index.js';
-import { createWayfindingRenderer } from './renderer/index.js';
+import { createWayfindingRenderer, } from './renderer/index.js';
 import { createWayfindingRuntime, } from './runtime/index.js';
 export function createWayfinding(config) {
     const { dataSource, renderer: rendererPort, iconProvider, floorContext, layers, gpsConfig, } = config;
     const engine = createWayfindingEngine(dataSource);
-    const renderer = createWayfindingRenderer(rendererPort);
+    const renderer = createWayfindingRenderer(rendererPort, layers);
     const snapThresholdMeters = getThresholdOrDefault(gpsConfig?.snapThreshold, SNAP_THRESHOLD_METERS);
     const snapThreshold = getThresholdFromMetersToSvg({
         thresholdInMeters: snapThresholdMeters,
@@ -15,7 +15,6 @@ export function createWayfinding(config) {
         renderer,
         iconProvider,
         floorContext,
-        layers,
         snapThreshold,
         rerouteThreshold: resolveRerouteThresholdSvg(gpsConfig),
         onTransitionClick: (point) => config.onTransitionClick?.(point),

package/dist/index.d.ts

@@ -1,12 +1,16 @@
 /**
  * `@expofp/wayfinding` — framework-neutral wayfinding: routing/snapping engine,
- * an imperative runtime, and a scene renderer behind a single entry point.
+ * an imperative runtime, and a scene renderer behind two entry points:
+ * `initWayfindingLayers` builds the layers for the host to mount,
+ * `createWayfinding` fills them.
  */
 export type { GpsConfig, Wayfinding, WayfindingConfig } from './createWayfinding.js';
 export { createWayfinding } from './createWayfinding.js';
+export type { WayfindingLayers } from './renderer/index.js';
+export { initWayfindingLayers, resolveWayfindingLayers } from './renderer/index.js';
 export type { GraphDataSource } from './core/index.js';
 export type { IconConfig, RendererPort } from './renderer/index.js';
-export type { FloorContext, IconAsset, IconName, IconProvider, LayerNames, } from './runtime/index.js';
+export type { FloorContext, IconAsset, IconName, IconProvider } from './runtime/index.js';
 export type { GraphLine, Route, RouteEndpoint, RouteLine, RoutePoint, TransitionPointDef, } from './core/index.js';
 export type { PositionInput, SetRouteInput } from './runtime/index.js';
 export { CURRENT_POSITION_POINT_ID } from './runtime/index.js';

package/dist/index.js

@@ -1,8 +1,11 @@
 /**
  * `@expofp/wayfinding` — framework-neutral wayfinding: routing/snapping engine,
- * an imperative runtime, and a scene renderer behind a single entry point.
+ * an imperative runtime, and a scene renderer behind two entry points:
+ * `initWayfindingLayers` builds the layers for the host to mount,
+ * `createWayfinding` fills them.
  */
 export { createWayfinding } from './createWayfinding.js';
+export { initWayfindingLayers, resolveWayfindingLayers } from './renderer/index.js';
 // Protocol sentinel: the host must stamp it as the `id` of a "current position"
 // route endpoint so the runtime renders that point as the live position.
 export { CURRENT_POSITION_POINT_ID } from './runtime/index.js';

package/dist/renderer/createWayfindingRenderer.d.ts

@@ -1,7 +1,8 @@
+import type { WayfindingLayers } from './layers.js';
 import type { RendererPort, WayfindingRenderer, WayfindingRendererConfig } from './types.js';
 /**
  * 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;
+export declare function createWayfindingRenderer(port: RendererPort, layers: WayfindingLayers, config?: WayfindingRendererConfig): WayfindingRenderer;
 //# sourceMappingURL=createWayfindingRenderer.d.ts.map

package/dist/renderer/createWayfindingRenderer.js

@@ -11,12 +11,12 @@ const DEFAULT_COLORS = {
  * Create a {@link WayfindingRenderer} — the composition root over {@link LayerManager},
  * {@link IconManager}, {@link TrailManager} and {@link RouteLineManager}.
  */
-export function createWayfindingRenderer(port, config = {}) {
+export function createWayfindingRenderer(port, layers, config = {}) {
     const colors = { ...DEFAULT_COLORS, ...config.colors };
     const layerManager = createLayerManager(port);
-    const iconManager = createIconManager(layerManager, port);
-    const trailManager = createTrailManager(layerManager, port);
-    const routeLineManager = createRouteLineManager(layerManager, colors, port);
+    const iconManager = createIconManager(layerManager, port, layers);
+    const trailManager = createTrailManager(layerManager, layers.trail);
+    const routeLineManager = createRouteLineManager(layerManager, colors, port, layers);
     const wfRenderer = {
         setIcon: (...args) => iconManager.setIcon(...args),
         clearIcons: (...args) => iconManager.clearIcons(...args),
@@ -35,6 +35,9 @@ export function createWayfindingRenderer(port, config = {}) {
             iconManager.destroy();
             trailManager.destroy();
             routeLineManager.destroy();
+            // The layers belong to the host and outlive this instance, so emptying them has to reach the
+            // renderer before the dirty sets go — nothing is left to flush this afterwards.
+            layerManager.flush();
             layerManager.destroy();
         },
     };

package/dist/renderer/iconManager.d.ts

@@ -1,9 +1,10 @@
 import type { ImageDef, RenderableDef } from '@expofp/renderer';
 import type { LayerManager } from './layerManager.js';
+import type { WayfindingLayers } from './layers.js';
 import type { IconConfig, RendererPort } from './types.js';
 /**
  * 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.
+ * bounds are the source's pixel dimensions times the pixel size, about its own center.
  *
  * 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
@@ -30,6 +31,12 @@ export interface IconManager {
     /** Whether a def is a clickable icon. */
     handleHover(def: RenderableDef): boolean;
 }
-/** Create an {@link IconManager} that places icons into layers the {@link LayerManager} tracks. */
-export declare function createIconManager(layerManager: LayerManager, port: RendererPort): IconManager;
+/**
+ * Create an {@link IconManager} that places icons into the two icon layers of the block.
+ * @param layerManager - Tracks what changed.
+ * @param port - The host's roll rule and commit.
+ * @param layers - The icon layers to place into.
+ * @returns The manager.
+ */
+export declare function createIconManager(layerManager: LayerManager, port: RendererPort, layers: Pick<WayfindingLayers, 'icons' | 'currentPosition'>): IconManager;
 //# sourceMappingURL=iconManager.d.ts.map

package/dist/renderer/iconManager.js

@@ -1,7 +1,7 @@
 import { Rect } from '@expofp/geometry';
 /**
  * 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.
+ * bounds are the source's pixel dimensions times the pixel size, about its own center.
  *
  * 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
@@ -17,13 +17,28 @@ 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 icons into layers the {@link LayerManager} tracks. */
-export function createIconManager(layerManager, port) {
+/**
+ * Create an {@link IconManager} that places icons into the two icon layers of the block.
+ * @param layerManager - Tracks what changed.
+ * @param port - The host's roll rule and commit.
+ * @param layers - The icon layers to place into.
+ * @returns The manager.
+ */
+export function createIconManager(layerManager, port, layers) {
     const icons = new Map();
     const iconKeysByName = new Map();
     const keyToName = new Map();
     /** The reverse of {@link icons}: a pointer hit names a def, so it is a lookup, not a scan. */
     const iconsByDef = new Map();
+    /**
+     * Which of the two icon layers an icon belongs in — the only structural choice left to a caller,
+     * and not a layer name: `onTop` says the icon must not be covered by the others.
+     * @param cfg - The icon's config.
+     * @returns The layer to place it in.
+     */
+    function layerFor(cfg) {
+        return cfg.onTop ? layers.currentPosition : layers.icons;
+    }
     function composeKey(name, key) {
         return key === undefined ? name : `${name}#${key}`;
     }
@@ -45,22 +60,26 @@ export function createIconManager(layerManager, port) {
             nameKeys.delete(iconKey);
         keyToName.delete(iconKey);
     }
-    function createIcon(iconKey, name, cfg) {
-        const layer = layerManager.touchLayer(cfg.layer);
+    function createIcon(iconKey, name, cfg, rotation = cfg.rotation) {
+        const layer = layerFor(cfg);
+        layerManager.touchLayer(layer);
         // 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), {
+        const def = {
+            source: cfg.canvas,
+            bounds: new Rect({ x: cfg.x, y: cfg.y }, ZERO, rotation),
             hidden: cfg.hidden ?? false,
             dim: cfg.dimmed ? 1 : 0,
             origin: cfg.origin,
-            cardinalSnap: cfg.cardinalSnap,
-        });
+        };
+        if (cfg.cardinalSnap)
+            port.attachCardinalSnap(def);
         def.onScale = ({ pixelSize }) => rescaleIcon(def, pixelSize);
         layer.children.push(def);
         const record = {
             imageDef: def,
-            layerName: cfg.layer,
+            layer,
             callback: cfg.onClick ?? null,
         };
         icons.set(iconKey, record);
@@ -69,20 +88,28 @@ export function createIconManager(layerManager, port) {
         return record;
     }
     function recreateIcon(iconKey, name, record, cfg) {
-        const oldLayer = layerManager.resolveLayer(record.layerName);
-        const oldChildren = oldLayer.children;
+        const oldChildren = record.layer.children;
         const idx = oldChildren.indexOf(record.imageDef);
+        // The heading the icon holds, which the replacement inherits when the caller names none: a
+        // cardinal-snap icon carries whole quarters the camera gave it, and a new canvas is no reason
+        // to lose them.
+        const rotation = cfg.rotation ?? record.imageDef.bounds.rotation;
+        // Hidden as well as removed. The renderer commits a def write synchronously and defers the
+        // membership sweep, so a def only spliced out stays drawn — the old canvas, at the old place —
+        // until that sweep lands.
+        record.imageDef.hidden = true;
+        layerManager.touchDef(record.imageDef);
         if (idx >= 0)
             oldChildren.splice(idx, 1);
-        layerManager.touchedLayers.set(record.layerName, oldLayer);
+        layerManager.touchLayer(record.layer);
         icons.delete(iconKey);
         iconsByDef.delete(record.imageDef);
         untrackKey(iconKey);
-        createIcon(iconKey, name, cfg);
+        createIcon(iconKey, name, cfg, rotation);
     }
     function updateIcon(iconKey, name, record, cfg) {
-        if (record.layerName !== cfg.layer) {
-            throw new Error(`renderer: icon "${iconKey}" cannot move between layers (was "${record.layerName}", got "${cfg.layer}")`);
+        if (record.layer !== layerFor(cfg)) {
+            throw new Error(`renderer: icon "${iconKey}" cannot move between layers (was onTop=${!!(record.layer === layers.currentPosition)}, got onTop=${!!cfg.onTop})`);
         }
         if (record.imageDef.source !== cfg.canvas) {
             recreateIcon(iconKey, name, record, cfg);
@@ -140,6 +167,15 @@ export function createIconManager(layerManager, port) {
                 hideIcon(record);
         },
         destroy() {
+            // The layers belong to the host and outlive this manager, so what was put in them comes back
+            // out: a handle that keeps a torn-down instance's icons is not reusable.
+            for (const record of icons.values()) {
+                const children = record.layer.children;
+                const idx = children.indexOf(record.imageDef);
+                if (idx >= 0)
+                    children.splice(idx, 1);
+                layerManager.touchLayer(record.layer);
+            }
             icons.clear();
             iconsByDef.clear();
             iconKeysByName.clear();

package/dist/renderer/index.d.ts

@@ -1,3 +1,5 @@
 export { createWayfindingRenderer } from './createWayfindingRenderer.js';
+export type { WayfindingLayers } from './layers.js';
+export { initWayfindingLayers, resolveWayfindingLayers } from './layers.js';
 export type { IconConfig, RendererPort, WayfindingRenderer } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/renderer/index.js

@@ -1 +1,2 @@
 export { createWayfindingRenderer } from './createWayfindingRenderer.js';
+export { initWayfindingLayers, resolveWayfindingLayers } from './layers.js';

package/dist/renderer/layerManager.d.ts

@@ -1,11 +1,10 @@
 import type { LayerDef, RenderableDef } from '@expofp/renderer';
 import type { RendererPort } from './types.js';
 /**
- * Manages scene layer resolution, caching, dirty-tracking, and flush.
+ * Tracks what changed in the wayfinding layers and commits it.
  *
- * 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.
+ * `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 —
@@ -13,12 +12,11 @@ import type { RendererPort } from './types.js';
  * instance not at all.
  */
 export interface LayerManager {
-    /** 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 its membership as dirty for the next {@link flush}. */
-    touchLayer(name: string): LayerDef;
+    /**
+     * Mark a layer's membership as dirty for the next {@link flush}.
+     * @param layer - The layer whose children changed.
+     */
+    touchLayer(layer: LayerDef): void;
     /**
      * Mark one def's fields as dirty for the next {@link flush}.
      * @param def - The def whose fields were mutated.
@@ -26,12 +24,12 @@ export interface LayerManager {
     touchDef(def: RenderableDef): void;
     /** Commit everything dirty and clear the dirty sets. */
     flush(): void;
-    /** Clear caches and dirty sets. */
+    /** Clear the dirty sets. */
     destroy(): void;
 }
 /**
- * Create a {@link LayerManager} over the scene layers the caller resolved.
- * @param port - The scene layers and the commit function; see {@link RendererPort}.
+ * Create a {@link LayerManager}.
+ * @param port - The commit function; see {@link RendererPort}.
  * @returns The manager.
  */
 export declare function createLayerManager(port: RendererPort): LayerManager;

package/dist/renderer/layerManager.js

@@ -1,29 +1,14 @@
 /**
- * Create a {@link LayerManager} over the scene layers the caller resolved.
- * @param port - The scene layers and the commit function; see {@link RendererPort}.
+ * Create a {@link LayerManager}.
+ * @param port - The commit function; see {@link RendererPort}.
  * @returns The manager.
  */
 export function createLayerManager(port) {
-    const allLayers = port.layers;
-    const layerCache = new Map();
-    const touchedLayers = new Map();
+    const touchedLayers = new Set();
     const touchedDefs = new Set();
     return {
-        touchedLayers,
-        resolveLayer(name) {
-            const cached = layerCache.get(name);
-            if (cached)
-                return cached;
-            const layer = allLayers.find((candidate) => candidate.name === name);
-            if (!layer)
-                throw new Error(`renderer: layer "${name}" not found in scene`);
-            layerCache.set(name, layer);
-            return layer;
-        },
-        touchLayer(name) {
-            const layer = this.resolveLayer(name);
-            touchedLayers.set(name, layer);
-            return layer;
+        touchLayer(layer) {
+            touchedLayers.add(layer);
         },
         touchDef(def) {
             touchedDefs.add(def);
@@ -31,17 +16,16 @@ export function createLayerManager(port) {
         flush() {
             if (touchedLayers.size === 0 && touchedDefs.size === 0)
                 return;
-            for (const layer of touchedLayers.values()) {
+            for (const layer of touchedLayers) {
                 layer.children = [...layer.children];
             }
-            port.update(...touchedLayers.values(), ...touchedDefs);
+            port.update(...touchedLayers, ...touchedDefs);
             touchedLayers.clear();
             touchedDefs.clear();
         },
         destroy() {
             touchedLayers.clear();
             touchedDefs.clear();
-            layerCache.clear();
         },
     };
 }

package/dist/renderer/layers.d.ts

@@ -0,0 +1,39 @@
+import type { ImageDef, LayerDef, LineDef } from '@expofp/renderer';
+/**
+ * The layers wayfinding fills, resolved out of the block the host mounted.
+ *
+ * One layer per def kind is not a choice: `RenderableDefCollection` admits no mixed children, so
+ * images and lines cannot share one. Which layers exist and how they stack among themselves is this
+ * package's business; where the block sits in a scene is the host's.
+ */
+export interface WayfindingLayers {
+    /** Dot trail between an off-graph anchor and the route. */
+    readonly trail: LayerDef<ImageDef>;
+    /** Static route lines — passed and remaining. */
+    readonly lines: LayerDef<LineDef>;
+    /** The chase animation over the remaining route. */
+    readonly linesAnimated: LayerDef<LineDef>;
+    /** Endpoint, transition and host icons. The one layer worth making pickable. */
+    readonly icons: LayerDef<ImageDef>;
+    /** The live position, above the icons so an endpoint pin never covers it. */
+    readonly currentPosition: LayerDef<ImageDef>;
+}
+/**
+ * Creates the wayfinding block, empty.
+ *
+ * Mount it wherever wayfinding belongs in the scene — the route has to draw over the pathway layers
+ * (efp #1206). `createWayfinding` finds it there and fills it.
+ * @returns The block to mount.
+ */
+export declare function initWayfindingLayers(): LayerDef<LayerDef>;
+/**
+ * Finds the mounted block in a scene and hands back the layers inside it, so a host that mounted
+ * the block needs to carry nothing but its scene.
+ *
+ * The block sits directly under the scene's root layer, which is where the host mounted it.
+ * @param sceneRoot - The scene's root layer.
+ * @returns The layers to fill.
+ * @throws If the scene holds no wayfinding block — it was never mounted, or this is another scene.
+ */
+export declare function resolveWayfindingLayers(sceneRoot: LayerDef): WayfindingLayers;
+//# sourceMappingURL=layers.d.ts.map

package/dist/renderer/layers.js

@@ -0,0 +1,62 @@
+// The block's own layer names. Private: after this module nothing addresses a wayfinding layer by
+// name — the host mounts the block, and the renderer holds the references.
+const BLOCK_LAYER_NAME = 'wayfinding';
+const TRAIL_LAYER_NAME = 'wf-trail-points';
+const LINES_LAYER_NAME = 'wf-lines';
+const LINES_ANIMATED_LAYER_NAME = 'wf-lines-animated';
+const ICONS_LAYER_NAME = 'wf-points';
+const CURRENT_POSITION_LAYER_NAME = 'wf-current-position';
+/**
+ * Creates the wayfinding block, empty.
+ *
+ * Mount it wherever wayfinding belongs in the scene — the route has to draw over the pathway layers
+ * (efp #1206). `createWayfinding` finds it there and fills it.
+ * @returns The block to mount.
+ */
+export function initWayfindingLayers() {
+    const trail = { name: TRAIL_LAYER_NAME, children: [] };
+    const lines = { name: LINES_LAYER_NAME, children: [] };
+    const linesAnimated = { name: LINES_ANIMATED_LAYER_NAME, children: [] };
+    const icons = { name: ICONS_LAYER_NAME, children: [] };
+    const currentPosition = {
+        name: CURRENT_POSITION_LAYER_NAME,
+        children: [],
+    };
+    return {
+        name: BLOCK_LAYER_NAME,
+        // Bottom → top, and the only place the block's order is stated.
+        children: [trail, lines, linesAnimated, icons, currentPosition],
+        // Once for the block, which the children inherit: a search dims the venue behind the route,
+        // never the route.
+        dim: 0,
+    };
+}
+/**
+ * Finds the mounted block in a scene and hands back the layers inside it, so a host that mounted
+ * the block needs to carry nothing but its scene.
+ *
+ * The block sits directly under the scene's root layer, which is where the host mounted it.
+ * @param sceneRoot - The scene's root layer.
+ * @returns The layers to fill.
+ * @throws If the scene holds no wayfinding block — it was never mounted, or this is another scene.
+ */
+export function resolveWayfindingLayers(sceneRoot) {
+    const children = sceneRoot.children;
+    const root = children.find((child) => 'name' in child && child.name === BLOCK_LAYER_NAME && 'children' in child);
+    if (!root)
+        throw new Error('The scene holds no wayfinding block — mount `root` first.');
+    const byName = new Map(root.children.map((layer) => [layer.name, layer]));
+    function layerOf(name) {
+        const layer = byName.get(name);
+        if (!layer)
+            throw new Error(`The wayfinding block is missing its \`${name}\` layer.`);
+        return layer;
+    }
+    return {
+        trail: layerOf(TRAIL_LAYER_NAME),
+        lines: layerOf(LINES_LAYER_NAME),
+        linesAnimated: layerOf(LINES_ANIMATED_LAYER_NAME),
+        icons: layerOf(ICONS_LAYER_NAME),
+        currentPosition: layerOf(CURRENT_POSITION_LAYER_NAME),
+    };
+}

package/dist/renderer/routeLineManager.d.ts

@@ -1,4 +1,5 @@
 import type { LayerManager } from './layerManager.js';
+import type { WayfindingLayers } from './layers.js';
 import type { RendererPort, RouteColors } from './types.js';
 /**
  * Manages static route lines (passed + remaining) and an animated overlay
@@ -23,9 +24,7 @@ export interface RouteLineManager {
             x: number;
             y: number;
         };
-    }[], options: {
-        readonly linesLayer: string;
-        readonly animatedLinesLayer: string;
+    }[], options?: {
         readonly resetAnimation?: boolean;
     }): void;
     /** Stop animation, wipe both lines layers. */
@@ -36,10 +35,11 @@ export interface RouteLineManager {
 /**
  * Create a {@link RouteLineManager} that renders `LineDef` segments
  * into layers managed by the given {@link LayerManager}.
- * @param layerManager - Where the lines are placed and dirt is tracked.
+ * @param layerManager - Tracks what changed.
  * @param colors - The route palette.
  * @param port - The commit function the animation ticks through.
+ * @param layers - The two line layers to draw into.
  * @returns The manager.
  */
-export declare function createRouteLineManager(layerManager: LayerManager, colors: RouteColors, port: RendererPort): RouteLineManager;
+export declare function createRouteLineManager(layerManager: LayerManager, colors: RouteColors, port: RendererPort, layers: Pick<WayfindingLayers, 'lines' | 'linesAnimated'>): RouteLineManager;
 //# sourceMappingURL=routeLineManager.d.ts.map