@mapvx/web-js 3.5.0-dev.3 → 3.5.0-dev.4

package/dist/es/controllers/routeController.js

@@ -12,6 +12,24 @@ const DEFAULT_AUTO_FIT_PADDING = {
     bottom: 150,
     left: 150,
 };
+/**
+ * Longest a step waits for its line to be uploaded before animating anyway, so
+ * a stalled worker never freezes the route.
+ *
+ * A deadline rather than a frame count. `animateStep` is handed a `timestamp`
+ * already, and a frame count would stretch to three seconds or more on the
+ * 20-30 fps panels this wait exists for — the devices where a frozen marker at
+ * every step boundary is most visible.
+ */
+const MAX_SOURCE_WAIT_MS = 1500;
+/** Fully transparent: the part of a step line the reveal has not reached yet. */
+const TRANSPARENT_COLOR = "rgba(0, 0, 0, 0)";
+/**
+ * Width of the reveal cut-off, as a fraction of the step line. One texel of
+ * maplibre's 256-sample gradient ramp, i.e. the narrowest edge the ramp can
+ * actually resolve.
+ */
+const REVEAL_EDGE = 1 / 256;
 /**
  * Longest gap between two frames, in milliseconds, that still counts as
  * animation time.
@@ -62,9 +80,10 @@ export class RouteController {
      * Add MapLibre sources and layers for a single route instance.
      *
      * All three sources set `lineMetrics`: maplibre computes `line-progress` only
-     * when a source asks it to, and `preparePaintForLayer` emits a
-     * `line-progress` gradient for a GradientStyle. Without it, a consumer
-     * setting a gradient route style silently got no gradient at all.
+     * when a source asks it to. The CURRENT layer needs it to reveal the step
+     * line as the marker advances, and `preparePaintForLayer` emits a
+     * `line-progress` gradient for a GradientStyle on any of the three — without
+     * it, a consumer setting a gradient route style silently got no gradient.
      */
     addSourcesAndLayersForRoute(instance) {
         this.map.addSource(instance.aheadId, {
@@ -137,9 +156,36 @@ export class RouteController {
     addSourcesAndLayers() {
         for (const instance of this.routes.values()) {
             this.addSourcesAndLayersForRoute(instance);
+            this.restoreLayerPaint(instance);
         }
         this.syncRouteCollision();
     }
+    /**
+     * Re-apply the paint a style reload dropped.
+     *
+     * {@link addSourcesAndLayersForRoute} re-adds the layers with no paint at all, so
+     * without this the route keeps its geometry but loses its colors — and the CURRENT
+     * layer loses its `line-gradient`, which is the only thing hiding the part of the
+     * step the marker has not reached yet: the whole step would be drawn at once.
+     */
+    restoreLayerPaint(instance) {
+        var _a;
+        for (const [layerId, drawConfig] of Object.entries(instance.layerDrawConfigs)) {
+            this.setLayerPaint(instance, layerId, drawConfig);
+        }
+        // `?? 0`: a step whose geometry was loaded while the style was mid-swap
+        // never got a reveal recorded, because `applyReveal` bails when there is no
+        // layer to paint. Leaving the gradient off entirely then draws the whole
+        // step at once in the traveled color, and the `awaitingSources` hold, the
+        // rotation phase, the floor-change wait and a pause can each postpone the
+        // frame that would correct it — indefinitely, in the case of a pause.
+        // Revealing nothing is the safe default.
+        const reveal = (_a = instance.revealFraction) !== null && _a !== void 0 ? _a : 0;
+        // Force the update: `applyReveal` skips a fraction it believes is already on
+        // the map, and the fresh layer has no gradient at all.
+        instance.revealFraction = undefined;
+        this.applyReveal(instance, reveal);
+    }
     /**
      * Recompute the GLB route-transparency collision path from all active routes and push it to the
      * map. Every polyline point of every step is tagged with the floor its segment is drawn on (same
@@ -170,7 +216,7 @@ export class RouteController {
         this.lastAddedRouteId = instance.id;
         this.addSourcesAndLayersForRoute(instance);
         this.setSourceData(instance, instance.aheadId, route.steps);
-        this.setLayerPaint(instance.aheadId, drawConfig);
+        this.setLayerPaint(instance, instance.aheadId, drawConfig);
         this.updateLayerFilter(instance.aheadId);
         this.syncRouteCollision();
     }
@@ -272,7 +318,7 @@ export class RouteController {
         const aheadSource = this.map.getSource(instance.aheadId);
         aheadSource === null || aheadSource === void 0 ? void 0 : aheadSource.setData(instance.aheadSourceData);
         // Ensure paint is set on the behind layer
-        this.setLayerPaint(instance.behindId, behindDrawConfig);
+        this.setLayerPaint(instance, instance.behindId, behindDrawConfig);
         this.updateLayerFilter(instance.behindId);
         this.updateLayerFilter(instance.aheadId);
     }
@@ -308,55 +354,199 @@ export class RouteController {
             source === null || source === void 0 ? void 0 : source.setData(instance.behindSourceData);
         }
     }
-    setCurrentSourceData(instance, step) {
+    /**
+     * Upload the whole polyline of `step` as the CURRENT feature and reset its
+     * reveal to zero. The line is then drawn progressively by moving a
+     * `line-progress` cut-off (see {@link applyReveal}) instead of re-uploading a
+     * growing geometry every frame: a paint change is applied synchronously, while
+     * a `setData` goes through the worker and lands several frames after the DOM
+     * marker already moved — on a slow device the marker visibly ran ahead of
+     * its line.
+     */
+    loadStepGeometry(instance, step) {
+        var _a;
         instance.currentSourceData.properties = {
             floor_key: this.getFloorKeyForStep(step),
         };
-        const coordinate = step === null || step === void 0 ? void 0 : step.coordinates[0];
-        if (coordinate != null) {
-            instance.currentSourceData.geometry.coordinates = [[coordinate.lng, coordinate.lat]];
-        }
-        else {
-            instance.currentSourceData.geometry.coordinates = [];
-        }
+        const coordinates = (_a = step === null || step === void 0 ? void 0 : step.coordinates) !== null && _a !== void 0 ? _a : [];
+        // A LineString needs at least two positions; anything shorter draws nothing.
+        instance.currentSourceData.geometry.coordinates =
+            coordinates.length >= 2 ? coordinates.map((c) => [c.lng, c.lat]) : [];
+        const cumulative = [0];
+        for (let i = 1; i < coordinates.length; i++) {
+            cumulative.push(cumulative[i - 1] + NavFunctions.distance(coordinates[i - 1], coordinates[i]));
+        }
+        instance.stepMetrics = { cumulative, total: cumulative[cumulative.length - 1] };
+        instance.revealFraction = undefined;
+        this.applyReveal(instance, 0);
         const source = this.map.getSource(instance.currentId);
         source === null || source === void 0 ? void 0 : source.setData(instance.currentSourceData);
     }
-    setLayerPaint(layerId, drawConfig) {
+    /**
+     * Fraction of the step line up to `coordinatesIndex` plus `extraMeters` along
+     * the following segment.
+     */
+    fractionAlongStep(instance, coordinatesIndex, extraMeters) {
+        var _a;
+        const metrics = instance.stepMetrics;
+        if (!metrics || metrics.total <= 0)
+            return 1;
+        const index = Math.min(coordinatesIndex, metrics.cumulative.length - 1);
+        return (((_a = metrics.cumulative[index]) !== null && _a !== void 0 ? _a : 0) + extraMeters) / metrics.total;
+    }
+    /**
+     * Show the first `fraction` of the CURRENT step line: a `line-gradient` step on
+     * `line-progress` that turns transparent past the cut-off. MapLibre treats it
+     * as a plain paint update (a 256px ramp re-rendered on the next draw), so the
+     * line head and the marker move in the same frame.
+     *
+     * The paint is set with `validate: false`: this runs on every animation frame and
+     * the expression is built here, not taken from a consumer, so re-parsing and
+     * re-validating it 60 times a second is pure overhead on a totem-class device.
+     */
+    applyReveal(instance, fraction) {
+        const color = instance.currentLineColor;
+        if (color === undefined)
+            return;
+        const clamped = Math.max(0, Math.min(1, fraction));
+        if (instance.revealFraction === clamped)
+            return;
+        // A full style swap removes the route's sources and layers and re-adds them a
+        // few frames later. Painting a layer that is not there fires a MapLibre error on
+        // every animation frame; `revealFraction` is deliberately left untouched so
+        // `restoreLayerPaint` re-applies this reveal once the layers are back.
+        if (!this.hasSource(instance.currentId))
+            return;
+        instance.revealFraction = clamped;
+        this.map.setPaintProperty(instance.currentId, "line-gradient", this.revealGradient(color, clamped), { validate: false });
+    }
+    /**
+     * The `line-gradient` that shows the first `fraction` of the step line and
+     * nothing after it.
+     *
+     * Deliberately built on `interpolate` rather than the `step` this reads like.
+     * `LineStyleLayer._handleSpecialPaintPropertyUpdate` sets `stepInterpolant`
+     * for any `step` root, and `stepInterpolant` swaps the gradient ramp from a
+     * fixed 256 texels to
+     * `clamp(nextPowerOfTwo(lineLength * 1024 * potentialOverzoom), 256, maxTextureSize)`
+     * — 4096 to 16384 in practice. Every `setPaintProperty` here bumps
+     * `gradientVersion`, so that ramp would be re-rendered and re-uploaded once
+     * per visible tile per frame, which is the opposite of what this reveal is
+     * for. An `interpolate` root keeps the ramp at 256 texels; the cost is a
+     * one-texel soft edge at the cut-off instead of a hard one.
+     */
+    revealGradient(color, fraction) {
+        if (fraction <= 0)
+            return TRANSPARENT_COLOR;
+        // `line-progress` reaches exactly 1 at the last vertex, so a fully revealed
+        // line is just the line's own color, with no cut-off to express.
+        if (fraction >= 1)
+            return color;
+        return [
+            "interpolate",
+            ["linear"],
+            ["line-progress"],
+            fraction,
+            color,
+            // `interpolate` clamps to its domain, so one texel past the cut-off is
+            // enough to make everything beyond it transparent.
+            Math.min(fraction + REVEAL_EDGE, 1),
+            TRANSPARENT_COLOR,
+        ];
+    }
+    /**
+     * Whether the route's three sources have finished uploading their latest
+     * data, i.e. what is on screen matches what was last set. Maps without
+     * `isSourceLoaded` (test doubles) count as ready.
+     */
+    stepSourcesReady(instance) {
+        try {
+            // CURRENT alone. It carries the step being drawn, which is what has to be
+            // on screen for the line, the floor and the marker to change together.
+            // AHEAD and BEHIND hold the whole route and are rewritten in full at every
+            // boundary, so waiting on them made the freeze at each step scale with the
+            // route's total length rather than the step's — and on a long route that
+            // is the difference between imperceptible and hitting the deadline.
+            if (!this.map.getSource(instance.currentId))
+                return false;
+            return this.map.isSourceLoaded(instance.currentId) !== false;
+        }
+        catch (_a) {
+            // The map is briefly style-less mid-swap and `getSource` throws there. This runs
+            // inside a `requestAnimationFrame` callback, where an exception would kill the
+            // animation loop for good, so treat it as "not ready yet" instead.
+            return false;
+        }
+    }
+    /** Whether `sourceId` is currently on the map (false while a style swap is in flight). */
+    hasSource(sourceId) {
+        try {
+            return this.map.getSource(sourceId) != null;
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+    /**
+     * Apply a floor switch that was deferred until the next step's line was
+     * uploaded, then put the marker where that step starts. Floor, line and
+     * marker change in the same frame.
+     */
+    applyPendingFloor(instance) {
+        var _a;
+        const pending = (_a = instance.conditions) === null || _a === void 0 ? void 0 : _a.pendingFloor;
+        if (!pending || !instance.conditions)
+            return;
+        instance.conditions.pendingFloor = undefined;
+        this.updatePlaceFloorForRouting(instance, pending.placeId, pending.floorKey);
+        this.setMarkerLngLat(instance, pending.location);
+    }
+    setLayerPaint(instance, layerId, drawConfig) {
+        instance.layerDrawConfigs[layerId] = drawConfig;
         const paintConfig = this.preparePaintForLayer(drawConfig);
         for (const property in paintConfig) {
             this.map.setPaintProperty(layerId, property, paintConfig[property]);
         }
     }
-    preparePaintForLayer(drawConfig) {
+    /**
+     * Set the paint the step line is drawn with, resolving its color once.
+     *
+     * See {@link RouteInstance.currentLineColor}: resolving a gradient allocates
+     * and can throw, and the reveal would otherwise redo it on every frame.
+     */
+    setCurrentDrawConfig(instance, drawConfig) {
+        instance.currentDrawConfig = drawConfig;
+        instance.currentLineColor = this.lineColorExpression(drawConfig);
+    }
+    /** The color of a route line: a solid color or a `line-progress` gradient ramp. */
+    lineColorExpression(drawConfig) {
         if ("color" in drawConfig.routeStyle) {
             // Check for propriety unique to SolidStyle
-            return {
-                "line-color": drawConfig.routeStyle.color,
-                "line-gradient": null, // null to unset the existing value
-                "line-width": drawConfig.polylineWidth,
-            };
+            return drawConfig.routeStyle.color;
         }
-        else {
-            // Is GradienteStyle
-            const { colors, positions } = drawConfig.routeStyle;
-            const positionsToUse = positions !== null && positions !== void 0 ? positions : createPositionsForStops(colors.length);
-            if (positionsToUse.length !== colors.length) {
-                throw new Error("Error: position array has different length than colors array");
-            }
-            const stops = createStops(positionsToUse, colors);
-            const gradient = [
-                "interpolate",
-                ["linear"],
-                ["line-progress"],
-                ...stops,
-            ];
+        // Is GradienteStyle
+        const { colors, positions } = drawConfig.routeStyle;
+        const positionsToUse = positions !== null && positions !== void 0 ? positions : createPositionsForStops(colors.length);
+        if (positionsToUse.length !== colors.length) {
+            throw new Error("Error: position array has different length than colors array");
+        }
+        const stops = createStops(positionsToUse, colors);
+        return ["interpolate", ["linear"], ["line-progress"], ...stops];
+    }
+    preparePaintForLayer(drawConfig) {
+        const color = this.lineColorExpression(drawConfig);
+        if (typeof color === "string") {
             return {
-                "line-color": null,
-                "line-gradient": gradient,
+                "line-color": color,
+                "line-gradient": null, // null to unset the existing value
                 "line-width": drawConfig.polylineWidth,
             };
         }
+        return {
+            "line-color": null,
+            "line-gradient": color,
+            "line-width": drawConfig.polylineWidth,
+        };
     }
     /**
      * Update the filter of the layer referenced with a ID.
@@ -495,15 +685,11 @@ export class RouteController {
         this.updatePlaceFloorForRouting(instance, firstStep.startInsidePlace, firstStep.startInsideFloor);
         this.setSourceData(instance, instance.aheadId, route.steps);
         this.setSourceData(instance, instance.behindId, []);
-        instance.currentSourceData.properties = {
-            floor_key: this.getFloorKeyForStep(firstStep),
-        };
-        instance.currentSourceData.geometry.coordinates = [
-            [firstStep.coordinates[0].lng, firstStep.coordinates[0].lat],
-        ];
-        this.setLayerPaint(instance.aheadId, drawConfig.aheadConfig);
-        this.setLayerPaint(instance.behindId, drawConfig.behindConfig);
-        this.setLayerPaint(instance.currentId, drawConfig.behindConfig);
+        this.setLayerPaint(instance, instance.aheadId, drawConfig.aheadConfig);
+        this.setLayerPaint(instance, instance.behindId, drawConfig.behindConfig);
+        this.setLayerPaint(instance, instance.currentId, drawConfig.behindConfig);
+        this.setCurrentDrawConfig(instance, drawConfig.behindConfig);
+        this.loadStepGeometry(instance, firstStep);
         instance.animationConfig = animationConfig;
         instance.routeMarker = new MarkerAttribute({
             coordinate: firstStep.startLocation,
@@ -537,14 +723,34 @@ export class RouteController {
             progress: 0,
             resetTime: false,
             waitStartTime: undefined,
+            awaitingSources: true,
             animationId: requestAnimationFrame((time) => this.animateStep(time, instance)),
             onFinish: (time) => this.prepareForNextStep(time, instance),
         };
         (_c = animationConfig.callBack) === null || _c === void 0 ? void 0 : _c.call(animationConfig, { isFinished: false, step: firstStep });
         this.syncRouteCollision();
     }
-    clearRouteInstance(instance) {
+    /**
+     * Tear one route instance down.
+     *
+     * `applyPendingFloorChange` decides what happens to a floor switch this
+     * instance had decided on but not yet shown. Removing a single route mid-walk
+     * applies it: the consumer may be removing the route from the step callback,
+     * and dropping the switch would leave the map on the floor the route has
+     * already left. Clearing every route does not — a floor switch is a visible
+     * camera and filter change plus an `onFloorChange` to the consumer, and
+     * `removeAllRoutes` is what teardown calls, where moving the map is
+     * a side effect nobody asked for and a consumer that re-enters from
+     * `onFloorChange` re-enters teardown.
+     */
+    clearRouteInstance(instance, applyPendingFloorChange = true) {
         var _a;
+        if (applyPendingFloorChange) {
+            this.applyPendingFloor(instance);
+        }
+        else if (instance.conditions) {
+            instance.conditions.pendingFloor = undefined;
+        }
         (_a = instance.routeMarker) === null || _a === void 0 ? void 0 : _a.remove();
         instance.routeMarker = undefined;
         this.setSourceData(instance, instance.aheadId, []);
@@ -584,7 +790,7 @@ export class RouteController {
      */
     removeAllRoutes() {
         for (const instance of this.routes.values()) {
-            this.clearRouteInstance(instance);
+            this.clearRouteInstance(instance, false);
             this.removeSourcesAndLayersForRoute(instance);
         }
         this.routes.clear();
@@ -662,14 +868,7 @@ export class RouteController {
         this.updatePlaceFloorForRouting(instance, firstStep.startInsidePlace, firstStep.startInsideFloor);
         this.setSourceData(instance, instance.aheadId, instance.route.steps);
         this.setSourceData(instance, instance.behindId, []);
-        instance.currentSourceData.properties = {
-            floor_key: this.getFloorKeyForStep(firstStep),
-        };
-        instance.currentSourceData.geometry.coordinates = [
-            [firstStep.coordinates[0].lng, firstStep.coordinates[0].lat],
-        ];
-        const source = this.map.getSource(instance.currentId);
-        source === null || source === void 0 ? void 0 : source.setData(instance.currentSourceData);
+        this.loadStepGeometry(instance, firstStep);
         (_a = this.setMarkerRotation(instance, 0)) === null || _a === void 0 ? void 0 : _a.setLngLat(firstStep.startLocation).addTo(this.map);
         // Auto-fit by place if enabled
         if (((_b = instance.animationConfig.autoFitByPlace) === null || _b === void 0 ? void 0 : _b.enabled) && instance.route.steps.length > 0) {
@@ -698,6 +897,7 @@ export class RouteController {
             progress: 0,
             resetTime: false,
             waitStartTime: undefined,
+            awaitingSources: true,
             animationId: requestAnimationFrame((time) => this.animateStep(time, instance)),
             onFinish: (time) => this.prepareForNextStep(time, instance),
         };
@@ -735,10 +935,11 @@ export class RouteController {
         this.updatePlaceFloorForRouting(instance, firstStep.startInsidePlace, firstStep.startInsideFloor);
         this.setSourceData(instance, instance.aheadId, route.steps);
         this.setSourceData(instance, instance.behindId, []);
-        this.setCurrentSourceData(instance, firstStep);
-        this.setLayerPaint(instance.aheadId, drawConfig.aheadConfig);
-        this.setLayerPaint(instance.behindId, drawConfig.behindConfig);
-        this.setLayerPaint(instance.currentId, drawConfig.behindConfig);
+        this.setLayerPaint(instance, instance.aheadId, drawConfig.aheadConfig);
+        this.setLayerPaint(instance, instance.behindId, drawConfig.behindConfig);
+        this.setLayerPaint(instance, instance.currentId, drawConfig.behindConfig);
+        this.setCurrentDrawConfig(instance, drawConfig.behindConfig);
+        this.loadStepGeometry(instance, firstStep);
         instance.animationConfig = animationConfig;
         instance.routeMarker = new MarkerAttribute({
             coordinate: firstStep.startLocation,
@@ -788,7 +989,7 @@ export class RouteController {
                 const step = instance.route.steps[index];
                 this.setSourceData(instance, instance.behindId, behindSteps);
                 this.setSourceData(instance, instance.aheadId, aheadSteps);
-                this.setCurrentSourceData(instance, step);
+                this.loadStepGeometry(instance, step);
                 instance.conditions.index = index;
                 // The status settles before either callback, as everywhere else: no frame
                 // is live once `animateStep` hands over to `onFinish`, so "WAITING" is
@@ -880,7 +1081,7 @@ export class RouteController {
             const step = instance.route.steps[index];
             this.setSourceData(instance, instance.behindId, behindSteps);
             this.setSourceData(instance, instance.aheadId, aheadSteps);
-            this.setCurrentSourceData(instance, step);
+            this.loadStepGeometry(instance, step);
             if (step.startInsideFloor != step.endInsideFloor && step.startInsideFloor) {
                 this.updatePlaceFloorForRouting(instance, step.startInsidePlace, step.startInsideFloor);
             }
@@ -954,21 +1155,41 @@ export class RouteController {
         const aheadSteps = instance.route.steps.slice(index + 1);
         this.setSourceData(instance, instance.behindId, behindSteps);
         this.setSourceData(instance, instance.aheadId, aheadSteps);
-        instance.currentSourceData.geometry.coordinates = [];
         if (index + 1 < instance.route.steps.length) {
             const step = instance.route.steps[index + 1];
-            instance.currentSourceData.geometry.coordinates.push([
-                step.startLocation.lng,
-                step.startLocation.lat,
-            ]);
-            instance.currentSourceData.properties = {
-                floor_key: this.getFloorKeyForStep(step),
-            };
+            this.loadStepGeometry(instance, step);
             instance.conditions.startTime = timestamp;
             instance.conditions.index++;
             instance.conditions.coordinatesIndex = 0;
             instance.conditions.progress = 0;
             instance.conditions.rotatingIcon = true;
+            // The step starts once its line (and the updated behind/ahead lines) are
+            // on screen; a floor switch decided by the previous step, or implied by a
+            // step that starts on another floor, is applied at that same moment.
+            instance.conditions.awaitingSources = true;
+            instance.conditions.awaitDeadline = undefined;
+            // Compared against the floor the PREVIOUS step ended on, not the map's current
+            // floor: the route decides its own floor changes, so a user who browsed to
+            // another floor mid-animation is not yanked back at every step boundary.
+            const previousStep = instance.route.steps[index];
+            // Against the previous step's *effective* floor, not its raw
+            // `endInsideFloor`. Venue data routinely carries `startInsideFloor` with
+            // no `endInsideFloor` — `getFloorKeyForStep` exists to resolve exactly
+            // that shape — and comparing against the raw field made every boundary
+            // on such a route look like a floor change: the map moved, the consumer
+            // got an `onFloorChange`, a settle poll ran and the step callback was
+            // deferred a frame, at each step. A user who had browsed to another floor
+            // was yanked back, which is what the deferral above is meant to avoid.
+            const previousFloor = this.getFloorKeyForStep(previousStep);
+            if (!instance.conditions.pendingFloor &&
+                step.startInsideFloor &&
+                step.startInsideFloor !== previousFloor) {
+                instance.conditions.pendingFloor = {
+                    placeId: step.startInsidePlace,
+                    floorKey: step.startInsideFloor,
+                    location: step.startLocation,
+                };
+            }
             if (!compareLatLng(instance.route.steps[index].endLocation, step.startLocation))
                 instance.conditions.nextFloorFirstStepIndex = index + 2;
             instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
@@ -983,12 +1204,28 @@ export class RouteController {
                     this.mapvxMap.fitRouteByPlace(instance.route, stepPlaceId, fitOptions);
                 }
             }
-            (_d = (_c = instance.animationConfig).callBack) === null || _d === void 0 ? void 0 : _d.call(_c, {
-                isFinished: false,
-                step: instance.route.steps[index + 1],
-            });
+            if (instance.conditions.pendingFloor) {
+                // The switch lands a few frames later, in `animateStep`. Firing the callback
+                // now would report the step while the map is still on the previous floor —
+                // and a consumer that stops the route from it would drop the switch entirely.
+                instance.conditions.pendingStepCallback = step;
+            }
+            else {
+                (_d = (_c = instance.animationConfig).callBack) === null || _d === void 0 ? void 0 : _d.call(_c, { isFinished: false, step });
+            }
         }
         else {
+            // finishes animation
+            this.applyPendingFloor(instance);
+            // That reached `onFloorChange`, and a consumer removing the route from it
+            // has already had `clearRouteInstance` null `animationConfig` and settle
+            // the status at "NO_ROUTE". Both lines below write through it — the
+            // `?.` is on `callBack`, not on `animationConfig` — so without this the
+            // branch threw a TypeError out of the rAF callback, and overwrote a
+            // finished instance's status with "FINISHED". `animateStep`'s release
+            // path takes the same guard after the same call.
+            if (instance.conditions == null || instance.animationConfig == null)
+                return;
             // The status settles before the consumer hears that the route finished,
             // for the same reason `startAnimating` and `restartAnimation` order it
             // that way. A consumer that relaunches from this callback — looping a
@@ -1002,7 +1239,7 @@ export class RouteController {
         }
     }
     animateStep(timestamp, instance) {
-        var _a;
+        var _a, _b, _c, _d;
         if (instance.conditions == null || instance.animationConfig == null || instance.route == null) {
             throw new Error("Error: conditions and animationConfig should not be null at this point");
         }
@@ -1019,6 +1256,53 @@ export class RouteController {
             instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
             return;
         }
+        if (instance.conditions.awaitingSources) {
+            let deadline = (_a = instance.conditions.awaitDeadline) !== null && _a !== void 0 ? _a : timestamp + MAX_SOURCE_WAIT_MS;
+            // The deadline is wall clock, and this block returns before the frame-gap
+            // branch below can ever run, so it needs that branch's shift applied here
+            // — the same one `waitStartTime` gets, for the same reason. A backgrounded
+            // tab or a pause longer than the deadline would otherwise release the step
+            // on the first frame back without once asking whether its line is on
+            // screen, which is the desync the wait exists to prevent.
+            if (previousFrameTime != null && timestamp - previousFrameTime > MAX_FRAME_GAP_MS) {
+                deadline += timestamp - previousFrameTime;
+            }
+            instance.conditions.awaitDeadline = deadline;
+            if (!this.stepSourcesReady(instance) && timestamp < deadline) {
+                // Hold the clock: the step starts when its line can be seen.
+                instance.conditions.startTime = timestamp;
+                instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
+                return;
+            }
+            instance.conditions.awaitingSources = false;
+            instance.conditions.awaitDeadline = undefined;
+            instance.conditions.startTime = timestamp;
+            const heldStep = instance.conditions.pendingStepCallback;
+            instance.conditions.pendingStepCallback = undefined;
+            // The frame that releases the wait draws nothing: it queues its successor
+            // and hands control to the consumer, and that successor does the drawing.
+            //
+            // The queue has to come first. Both calls below reach consumer code —
+            // `applyPendingFloor` through the `onFloorChange` handler, and the held
+            // step callback directly — and a `pauseAnimation()` from either one
+            // cancels whatever id sits in `conditions.animationId`. While that id was
+            // the frame already executing, cancelling it did nothing: the loop kept
+            // running under a `PAUSED` status, and the matching `resumeAnimation()`
+            // passed its status guard and installed a second concurrent rAF chain on
+            // the same instance. Queueing first gives that pause a pending frame to
+            // cancel, and returning afterwards means this frame does not queue a
+            // replacement for the one it just cancelled.
+            instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
+            this.applyPendingFloor(instance);
+            // `onFloorChange` may have removed the route; everything below reads
+            // `conditions`.
+            if (instance.conditions == null || instance.animationConfig == null)
+                return;
+            if (heldStep) {
+                (_c = (_b = instance.animationConfig).callBack) === null || _c === void 0 ? void 0 : _c.call(_b, { isFinished: false, step: heldStep });
+            }
+            return;
+        }
         if (resetTime) {
             startTime = timestamp - progress;
             instance.conditions.startTime = startTime;
@@ -1091,7 +1375,15 @@ export class RouteController {
                     return;
                 }
             }
-            if (step.startInsideFloor !== step.endInsideFloor) {
+            // There has to be a floor to switch *to*. An absent `startInsideFloor` is
+            // meaningful — that is a step entering the building from outdoors — but an
+            // absent `endInsideFloor` is not: venue data routinely omits it on a step
+            // that does not change floor, and reading that as "different" made every
+            // such step stall for `changeFloorTime` and then queue a switch whose
+            // `floorKey` was `undefined`. `updatePlaceFloorForRouting` drops that
+            // silently, but not before it has occupied the `pendingFloor` slot the
+            // step boundary needed for a real one.
+            if (step.endInsideFloor && step.startInsideFloor !== step.endInsideFloor) {
                 if (waitStartTime == null) {
                     instance.conditions.waitStartTime = timestamp;
                     instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
@@ -1102,9 +1394,21 @@ export class RouteController {
                     return;
                 }
                 else {
-                    this.updatePlaceFloorForRouting(instance, step.endInsidePlace, step.endInsideFloor);
-                    this.setMarkerLngLat(instance, step.endLocation);
                     instance.conditions.waitStartTime = undefined;
+                    if (instance.conditions.isStepByStep) {
+                        // Step-by-step mode is user-driven: switch right away, as before.
+                        this.updatePlaceFloorForRouting(instance, step.endInsidePlace, step.endInsideFloor);
+                        this.setMarkerLngLat(instance, step.endLocation);
+                    }
+                    else {
+                        // Defer the switch until the next step's line is uploaded, so floor,
+                        // line and marker change together (see applyPendingFloor).
+                        instance.conditions.pendingFloor = {
+                            placeId: step.endInsidePlace,
+                            floorKey: step.endInsideFloor,
+                            location: step.endLocation,
+                        };
+                    }
                     onFinish === null || onFinish === void 0 ? void 0 : onFinish(timestamp);
                     return;
                 }
@@ -1120,22 +1424,17 @@ export class RouteController {
             // ignored `stepTime` altogether and collapsed to `vertexCount / fps`.
             // Encoded polylines quantise near 1.1 m, so that regime was the common
             // one, not the corner case.
+            //
+            // The step's whole polyline is already uploaded (see `loadStepGeometry`),
+            // so a frame commits nothing: it only moves the reveal cut-off, which is
+            // the same distance that moves the marker.
             let segmentStart = start;
             let segmentEnd = end;
             let segmentDistance = NavFunctions.distance(segmentStart, segmentEnd);
-            // Drop the previous frame's interpolated tip before committing anything.
-            // Coordinates up to and including the current vertex are settled geometry
-            // — exactly `coordinatesIndex + 1` of them — and the tip is a single
-            // moving point after them, re-placed at the end of this frame. Appending
-            // one per frame instead grew the drawn line with elapsed frames, well
-            // past the polyline's own vertex count, and `setData` re-indexed every
-            // one of those points on the next frame.
-            const coordinates = instance.currentSourceData.geometry.coordinates;
-            coordinates.length = Math.min(coordinates.length, instance.conditions.coordinatesIndex + 1);
             while (speed * progressInSeconds > segmentDistance) {
-                coordinates.push([segmentEnd.lng, segmentEnd.lat]);
                 if (instance.conditions.coordinatesIndex + 2 >= step.coordinates.length) {
-                    this.flushCurrentSourceData(instance);
+                    // `segmentEnd` is the step's last vertex: reveal the line in full.
+                    this.applyReveal(instance, this.fractionAlongStep(instance, instance.conditions.coordinatesIndex + 1, 0));
                     onFinish === null || onFinish === void 0 ? void 0 : onFinish(timestamp);
                     return;
                 }
@@ -1164,24 +1463,27 @@ export class RouteController {
                         instance.conditions.rotatingIcon = true;
                         instance.conditions.startTime = timestamp;
                         instance.conditions.progress = 0;
-                        this.flushCurrentSourceData(instance);
+                        // The marker stops on the vertex it turns about, so the line does too.
+                        this.applyReveal(instance, this.fractionAlongStep(instance, instance.conditions.coordinatesIndex, 0));
                         instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
                         return;
                     }
                     const nextAngle = NavFunctions.bearingInDegBetween(segmentEnd, next);
                     instance.conditions.iconRotation = nextAngle;
-                    (_a = instance.routeMarker) === null || _a === void 0 ? void 0 : _a.setRotation(nextAngle);
+                    (_d = instance.routeMarker) === null || _d === void 0 ? void 0 : _d.setRotation(nextAngle);
                 }
                 segmentStart = segmentEnd;
                 segmentEnd = next;
                 segmentDistance = NavFunctions.distance(segmentStart, segmentEnd);
             }
-            const fraction = (speed * progressInSeconds) / segmentDistance;
+            const traveled = Math.min(speed * progressInSeconds, segmentDistance);
             const point = segmentDistance === 0
                 ? segmentEnd
-                : NavFunctions.intermediatePointBetween(segmentStart, segmentEnd, Math.min(fraction, 1));
-            coordinates.push([point.lng, point.lat]);
-            this.flushCurrentSourceData(instance);
+                : NavFunctions.intermediatePointBetween(segmentStart, segmentEnd, traveled / segmentDistance);
+            // The same distance drives the reveal cut-off and the marker, and the
+            // reveal is a synchronous paint update rather than a `setData` that lands
+            // several frames later, so the two cannot drift apart.
+            this.applyReveal(instance, this.fractionAlongStep(instance, instance.conditions.coordinatesIndex, traveled));
             this.setMarkerLngLat(instance, point);
             // Only when it has genuinely left the DOM. maplibre's `Marker.addTo`
             // opens with `remove()`, so re-attaching an attached marker tears down
@@ -1210,18 +1512,6 @@ export class RouteController {
             return;
         }
     }
-    /**
-     * Pushes the in-progress segment's geometry to its map source.
-     *
-     * Called once per frame rather than once per vertex crossed: `setData`
-     * rebuilds the whole geojson-vt index and reloads every in-view tile, so its
-     * cost is a large fixed one per call and is worth paying only once, with the
-     * frame's final geometry.
-     */
-    flushCurrentSourceData(instance) {
-        const source = this.map.getSource(instance.currentId);
-        source === null || source === void 0 ? void 0 : source.setData(instance.currentSourceData);
-    }
     setMarkerLngLat(instance, point) {
         var _a, _b;
         if ((_a = instance.conditions) === null || _a === void 0 ? void 0 : _a.isStepByStep) {