@mapmap/maps 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -518,6 +518,26 @@ interface NavRouteDesign {
     opacity: number;
     /** Casing (outline) colour drawn under the line. */
     casingColor: string;
+    /**
+     * Casing width in px. Defaults to `width + 4`.
+     *
+     * Optional because the casing was previously always `width + 4`, which
+     * cannot express a design whose casing is not exactly four wider than
+     * its line (the playground's is 9 over a 4.5 line).
+     */
+    casingWidth?: number;
+    /**
+     * Casing opacity, 0-1. Defaults to {@link NavRouteDesign.opacity}.
+     *
+     * Optional because casing and line previously shared one opacity, which
+     * cannot express a translucent casing under a solid line.
+     */
+    casingOpacity?: number;
+    /**
+     * Line dash pattern, in line-widths, as MapLibre's `line-dasharray`.
+     * Omitted or `null` draws a solid line.
+     */
+    dash?: number[] | null;
 }
 /** Current-position puck tokens. */
 interface NavPuckDesign {
@@ -1165,6 +1185,18 @@ declare function createMap(options: MapMapOptions): MapMapMap;
 
 /** MapMap brand signal blue (see website `--signal`). */
 declare const SIGNAL_BLUE = "#3a86ff";
+/**
+ * Runtime overrides for the drawn line, applied over the design or the
+ * built-in look. Every field is optional; omitted ones are left alone.
+ */
+interface RouteLineStyle {
+    /** Line colour. */
+    color?: string;
+    /** Dash pattern in line-widths, or `null` for solid. */
+    dash?: number[] | null;
+    /** Casing opacity, 0-1. Set 0 to hide the casing entirely. */
+    casingOpacity?: number;
+}
 interface RouteLayerOptions {
     /** Gateway base URL. Defaults to the map's `baseUrl` when given a map. */
     baseUrl?: string;
@@ -1191,6 +1223,12 @@ interface RouteLayerOptions {
      * route line"). Defaults to a dimmed grey.
      */
     progressColor?: string;
+    /** Casing colour for unselected alternative routes. */
+    alternativeCasingColor?: string;
+    /** Line colour for unselected alternative routes. */
+    alternativeColor?: string;
+    /** Colour of the ferry dashes drawn over the selected route. */
+    ferryColor?: string;
 }
 /** Draws MapMap routes on a MapLibre map. */
 declare class RouteLayer {
@@ -1211,7 +1249,22 @@ declare class RouteLayer {
     private readonly design;
     private alertsDesign;
     private readonly progressColor;
+    private readonly altSourceId;
+    private readonly altCasingLayerId;
+    private readonly altLineLayerId;
+    private readonly ferrySourceId;
+    private readonly ferryLayerId;
+    private readonly altCasingColor;
+    private readonly altColor;
+    private readonly ferryColor;
     private lastRoute;
+    /** Unselected alternatives, drawn beneath the selected route. */
+    private alternatives;
+    /** Ferry legs of the selected route, drawn as dashes over its line. */
+    private ferrySegments;
+    private selectHandler;
+    /** Runtime paint override, re-applied after every style reload. */
+    private lineStyle;
     private progress;
     private maneuver;
     private corridors;
@@ -1235,6 +1288,71 @@ declare class RouteLayer {
     draw(route: ParsedRoute): void;
     /** Add-or-update the source and layers for a route on the current style. */
     private install;
+    /**
+     * Draw a bare line from coordinates, without a parsed OSRM route.
+     *
+     * {@link RouteLayer.draw} expects a {@link ParsedRoute} because it is
+     * normally fed by {@link RouteLayer.route}. Callers that already have
+     * geometry and nothing else — an agent tool result, a stored polyline,
+     * a hand-built preview — had to invent a `ParsedRoute` with zeroed
+     * distance and duration that `draw` never reads. This is that path,
+     * named honestly.
+     */
+    drawGeometry(coordinates: [number, number][]): void;
+    /**
+     * Draw a set of routes: one selected, the rest as dimmer alternatives
+     * beneath it. Offering alternatives is table stakes for a navigation UI,
+     * and the selected route keeps every feature of {@link RouteLayer.draw}
+     * (progress, manoeuvre arrow, corridors, route effects).
+     *
+     * Pass the index of the route to select; out-of-range values clamp to the
+     * first route. Calling with a single route is equivalent to `draw`, and
+     * calling with an empty array clears everything.
+     */
+    drawAlternatives(routes: ParsedRoute[], selectedIndex?: number): void;
+    /** Which alternatives are currently drawn, in the order given. */
+    get alternativeRoutes(): readonly ParsedRoute[];
+    /**
+     * Register a click handler for the alternative lines. The index is the
+     * position within the array last passed to
+     * {@link RouteLayer.drawAlternatives}, so a caller can re-issue that call
+     * with the new selection. Passing `undefined` removes the handler.
+     */
+    onSelectAlternative(handler: ((index: number) => void) | undefined): void;
+    /**
+     * Draw ferry legs of the selected route as dashes over its line, so water
+     * crossings do not read as driving.
+     *
+     * Supplied as explicit geometries rather than derived from the route,
+     * because `line-dasharray` cannot be data-driven: a ferry leg needs its
+     * own layer, and only the caller knows which parts of their route are
+     * ferries.
+     */
+    setFerrySegments(segments: [number, number][][]): void;
+    /** Remove the ferry dashes. */
+    clearFerrySegments(): void;
+    /** Add-or-update the alternative-route source and its two layers. */
+    private installAlternatives;
+    private readonly handleAlternativeClick;
+    /** Original array position of each drawn alternative, by its own index. */
+    private altOriginalIndices;
+    private removeAlternativeLayers;
+    /** Add-or-update the ferry-dash overlay above the selected route. */
+    private installFerry;
+    /**
+     * Override the drawn line's paint at runtime, over whatever the design or
+     * the built-in look set.
+     *
+     * Route styling is not always static: a route can be provisional, or a
+     * straight-line approximation that must not be mistaken for a surveyed
+     * one. That is a paint change on a route already drawn, so it belongs
+     * here rather than in the constructor's design.
+     *
+     * Overrides survive style reloads. Pass `{}` to clear them.
+     */
+    setLineStyle(style: RouteLineStyle): void;
+    /** Apply any runtime override; a no-op when the layers are absent. */
+    private applyLineStyle;
     /**
      * Sets how much of the route has been travelled, as a fraction in `[0, 1]`
      * of the line's length. The travelled part dims to `progressColor` (the
@@ -2783,4 +2901,4 @@ declare class VoiceGuidance {
     private playEarcon;
 }
 
-export { ALERT_CONTRAST_MIN, AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type AlertChipContent, type AlertContrastIssue, type AlertPresentation, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraAlert, CameraAlertChip, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, type MapDisplayMode, MapMapMap, type MapMapOptions, type MapMapTheme, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, type NavAlertAudioMode, type NavAlertChipPosition, type NavAlertIconSet, type NavAlertKindDesign, type NavAlertLeadDistance, type NavAlertMode, type NavAlertSound, type NavAlertsDesign, type NavBannerDesign, type NavCameraDesign, type NavCameraKind, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerOptions, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isNameTextField, languageTextField, lngLatToMercator, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, uploadProbeBatch };
+export { ALERT_CONTRAST_MIN, AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type AlertChipContent, type AlertContrastIssue, type AlertPresentation, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraAlert, CameraAlertChip, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, type MapDisplayMode, MapMapMap, type MapMapOptions, type MapMapTheme, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, type NavAlertAudioMode, type NavAlertChipPosition, type NavAlertIconSet, type NavAlertKindDesign, type NavAlertLeadDistance, type NavAlertMode, type NavAlertSound, type NavAlertsDesign, type NavBannerDesign, type NavCameraDesign, type NavCameraKind, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerOptions, type RouteLineStyle, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isNameTextField, languageTextField, lngLatToMercator, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, uploadProbeBatch };

package/dist/index.js

@@ -2159,6 +2159,9 @@ var CASING_COLOR = "#1f438a";
 var CORRIDOR_COLOR = "#e05c6c";
 var CORRIDOR_OPACITY = 0.55;
 var PROGRESS_COLOR = "#b0b0b0";
+var ALT_CASING_COLOR = "#5a6b84";
+var ALT_LINE_COLOR = "#aebdd2";
+var FERRY_COLOR = "#eaf1fb";
 function arrowImage() {
   const size = 24;
   const data = new Uint8Array(size * size * 4);
@@ -2186,13 +2189,29 @@ function arrowImage() {
 }
 var RouteLayer = class {
   constructor(map, options = {}) {
+    /** Unselected alternatives, drawn beneath the selected route. */
+    this.alternatives = [];
+    /** Ferry legs of the selected route, drawn as dashes over its line. */
+    this.ferrySegments = [];
     this.progress = 0;
     this.corridors = [];
     this.handleStyleLoad = () => {
+      this.installAlternatives();
       if (this.lastRoute) this.install(this.lastRoute);
       else this.installManeuver();
       this.installCorridors();
+      this.installFerry();
     };
+    this.handleAlternativeClick = (event) => {
+      if (!this.selectHandler) return;
+      const raw = event.features?.[0]?.properties?.["index"];
+      const position = typeof raw === "number" ? raw : Number(raw);
+      if (!Number.isInteger(position)) return;
+      const original = this.altOriginalIndices[position];
+      if (original !== void 0) this.selectHandler(original);
+    };
+    /** Original array position of each drawn alternative, by its own index. */
+    this.altOriginalIndices = [];
     if (map instanceof MapMapMap) {
       this.map = map.map;
       this.owner = map;
@@ -2219,7 +2238,15 @@ var RouteLayer = class {
     this.arrowImageId = `${id}-arrow`;
     this.corridorSourceId = `${id}-corridor-src`;
     this.corridorLayerId = `${id}-corridor`;
+    this.altSourceId = `${id}-alt-src`;
+    this.altCasingLayerId = `${id}-alt-casing`;
+    this.altLineLayerId = `${id}-alt-line`;
+    this.ferrySourceId = `${id}-ferry-src`;
+    this.ferryLayerId = `${id}-ferry`;
     this.progressColor = options.progressColor ?? PROGRESS_COLOR;
+    this.altCasingColor = options.alternativeCasingColor ?? ALT_CASING_COLOR;
+    this.altColor = options.alternativeColor ?? ALT_LINE_COLOR;
+    this.ferryColor = options.ferryColor ?? FERRY_COLOR;
     this.map.on("style.load", this.handleStyleLoad);
   }
   /**
@@ -2285,6 +2312,7 @@ var RouteLayer = class {
     }
     if (this.map.getLayer(this.casingLayerId) && this.map.getLayer(this.lineLayerId)) {
       this.applyProgress();
+      this.applyLineStyle();
       this.installManeuver();
       return;
     }
@@ -2295,8 +2323,8 @@ var RouteLayer = class {
       layout: { "line-cap": "round", "line-join": "round" },
       paint: this.design ? {
         "line-color": this.design.casingColor,
-        "line-width": this.design.width + 4,
-        "line-opacity": this.design.opacity
+        "line-width": this.design.casingWidth ?? this.design.width + 4,
+        "line-opacity": this.design.casingOpacity ?? this.design.opacity
       } : {
         "line-color": CASING_COLOR,
         "line-width": ["interpolate", ["linear"], ["zoom"], 8, 6, 16, 12]
@@ -2310,7 +2338,8 @@ var RouteLayer = class {
       paint: this.design ? {
         "line-color": this.design.color,
         "line-width": this.design.width,
-        "line-opacity": this.design.opacity
+        "line-opacity": this.design.opacity,
+        ...this.design.dash ? { "line-dasharray": this.design.dash } : {}
       } : {
         "line-color": SIGNAL_BLUE,
         "line-width": ["interpolate", ["linear"], ["zoom"], 8, 3, 16, 8]
@@ -2319,8 +2348,202 @@ var RouteLayer = class {
     if (!this.map.getLayer(this.casingLayerId)) this.map.addLayer(casing);
     if (!this.map.getLayer(this.lineLayerId)) this.map.addLayer(line);
     this.applyProgress();
+    this.applyLineStyle();
     this.installManeuver();
   }
+  /**
+   * Draw a bare line from coordinates, without a parsed OSRM route.
+   *
+   * {@link RouteLayer.draw} expects a {@link ParsedRoute} because it is
+   * normally fed by {@link RouteLayer.route}. Callers that already have
+   * geometry and nothing else — an agent tool result, a stored polyline,
+   * a hand-built preview — had to invent a `ParsedRoute` with zeroed
+   * distance and duration that `draw` never reads. This is that path,
+   * named honestly.
+   */
+  drawGeometry(coordinates) {
+    this.draw({
+      distanceM: 0,
+      durationS: 0,
+      geometry: { type: "LineString", coordinates },
+      raw: {}
+    });
+  }
+  /**
+   * Draw a set of routes: one selected, the rest as dimmer alternatives
+   * beneath it. Offering alternatives is table stakes for a navigation UI,
+   * and the selected route keeps every feature of {@link RouteLayer.draw}
+   * (progress, manoeuvre arrow, corridors, route effects).
+   *
+   * Pass the index of the route to select; out-of-range values clamp to the
+   * first route. Calling with a single route is equivalent to `draw`, and
+   * calling with an empty array clears everything.
+   */
+  drawAlternatives(routes, selectedIndex = 0) {
+    if (routes.length === 0) {
+      this.clear();
+      return;
+    }
+    const index = selectedIndex >= 0 && selectedIndex < routes.length ? selectedIndex : 0;
+    this.alternatives = routes.filter((_, i) => i !== index);
+    this.altOriginalIndices = routes.map((_, i) => i).filter((i) => i !== index);
+    this.installAlternatives();
+    this.draw(routes[index]);
+  }
+  /** Which alternatives are currently drawn, in the order given. */
+  get alternativeRoutes() {
+    return this.alternatives;
+  }
+  /**
+   * Register a click handler for the alternative lines. The index is the
+   * position within the array last passed to
+   * {@link RouteLayer.drawAlternatives}, so a caller can re-issue that call
+   * with the new selection. Passing `undefined` removes the handler.
+   */
+  onSelectAlternative(handler) {
+    this.selectHandler = handler;
+  }
+  /**
+   * Draw ferry legs of the selected route as dashes over its line, so water
+   * crossings do not read as driving.
+   *
+   * Supplied as explicit geometries rather than derived from the route,
+   * because `line-dasharray` cannot be data-driven: a ferry leg needs its
+   * own layer, and only the caller knows which parts of their route are
+   * ferries.
+   */
+  setFerrySegments(segments) {
+    this.ferrySegments = segments;
+    if (this.map.isStyleLoaded()) this.installFerry();
+  }
+  /** Remove the ferry dashes. */
+  clearFerrySegments() {
+    this.ferrySegments = [];
+    if (this.map.getLayer(this.ferryLayerId)) this.map.removeLayer(this.ferryLayerId);
+    if (this.map.getSource(this.ferrySourceId)) this.map.removeSource(this.ferrySourceId);
+  }
+  /** Add-or-update the alternative-route source and its two layers. */
+  installAlternatives() {
+    if (this.alternatives.length === 0) {
+      this.removeAlternativeLayers();
+      return;
+    }
+    if (!this.map.isStyleLoaded()) return;
+    const data = {
+      type: "FeatureCollection",
+      features: this.alternatives.map((route, i) => ({
+        type: "Feature",
+        properties: { index: i },
+        geometry: route.geometry
+      }))
+    };
+    const existing = this.map.getSource(this.altSourceId);
+    if (existing) existing.setData(data);
+    else this.map.addSource(this.altSourceId, { type: "geojson", data });
+    const below = this.map.getLayer(this.casingLayerId) ? this.casingLayerId : void 0;
+    if (!this.map.getLayer(this.altCasingLayerId)) {
+      this.map.addLayer({
+        id: this.altCasingLayerId,
+        type: "line",
+        source: this.altSourceId,
+        layout: { "line-cap": "round", "line-join": "round" },
+        paint: {
+          "line-color": this.altCasingColor,
+          "line-width": 7,
+          "line-opacity": 0.55
+        }
+      }, below);
+    }
+    if (!this.map.getLayer(this.altLineLayerId)) {
+      this.map.addLayer({
+        id: this.altLineLayerId,
+        type: "line",
+        source: this.altSourceId,
+        layout: { "line-cap": "round", "line-join": "round" },
+        paint: {
+          "line-color": this.altColor,
+          "line-width": 4,
+          "line-opacity": 0.9
+        }
+      }, below);
+      this.map.on("click", this.altLineLayerId, this.handleAlternativeClick);
+    }
+  }
+  removeAlternativeLayers() {
+    if (this.map.getLayer(this.altLineLayerId)) {
+      this.map.off("click", this.altLineLayerId, this.handleAlternativeClick);
+      this.map.removeLayer(this.altLineLayerId);
+    }
+    if (this.map.getLayer(this.altCasingLayerId)) this.map.removeLayer(this.altCasingLayerId);
+    if (this.map.getSource(this.altSourceId)) this.map.removeSource(this.altSourceId);
+  }
+  /** Add-or-update the ferry-dash overlay above the selected route. */
+  installFerry() {
+    if (this.ferrySegments.length === 0) {
+      this.clearFerrySegments();
+      return;
+    }
+    if (!this.map.isStyleLoaded()) return;
+    const data = {
+      type: "FeatureCollection",
+      features: this.ferrySegments.map((coordinates) => ({
+        type: "Feature",
+        properties: {},
+        geometry: { type: "LineString", coordinates }
+      }))
+    };
+    const existing = this.map.getSource(this.ferrySourceId);
+    if (existing) existing.setData(data);
+    else this.map.addSource(this.ferrySourceId, { type: "geojson", data });
+    if (!this.map.getLayer(this.ferryLayerId)) {
+      this.map.addLayer({
+        id: this.ferryLayerId,
+        type: "line",
+        source: this.ferrySourceId,
+        layout: { "line-cap": "butt", "line-join": "round" },
+        paint: {
+          "line-color": this.ferryColor,
+          "line-width": 2.5,
+          "line-dasharray": [1.2, 1.6]
+        }
+      });
+    }
+  }
+  /**
+   * Override the drawn line's paint at runtime, over whatever the design or
+   * the built-in look set.
+   *
+   * Route styling is not always static: a route can be provisional, or a
+   * straight-line approximation that must not be mistaken for a surveyed
+   * one. That is a paint change on a route already drawn, so it belongs
+   * here rather than in the constructor's design.
+   *
+   * Overrides survive style reloads. Pass `{}` to clear them.
+   */
+  setLineStyle(style) {
+    this.lineStyle = Object.keys(style).length > 0 ? style : void 0;
+    this.applyLineStyle();
+  }
+  /** Apply any runtime override; a no-op when the layers are absent. */
+  applyLineStyle() {
+    const style = this.lineStyle;
+    if (!style) return;
+    if (this.map.getLayer(this.lineLayerId)) {
+      if (style.color !== void 0) {
+        this.map.setPaintProperty(this.lineLayerId, "line-color", style.color);
+      }
+      if (style.dash !== void 0) {
+        this.map.setPaintProperty(
+          this.lineLayerId,
+          "line-dasharray",
+          style.dash ?? [1, 0]
+        );
+      }
+    }
+    if (style.casingOpacity !== void 0 && this.map.getLayer(this.casingLayerId)) {
+      this.map.setPaintProperty(this.casingLayerId, "line-opacity", style.casingOpacity);
+    }
+  }
   /**
    * Sets how much of the route has been travelled, as a fraction in `[0, 1]`
    * of the line's length. The travelled part dims to `progressColor` (the
@@ -2461,6 +2684,10 @@ var RouteLayer = class {
   clear() {
     this.clearManeuver();
     this.clearAlertCorridors();
+    this.clearFerrySegments();
+    this.alternatives = [];
+    this.altOriginalIndices = [];
+    this.removeAlternativeLayers();
     for (const layerId of [this.lineLayerId, this.casingLayerId]) {
       if (this.map.getLayer(layerId)) this.map.removeLayer(layerId);
     }
@@ -3936,6 +4163,16 @@ var AdrCheck = class {
 };
 
 // src/guidance.ts
+var CSS_COLOUR = /^(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix|var)\((?:[\w\s.,%/#-]|\([\w\s.,%/#-]*\))*\)$/i;
+function safeColour(value, fallback) {
+  const v = value.trim();
+  if (v === "" || /[;{}]|url\(|\/\*/i.test(v)) return fallback;
+  if (v.startsWith("#")) {
+    return /^[0-9a-fA-F]+$/.test(v.slice(1)) && [3, 4, 6, 8].includes(v.length - 1) ? v : fallback;
+  }
+  if (/^[a-zA-Z][a-zA-Z-]*$/.test(v)) return v;
+  return CSS_COLOUR.test(v) ? v : fallback;
+}
 function extractGuidance(route) {
   const legs = route.raw["legs"] ?? [];
   const out = [];
@@ -3986,10 +4223,11 @@ var XML_ENTITIES = {
   "&apos;": "'"
 };
 function ssmlToText(ssml) {
-  return ssml.replace(/<[^>]+>/g, "").replace(
-    /&(?:amp|lt|gt|quot|apos);|&#(\d+);/g,
-    (entity, decimal) => decimal !== void 0 ? String.fromCodePoint(Number(decimal)) : XML_ENTITIES[entity] ?? entity
-  ).trim();
+  return ssml.replace(/<[^>]+>/g, "").replace(/&(?:amp|lt|gt|quot|apos);|&#(\d+);/g, (entity, decimal) => {
+    if (decimal === void 0) return XML_ENTITIES[entity] ?? entity;
+    const n = Number(decimal);
+    return n <= 1114111 ? String.fromCodePoint(n) : entity;
+  }).trim();
 }
 function bannerLanes(banner) {
   const components = banner.sub?.components ?? [];
@@ -4045,7 +4283,7 @@ var GuidanceBanner = class {
     this.design = design;
     this.element = doc.createElement("div");
     this.element.className = "mapmap-banner";
-    this.element.style.cssText = design ? `display:none;align-items:center;box-sizing:border-box;gap:${Math.round((design.padding ?? 10) * 1.2)}px;padding:${design.padding ?? 10}px ${Math.round((design.padding ?? 10) * 1.4)}px;background:${design.background};color:${design.textColor};border-radius:${design.cornerRadius ?? 10}px;max-width:${design.maxWidth ?? 340}px;` + (design.height !== void 0 ? `min-height:${design.height}px;` : "") + `font:600 ${design.fontSize}px/1.3 system-ui,sans-serif` : "display:none;gap:12px;align-items:center;padding:10px 14px;background:#101418;color:#fff;border-radius:10px;font:600 16px/1.3 system-ui,sans-serif";
+    this.element.style.cssText = design ? `display:none;align-items:center;box-sizing:border-box;gap:${Math.round((design.padding ?? 10) * 1.2)}px;padding:${design.padding ?? 10}px ${Math.round((design.padding ?? 10) * 1.4)}px;background:${safeColour(design.background, "#101418")};color:${safeColour(design.textColor, "#ffffff")};border-radius:${design.cornerRadius ?? 10}px;max-width:${design.maxWidth ?? 340}px;` + (design.height !== void 0 ? `min-height:${design.height}px;` : "") + `font:600 ${design.fontSize}px/1.3 system-ui,sans-serif` : "display:none;gap:12px;align-items:center;padding:10px 14px;background:#101418;color:#fff;border-radius:10px;font:600 16px/1.3 system-ui,sans-serif";
     container?.appendChild(this.element);
   }
   /**
@@ -4304,9 +4542,9 @@ var CameraAlertChip = class {
       this.element.style.cssText = `display:${shown};gap:8px;align-items:center;padding:8px 12px;background:${this.escalated ? "#c0392b" : "#101418"};color:#fff;border-radius:10px;font:600 15px/1.3 system-ui,sans-serif`;
       return;
     }
-    const background = this.escalated ? design.escalatedBackground : design.background;
-    const color = this.escalated ? design.escalatedTextColor : design.textColor;
-    this.element.style.cssText = `display:${shown};gap:8px;align-items:center;box-sizing:border-box;padding:8px 12px;background:${background};color:${color};border-radius:${design.cornerRadius}px;` + (design.outlineWidth > 0 ? `border:${design.outlineWidth}px solid ${design.outlineColor};` : "") + (CHIP_SLOT_CSS[design.chipPosition] ?? "") + "font:600 15px/1.3 system-ui,sans-serif";
+    const background = this.escalated ? safeColour(design.escalatedBackground, "#c0392b") : safeColour(design.background, "#101418");
+    const color = this.escalated ? safeColour(design.escalatedTextColor, "#ffffff") : safeColour(design.textColor, "#ffffff");
+    this.element.style.cssText = `display:${shown};gap:8px;align-items:center;box-sizing:border-box;padding:8px 12px;background:${background};color:${color};border-radius:${design.cornerRadius}px;` + (design.outlineWidth > 0 ? `border:${design.outlineWidth}px solid ${safeColour(design.outlineColor, "#ffffff")};` : "") + (CHIP_SLOT_CSS[design.chipPosition] ?? "") + "font:600 15px/1.3 system-ui,sans-serif";
   }
 };