@mapvx/web-js 4.0.2 → 4.0.3-dev.2

package/dist/es/controllers/routeController.js

@@ -2,35 +2,15 @@ import { MarkerAttribute } from "../domain/models/marker";
 import { createRouteInstance } from "../domain/models/routeInstance";
 import { NavFunctions, compareLatLng } from "../utils/nav-functions";
 import { createPositionsForStops, createStops } from "../utils/utils";
-/**
- * Default padding values for auto-fit by place feature.
- * Used when padding is not explicitly provided in the animation configuration.
- */
 const DEFAULT_AUTO_FIT_PADDING = {
     top: 150,
     right: 150,
     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)";
 const REVEAL_EDGE = 1 / 256;
-/**
- * A `line-gradient` ramp that is `color` along the whole line.
- *
- * `line-gradient` only accepts an expression, so "no cut-off at all" still has to be spelled as a
- * ramp. Two stops at the domain ends are the cheapest way to say it and keep them ascending.
- */
 const constantRamp = (color) => [
     "interpolate",
     ["linear"],
@@ -40,37 +20,7 @@ const constantRamp = (color) => [
     1,
     color,
 ];
-/**
- * Longest gap between two frames, in milliseconds, that still counts as
- * animation time.
- *
- * The frame loop charges the marker for however much wall clock has elapsed,
- * which is what makes a step take `stepTime` at any frame rate. A gap larger
- * than any frame rate can explain is not slow rendering, though — it is time
- * the animation did not run at all. `requestAnimationFrame` does not fire in a
- * backgrounded tab, so the first frame after the page comes back carries the
- * entire absence, and charging it advanced the draw by the whole gap: one
- * frame 10 s late at 50 m/s consumed exactly a hundred vertices in a single
- * `setData`, with the camera following the line as it jumped.
- *
- * Such a gap is therefore not charged (see `animateStep`). This is deliberately
- * NOT a clamp on how far one frame may advance: clamping would cap the catch-up
- * and hand back the frame-rate independence this loop exists to provide, and it
- * would still be wrong — the marker would sprint to catch up through time
- * nobody watched. Skipping the gap instead is what a pause does, which is what
- * an absence is.
- *
- * 500 ms is two frames per second. Real rendering does not sustain anything
- * near that low, so the threshold only ever separates absence from rendering,
- * and never shortens the catch-up of a genuinely slow frame.
- */
 const MAX_FRAME_GAP_MS = 500;
-/**
- * Represents the controller for routes on the map.
- * Supports multiple simultaneous routes with independent customizations,
- * animations, and lifecycle management.
- * @group Routes
- */
 export class RouteController {
     constructor(map) {
         this.routes = new Map();
@@ -79,22 +29,10 @@ export class RouteController {
     get map() {
         return this.mapvxMap.map;
     }
-    /**
-     * Resolve a route instance by ID, or fall back to the last added route.
-     */
     resolveInstance(routeId) {
         const id = routeId !== null && routeId !== void 0 ? routeId : this.lastAddedRouteId;
         return id ? this.routes.get(id) : undefined;
     }
-    /**
-     * 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. 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, {
             type: "geojson",
@@ -139,9 +77,6 @@ export class RouteController {
             },
         });
     }
-    /**
-     * Remove MapLibre sources and layers for a single route instance.
-     */
     removeSourcesAndLayersForRoute(instance) {
         const ids = [instance.aheadId, instance.behindId, instance.currentId];
         for (const id of ids) {
@@ -149,20 +84,14 @@ export class RouteController {
                 this.map.removeLayer(id);
             }
             catch (_a) {
-                // Layer may not exist
             }
             try {
                 this.map.removeSource(id);
             }
             catch (_b) {
-                // Source may not exist
             }
         }
     }
-    /**
-     * Re-add sources and layers for all active routes.
-     * Should be called when the map style is reloaded.
-     */
     addSourcesAndLayers() {
         for (const instance of this.routes.values()) {
             this.addSourcesAndLayersForRoute(instance);
@@ -170,39 +99,15 @@ export class RouteController {
         }
         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
-     * derivation as the route line's `floor_key`), so a 3D building only fades when a route is visibly
-     * crossing it on the displayed floor. The map ignores this unless the 3D scene is active, so it is
-     * safe to call unconditionally.
-     */
     syncRouteCollision() {
         const points = [];
         for (const instance of this.routes.values()) {
@@ -215,11 +120,6 @@ export class RouteController {
         }
         this.mapvxMap.setRouteCollisionPath(points);
     }
-    /**
-     * Add a route to the map.
-     * @param route The route to add.
-     * @param drawConfig The draw configuration for the route.
-     */
     addRoute(route, drawConfig) {
         const instance = createRouteInstance(route);
         this.routes.set(instance.id, instance);
@@ -230,22 +130,12 @@ export class RouteController {
         this.updateLayerFilter(instance.aheadId);
         this.syncRouteCollision();
     }
-    /**
-     * Update the visual progress of a route based on an external user position.
-     * Splits the route into behind (already traveled) and ahead (remaining) sections
-     * at the point on the route closest to the given position.
-     *
-     * @param routeId The ID of the route to update.
-     * @param position The current user position (will be projected onto the route).
-     * @param behindDrawConfig The draw configuration for the behind (traveled) portion.
-     */
     updateRouteProgress(routeId, position, behindDrawConfig) {
         const instance = this.routes.get(routeId);
         if (!instance)
             return;
         const route = instance.route;
         const steps = route.steps;
-        // Find the closest point on the route to the position
         let bestDist = Infinity;
         let bestStepIndex = 0;
         let bestCoordIndex = 0;
@@ -264,8 +154,6 @@ export class RouteController {
                 }
             }
         }
-        // Build behind features: all complete steps before the best step,
-        // plus the partial segment of the current step up to the projected point
         const behindFeatures = [];
         for (let s = 0; s < bestStepIndex; s++) {
             behindFeatures.push({
@@ -277,14 +165,12 @@ export class RouteController {
                 },
             });
         }
-        // Partial behind feature for the current step (up to projected point)
         const currentStep = steps[bestStepIndex];
         const currentCoords = currentStep.coordinates;
         const partialBehindCoords = [];
         for (let c = 0; c <= bestCoordIndex; c++) {
             partialBehindCoords.push([currentCoords[c].lng, currentCoords[c].lat]);
         }
-        // Add the projected point
         const a = currentCoords[bestCoordIndex];
         const b = currentCoords[Math.min(bestCoordIndex + 1, currentCoords.length - 1)];
         const projLat = a.lat + bestFraction * (b.lat - a.lat);
@@ -297,7 +183,6 @@ export class RouteController {
                 geometry: { type: "LineString", coordinates: partialBehindCoords },
             });
         }
-        // Build ahead features: partial remainder of current step + all remaining steps
         const aheadFeatures = [];
         const partialAheadCoords = [[projLng, projLat]];
         for (let c = bestCoordIndex + 1; c < currentCoords.length; c++) {
@@ -320,21 +205,16 @@ export class RouteController {
                 },
             });
         }
-        // Update sources
         instance.behindSourceData.features = behindFeatures;
         const behindSource = this.map.getSource(instance.behindId);
         behindSource === null || behindSource === void 0 ? void 0 : behindSource.setData(instance.behindSourceData);
         instance.aheadSourceData.features = aheadFeatures;
         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, instance.behindId, behindDrawConfig);
         this.updateLayerFilter(instance.behindId);
         this.updateLayerFilter(instance.aheadId);
     }
-    /**
-     * Project a point onto a line segment and return the clamped fraction and squared distance.
-     */
     projectPointToSegment(p, a, b) {
         const dx = b.lng - a.lng;
         const dy = b.lat - a.lat;
@@ -364,22 +244,12 @@ export class RouteController {
             source === null || source === void 0 ? void 0 : source.setData(instance.behindSourceData);
         }
     }
-    /**
-     * 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 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];
@@ -392,10 +262,6 @@ export class RouteController {
         const source = this.map.getSource(instance.currentId);
         source === null || source === void 0 ? void 0 : source.setData(instance.currentSourceData);
     }
-    /**
-     * Fraction of the step line up to `coordinatesIndex` plus `extraMeters` along
-     * the following segment.
-     */
     fractionAlongStep(instance, coordinatesIndex, extraMeters) {
         var _a;
         const metrics = instance.stepMetrics;
@@ -404,16 +270,6 @@ export class RouteController {
         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)
@@ -421,40 +277,14 @@ export class RouteController {
         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) {
-        // The degenerate ends carry no cut-off — nothing revealed is transparent throughout, fully
-        // revealed is the line's own color throughout — but they are still emitted as constant ramps
-        // rather than as a bare color. MapLibre v6 types `line-gradient` as expression-only, and a
-        // flat two-stop `interpolate` expresses "this color everywhere" while keeping the stops
-        // strictly ascending, which is the constraint that kept these ends cut-off-free to begin with.
         if (fraction <= 0)
             return constantRamp(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 constantRamp(color);
         return [
@@ -463,37 +293,20 @@ export class RouteController {
             ["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;
@@ -502,11 +315,6 @@ export class RouteController {
             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;
@@ -519,29 +327,18 @@ export class RouteController {
     setLayerPaint(instance, layerId, drawConfig) {
         instance.layerDrawConfigs[layerId] = drawConfig;
         const paintConfig = this.preparePaintForLayer(drawConfig);
-        // v6 types the property name as `keyof AllPaintProperties` rather than `string`. The config is
-        // built here from a known set of paint keys, so the cast asserts what this code already knows.
         for (const [property, value] of Object.entries(paintConfig)) {
             this.map.setPaintProperty(layerId, property, value);
         }
     }
-    /**
-     * 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 drawConfig.routeStyle.color;
         }
-        // Is GradienteStyle
         const { colors, positions } = drawConfig.routeStyle;
         const positionsToUse = positions !== null && positions !== void 0 ? positions : createPositionsForStops(colors.length);
         if (positionsToUse.length !== colors.length) {
@@ -555,7 +352,7 @@ export class RouteController {
         if (typeof color === "string") {
             return {
                 "line-color": color,
-                "line-gradient": null, // null to unset the existing value
+                "line-gradient": null,
                 "line-width": drawConfig.polylineWidth,
             };
         }
@@ -565,44 +362,20 @@ export class RouteController {
             "line-width": drawConfig.polylineWidth,
         };
     }
-    /**
-     * Update the filter of the layer referenced with a ID.
-     *
-     * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#setfilter}
-     * @param layerId The ID for the layer.
-     */
     updateLayerFilter(layerId, floorId) {
         const newFloorId = floorId !== null && floorId !== void 0 ? floorId : this.mapvxMap.getCurrentFloor();
         if (newFloorId === undefined)
             return;
-        // `getLayer` is a map lookup; `getStyle()` serialises every source and
-        // layer in the style just to answer the same question. This runs three
-        // times per route per floor change, and each preceding `setFilter`
-        // invalidates maplibre's serialised-layer cache, so the later calls used to
-        // re-serialise from scratch.
         if (this.map.getLayer(layerId) != null) {
             this.map.setFilter(layerId, ["==", ["get", "floor_key"], newFloorId]);
         }
     }
-    /**
-     * Determines the correct floor_key for a route step.
-     * Outdoor steps (without startInsideFloor) should use the outdoor floor key,
-     * not the current floor which might be indoor.
-     * Elevator steps are always drawn on startInsideFloor; floor is updated to endInsideFloor
-     * only when the step completes (see prepareForNextStep / animateStep).
-     * @param step The route step to determine the floor_key for
-     * @returns The floor_key string to use for the step
-     */
     getFloorKeyForStep(step) {
         var _a, _b, _c, _d, _e, _f, _g;
         if (!step) {
             return this.mapvxMap.getCurrentFloor();
         }
-        // If step has startInsideFloor, use it (unless it's a non-elevator floor change step)
         if (((_b = (_a = step.startInsideFloor) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0) {
-            // If step changes floors (different start and end) and is not an elevator step,
-            // use endInsideFloor so the step is drawn on the destination floor.
-            // Elevator steps are drawn on startInsideFloor; floor updates on step completion.
             if (((_d = (_c = step.endInsideFloor) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0) > 0 &&
                 step.startInsideFloor !== step.endInsideFloor &&
                 !step.elevatorStep) {
@@ -610,11 +383,9 @@ export class RouteController {
             }
             return step.startInsideFloor;
         }
-        // If step has endInsideFloor but no startInsideFloor (entering building), use endInsideFloor
         if (((_f = (_e = step.endInsideFloor) === null || _e === void 0 ? void 0 : _e.length) !== null && _f !== void 0 ? _f : 0) > 0) {
             return step.endInsideFloor;
         }
-        // If step is outdoor (no startInsideFloor and no endInsideFloor), use outdoor floor key
         const innerFloors = this.mapvxMap.getInnerFloors();
         const outdoorFloor = innerFloors.find((floor) => floor.reachableFromGPS === true);
         return (_g = outdoorFloor === null || outdoorFloor === void 0 ? void 0 : outdoorFloor.key) !== null && _g !== void 0 ? _g : "";
@@ -632,10 +403,6 @@ export class RouteController {
         });
         return features;
     }
-    /**
-     * Update the layers for all active routes.
-     * @param floorId The floor ID to update the layers for.
-     */
     updateRouteLayers(floorId) {
         for (const instance of this.routes.values()) {
             this.updateLayerFilter(instance.aheadId, floorId);
@@ -643,11 +410,6 @@ export class RouteController {
             this.updateLayerFilter(instance.currentId, floorId);
         }
     }
-    /**
-     * Every active route's marker. Used by `MarkerLayoutController` so marker
-     * labels are never placed on top of a route's own marker.
-     * @internal
-     */
     getRouteMarkers() {
         const markers = [];
         for (const instance of this.routes.values()) {
@@ -656,17 +418,8 @@ export class RouteController {
         }
         return markers;
     }
-    /**
-     * Update the visibility of route markers for all active routes.
-     * @param floorId The floor ID to update the visibility for.
-     */
     updateRouteMarkerVisibility(floorId) {
         var _a, _b, _c, _d;
-        // An outdoor step gives its marker an empty floorId, which never equals a
-        // real floor key — so on a venue with buildings the route arrow used to be
-        // hidden the moment the map filtered by one, and only reappeared because
-        // the animation re-attached the marker on its next frame. Outdoors is an
-        // allowance markers and circles already make; the route arrow makes it too.
         const isOutdoor = this.mapvxMap.isOutdoorFloor(floorId);
         for (const instance of this.routes.values()) {
             const markerFloorId = (_b = (_a = instance.routeMarker) === null || _a === void 0 ? void 0 : _a.floorId) !== null && _b !== void 0 ? _b : "";
@@ -684,12 +437,6 @@ export class RouteController {
             this.updateRouteMarkerVisibility(floorKey);
         }
     }
-    /**
-     * Start the animation of a route.
-     * @param route The route to animate.
-     * @param drawConfig The draw configuration for the route.
-     * @param animationConfig The animation configuration for the route.
-     */
     startAnimating(route, drawConfig, animationConfig) {
         var _a, _b, _c;
         const instance = createRouteInstance(route);
@@ -715,7 +462,6 @@ export class RouteController {
             rotationAlignment: "map",
         });
         instance.routeMarker.addToMap(this.map);
-        // Auto-fit by place if enabled
         if (((_a = animationConfig.autoFitByPlace) === null || _a === void 0 ? void 0 : _a.enabled) && route.steps.length > 0) {
             if (firstStep.startInsidePlace) {
                 instance.currentPlaceId = firstStep.startInsidePlace;
@@ -725,12 +471,6 @@ export class RouteController {
                 this.mapvxMap.fitRouteByPlace(route, firstStep.startInsidePlace, fitOptions);
             }
         }
-        // The conditions go in before the consumer hears about the start, for the same reason
-        // `restartAnimation` orders it that way. `animationStatus` is already "STARTED" here, so a
-        // consumer that pauses from inside this callback — showing a modal per step, say — passed
-        // `internalPause`'s status guard and then died on its `instance.conditions == null` check:
-        // the pause was dropped in silence, the loop kept running, and because the status stayed
-        // "STARTED" the matching `resumeAnimation()` bailed out too.
         instance.conditions = {
             index: 0,
             coordinatesIndex: 0,
@@ -747,19 +487,6 @@ export class RouteController {
         (_c = animationConfig.callBack) === null || _c === void 0 ? void 0 : _c.call(animationConfig, { isFinished: false, step: firstStep });
         this.syncRouteCollision();
     }
-    /**
-     * 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) {
@@ -785,10 +512,6 @@ export class RouteController {
         instance.animationConfig = undefined;
         instance.currentPlaceId = undefined;
     }
-    /**
-     * Remove a route from the map.
-     * @param routeId The ID of the route to remove. If not provided, removes the last added route.
-     */
     removeRoute(routeId) {
         const instance = this.resolveInstance(routeId);
         if (!instance)
@@ -802,9 +525,6 @@ export class RouteController {
         }
         this.syncRouteCollision();
     }
-    /**
-     * Remove all routes from the map.
-     */
     removeAllRoutes() {
         for (const instance of this.routes.values()) {
             this.clearRouteInstance(instance, false);
@@ -814,10 +534,6 @@ export class RouteController {
         this.lastAddedRouteId = undefined;
         this.syncRouteCollision();
     }
-    /**
-     * Get the IDs of all active routes on the map.
-     * @returns Array of route IDs.
-     */
     getRouteIds() {
         return [...this.routes.keys()];
     }
@@ -829,10 +545,6 @@ export class RouteController {
         cancelAnimationFrame(instance.conditions.animationId);
         instance.animationStatus = "PAUSED";
     }
-    /**
-     * Pause the animation of a route.
-     * @param routeId The ID of the route. If not provided, pauses the last added route.
-     */
     pauseAnimation(routeId) {
         const instance = this.resolveInstance(routeId);
         if (!instance)
@@ -848,20 +560,12 @@ export class RouteController {
         instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
         instance.animationStatus = "STARTED";
     }
-    /**
-     * Resume the animation of a route.
-     * @param routeId The ID of the route. If not provided, resumes the last added route.
-     */
     resumeAnimation(routeId) {
         const instance = this.resolveInstance(routeId);
         if (!instance)
             return;
         this.internalResume(instance);
     }
-    /**
-     * Restart the animation of a route.
-     * @param routeId The ID of the route. If not provided, restarts the last added route.
-     */
     restartAnimation(routeId) {
         var _a, _b, _c, _d, _e;
         const instance = this.resolveInstance(routeId);
@@ -887,7 +591,6 @@ export class RouteController {
         this.setSourceData(instance, instance.behindId, []);
         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) {
             if (firstStep.startInsidePlace) {
                 instance.currentPlaceId = firstStep.startInsidePlace;
@@ -897,14 +600,6 @@ export class RouteController {
                 this.mapvxMap.fitRouteByPlace(instance.route, firstStep.startInsidePlace, fitOptions);
             }
         }
-        // The new conditions go in before the consumer hears about the restart.
-        // Invoking the callback first left `instance.conditions` pointing at the
-        // previous run, so a consumer that pauses from inside it — showing a modal
-        // per step, say — cancelled a frame id that had already fired, marked the
-        // instance PAUSED, and then had a live loop installed underneath it. The
-        // next resume passed the "not paused" guard and started a second loop on
-        // the same instance; each schedules its own successor, so the doubling was
-        // permanent.
         instance.conditions = {
             index: 0,
             coordinatesIndex: 0,
@@ -920,10 +615,6 @@ export class RouteController {
         };
         (_e = (_d = instance.animationConfig).callBack) === null || _e === void 0 ? void 0 : _e.call(_d, { isFinished: false, step: firstStep });
     }
-    /**
-     * Stop the animation of a route.
-     * @param routeId The ID of the route. If not provided, stops the last added route.
-     */
     stopAnimation(routeId) {
         const instance = this.resolveInstance(routeId);
         if (!instance)
@@ -931,15 +622,8 @@ export class RouteController {
         if (instance.animationStatus == "FINISHED") {
             return;
         }
-        // todo hacer cosas para detener animación
         instance.animationStatus = "FINISHED";
     }
-    /**
-     * Add a step animation to a route.
-     * @param route The route to animate.
-     * @param drawConfig The draw configuration for the route.
-     * @param animationConfig The animation configuration for the route.
-     */
     addStepAnimation(route, drawConfig, animationConfig) {
         var _a, _b, _c;
         const instance = createRouteInstance(route);
@@ -966,7 +650,6 @@ export class RouteController {
         });
         instance.routeMarker.addToMap(this.map);
         this.cameraFollow(instance, firstStep.startLocation);
-        // Auto-fit by place if enabled
         if (((_a = animationConfig.autoFitByPlace) === null || _a === void 0 ? void 0 : _a.enabled) && route.steps.length > 0) {
             if (firstStep.startInsidePlace) {
                 instance.currentPlaceId = firstStep.startInsidePlace;
@@ -976,11 +659,6 @@ export class RouteController {
                 this.mapvxMap.fitRouteByPlace(route, firstStep.startInsidePlace, fitOptions);
             }
         }
-        // The conditions go in before the consumer hears about the route, as they
-        // do in `startAnimating`. Invoking the callback first left `conditions`
-        // undefined, so a consumer advancing the route from it — the step-by-step
-        // integration draws its first step this way — hit `nextStepAnimation`'s
-        // null check and got an exception instead of a step.
         instance.conditions = {
             index: 0,
             coordinatesIndex: 0,
@@ -1008,16 +686,9 @@ export class RouteController {
                 this.setSourceData(instance, instance.aheadId, aheadSteps);
                 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
-                // already true here. Writing it afterwards overwrote the "ANIMATING" of a
-                // consumer that chained the next step from this callback, and the
-                // following `nextStepAnimation` then skipped its cancel and installed a
-                // second self-sustaining loop on the same instance.
                 instance.stepAnimationStatus = "WAITING";
                 if (index < route.steps.length) {
                     const nextStep = route.steps[index];
-                    // Auto-fit by place if enabled and place changed
                     if (((_a = animationConfig.autoFitByPlace) === null || _a === void 0 ? void 0 : _a.enabled) && nextStep && instance.route != null) {
                         const stepPlaceId = nextStep.startInsidePlace || nextStep.endInsidePlace;
                         if (stepPlaceId && stepPlaceId !== instance.currentPlaceId) {
@@ -1038,10 +709,6 @@ export class RouteController {
         (_c = animationConfig.callBack) === null || _c === void 0 ? void 0 : _c.call(animationConfig, { isFinished: false, step: firstStep });
         this.syncRouteCollision();
     }
-    /**
-     * Animate the next step of a route.
-     * @param routeId The ID of the route. If not provided, uses the last added route.
-     */
     nextStepAnimation(routeId) {
         const instance = this.resolveInstance(routeId);
         if (!instance) {
@@ -1070,10 +737,6 @@ export class RouteController {
             throw new Error("Error: Does not exist next step to animate");
         }
     }
-    /**
-     * Go to the previous step of a route.
-     * @param routeId The ID of the route. If not provided, uses the last added route.
-     */
     previousStepAnimation(routeId) {
         var _a, _b, _c, _d;
         const instance = this.resolveInstance(routeId);
@@ -1118,7 +781,6 @@ export class RouteController {
             else {
                 this.setMarkerRotation(instance, 0);
             }
-            // Auto-fit by place if enabled and place changed
             if (((_a = instance.animationConfig.autoFitByPlace) === null || _a === void 0 ? void 0 : _a.enabled) && step && instance.route != null) {
                 const stepPlaceId = step.startInsidePlace || step.endInsidePlace;
                 if (stepPlaceId && stepPlaceId !== instance.currentPlaceId) {
@@ -1138,10 +800,6 @@ export class RouteController {
             throw new Error("previous step doesn't exists to animate");
         }
     }
-    /**
-     * Center on the current step of a route.
-     * @param routeId The ID of the route. If not provided, uses the last added route.
-     */
     centerOnCurrentStep(routeId) {
         var _a;
         const instance = this.resolveInstance(routeId);
@@ -1180,23 +838,9 @@ export class RouteController {
             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 &&
@@ -1210,7 +854,6 @@ export class RouteController {
             if (!compareLatLng(instance.route.steps[index].endLocation, step.startLocation))
                 instance.conditions.nextFloorFirstStepIndex = index + 2;
             instance.conditions.animationId = requestAnimationFrame((time) => this.animateStep(time, instance));
-            // Auto-fit by place if enabled and place changed
             if (((_a = instance.animationConfig.autoFitByPlace) === null || _a === void 0 ? void 0 : _a.enabled) && step && instance.route != null) {
                 const stepPlaceId = step.startInsidePlace || step.endInsidePlace;
                 if (stepPlaceId && stepPlaceId !== instance.currentPlaceId) {
@@ -1222,9 +865,6 @@ export class RouteController {
                 }
             }
             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 {
@@ -1232,25 +872,9 @@ export class RouteController {
             }
         }
         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
-            // kiosk demo is the ordinary case — got its fresh "STARTED" overwritten
-            // by the "FINISHED" written afterwards, and was left with a live loop the
-            // controller believed was over: `pauseAnimation` and `stopAnimation` both
-            // bailed on the status guard, and the next `restartAnimation` skipped its
-            // cancel and installed a second self-sustaining loop.
             instance.animationStatus = "FINISHED";
             (_f = (_e = instance.animationConfig).callBack) === null || _f === void 0 ? void 0 : _f.call(_e, { isFinished: true, step: null });
         }
@@ -1263,9 +887,6 @@ export class RouteController {
         let { startTime, resetTime, progress, waitStartTime } = instance.conditions;
         const { coordinatesIndex, iconRotation, index, onFinish, rotatingIcon } = instance.conditions;
         const { stepTime, minimumSpeed, iconRotationTime, changeFloorTime } = instance.animationConfig;
-        // How long this frame took to arrive. Recorded before any early return, so
-        // the next frame measures from the last one delivered rather than from the
-        // last one that drew.
         const previousFrameTime = instance.conditions.lastFrameTime;
         instance.conditions.lastFrameTime = timestamp;
         if (startTime == null) {
@@ -1275,18 +896,11 @@ export class RouteController {
         }
         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;
@@ -1296,23 +910,8 @@ export class RouteController {
             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) {
@@ -1327,23 +926,11 @@ export class RouteController {
             instance.conditions.resetTime = resetTime;
         }
         else if (previousFrameTime != null && timestamp - previousFrameTime > MAX_FRAME_GAP_MS) {
-            // Absence, not slow rendering: see MAX_FRAME_GAP_MS. Shift the clock
-            // forward by the gap instead of charging it, exactly as resuming from a
-            // pause does above, so this frame redraws where the last one left off
-            // and the next resumes from there.
             const gap = timestamp - previousFrameTime;
-            // What the previous frame had charged. Equal to `progress` whenever the
-            // two are in step, but the rotation branches above set `startTime` to
-            // the frame timestamp without resetting `progress`, so reading the
-            // stored value would carry a whole rotation's worth of time into the
-            // first frame back. Recomputed instead, which is 0 in exactly that case.
             progress = previousFrameTime - startTime;
             instance.conditions.progress = progress;
             startTime = timestamp - progress;
             instance.conditions.startTime = startTime;
-            // The floor-change wait runs on the raw timestamp rather than on
-            // `progress`, so it needs the same shift or an absence would satisfy it
-            // outright.
             if (waitStartTime != null) {
                 waitStartTime += gap;
                 instance.conditions.waitStartTime = waitStartTime;
@@ -1353,8 +940,6 @@ export class RouteController {
             progress = timestamp - startTime;
             instance.conditions.progress = progress;
         }
-        // Not const: the segment loop below rewinds it as it charges the clock for
-        // each segment it consumes within the frame.
         let progressInSeconds = progress / 1000;
         const step = instance.route.steps[index];
         if (step.coordinates.length <= 0) {
@@ -1392,14 +977,6 @@ export class RouteController {
                     return;
                 }
             }
-            // 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;
@@ -1413,13 +990,10 @@ export class RouteController {
                 else {
                     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,
@@ -1431,32 +1005,15 @@ export class RouteController {
                 }
             }
             const speed = Math.max(step.distance / stepTime, minimumSpeed !== null && minimumSpeed !== void 0 ? minimumSpeed : 0);
-            // Consume every whole segment the elapsed time pays for inside this one
-            // frame, carrying the sub-segment remainder into the next.
-            //
-            // Advancing a single vertex per frame — and restarting the clock at each
-            // one, which threw the overshoot away — made a step's duration depend on
-            // the frame rate: it cost `stepTime` plus up to one frame per vertex,
-            // and once `speed * frameInterval` exceeded a segment's length it
-            // 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);
             while (speed * progressInSeconds > segmentDistance) {
                 if (instance.conditions.coordinatesIndex + 2 >= step.coordinates.length) {
-                    // `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;
                 }
-                // Charge the clock exactly what this segment cost instead of
-                // restarting it, so no time is lost at a vertex.
                 const segmentMs = (segmentDistance / speed) * 1000;
                 startTime += segmentMs;
                 progress -= segmentMs;
@@ -1467,20 +1024,9 @@ export class RouteController {
                 const next = step.coordinates[instance.conditions.coordinatesIndex + 1];
                 if (!compareLatLng(segmentEnd, next)) {
                     if (instance.conditions.isStepByStep) {
-                        // Step-by-step mode animates the turn itself, on the rotation
-                        // branch of the next frame. Stop consuming segments and let it.
-                        //
-                        // The clock restarts here because the rotation branch measures its
-                        // own progress from `startTime`, and every other transition into it
-                        // resets too (see `prepareForNextStep` and the floor-change hand-off).
-                        // Carrying this frame's leftover sub-segment time over instead
-                        // started the turn already part-way through — or skipped it outright
-                        // once the remainder exceeded `iconRotationTime`. Before the segment
-                        // loop existed the per-vertex path reset it as well.
                         instance.conditions.rotatingIcon = true;
                         instance.conditions.startTime = timestamp;
                         instance.conditions.progress = 0;
-                        // 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;
@@ -1497,25 +1043,8 @@ export class RouteController {
             const point = segmentDistance === 0
                 ? segmentEnd
                 : 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
-            // and rebuilds 13 map listeners and detaches and re-appends the element.
-            // Unconditionally, that ran every frame — and quietly undid
-            // `updateRouteMarkerVisibility` hiding the arrow, which is the bug it was
-            // really covering for.
-            //
-            // `isConnected` alone cannot express that: `hide()` detaches the element
-            // through maplibre's `Marker.remove()`, so a marker hidden by a floor
-            // change reads as disconnected and was re-attached on the very next
-            // frame — the arrow reappeared on the wrong floor. Hidden-ness is an
-            // intent, so it is read from the flag `hide()`/`show()` maintain, and
-            // `isConnected` is left to answer only what it can: whether a marker
-            // nobody hid has fallen out of the DOM (a step transition removing it).
             if (instance.routeMarker != null &&
                 !instance.routeMarker.hiddenOnPurpose &&
                 !instance.routeMarker.getElement().isConnected) {
@@ -1559,4 +1088,3 @@ export class RouteController {
         this.mapvxMap.updateCamera(Object.assign({ center: point, animate: true, duration: (_c = instance.animationConfig) === null || _c === void 0 ? void 0 : _c.iconRotationTime }, (keepFixedBearing ? {} : { bearing: (_d = instance.routeMarker) === null || _d === void 0 ? void 0 : _d.getRotation() })));
     }
 }
-//# sourceMappingURL=routeController.js.map