@superrouteca/smap 1.0.1 → 1.0.5

package/dist/smap.js

@@ -1,6 +1,7 @@
-/*! sMap Web SDK 1.0.1. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
+/*! sMap Web SDK 1.0.5. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
 (function () {
 function smapCreateEngine() {
+  var SMAP_BASE_URL = (typeof document !== 'undefined' && document.baseURI) || (typeof location !== 'undefined' && location.href) || 'about:blank';
 var smapEngineExports = (() => {
   var __defProp = Object.defineProperty;
   var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -4596,7 +4597,7 @@ Use an identity property function instead: \`{ "type": "identity", "property": $
     }
   }
   function el() {
-    let e66 = "";
+    let e66 = SMAP_BASE_URL;
     if (!/^https?:/.test(e66)) return ``;
     let t2 = e66.endsWith(`-dev.mjs`) ? `maplibre-gl-worker-dev.mjs` : `maplibre-gl-worker.mjs`, n2 = new URL(`./${t2}`, e66);
     return n2.searchParams.set(`v`, l), n2.href;
@@ -4619,7 +4620,7 @@ Use an identity property function instead: \`{ "type": "identity", "property": $
     return URL.createObjectURL(r2);
   }
   function il(e66) {
-    let t2 = new Blob([`import ${JSON.stringify(new URL(e66, "").href)}`], { type: `text/javascript` });
+    let t2 = new Blob([`import ${JSON.stringify(new URL(e66, SMAP_BASE_URL).href)}`], { type: `text/javascript` });
     return URL.createObjectURL(t2);
   }
   async function al() {
@@ -26862,14 +26863,14 @@ function smapCreateSdk(engine) {
  */
 (function (root, factory) {
   if (typeof module === 'object' && module.exports) {
-    module.exports = factory(root.maplibregl || require('maplibre-gl'));
+    module.exports = factory(root.maplibregl !== undefined ? root.maplibregl : require('maplibre-gl'));
   } else {
     root.sMap = factory(root.maplibregl);
   }
 })(typeof self !== 'undefined' ? self : this, function (engine) {
   'use strict';
 
-  var VERSION = '1.0.1';
+  var VERSION = '1.0.5';
   var FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
   var BASEMAP_SOURCE = 'basemap';
   var BUILDINGS_LAYER = 'smap-buildings-3d';
@@ -26885,10 +26886,16 @@ function smapCreateSdk(engine) {
     } catch (e) { return 0; }
   }
 
+  var GEOMETRY_TYPES = ['Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', 'MultiPolygon', 'GeometryCollection'];
+
   function toFeatureCollection(data) {
     if (!data) { return { type: 'FeatureCollection', features: [] }; }
     if (data.type === 'FeatureCollection') { return data; }
     if (data.type === 'Feature') { return { type: 'FeatureCollection', features: [data] }; }
+    // A bare geometry (a LineString from a directions answer, a Polygon, …) is GeoJSON too: one feature without properties.
+    if (GEOMETRY_TYPES.indexOf(data.type) !== -1) {
+      return { type: 'FeatureCollection', features: [{ type: 'Feature', properties: {}, geometry: data }] };
+    }
     if (Array.isArray(data)) {
       var features = new Array(data.length);
       for (var i = 0; i < data.length; i++) {
@@ -26962,6 +26969,203 @@ function smapCreateSdk(engine) {
     };
   }
 
+  // ------------------------------------------------------------------ popups
+
+  var POPUP_OPTIONS = ['className', 'maxWidth', 'minWidth', 'offset', 'anchor', 'closeButton', 'closeOnClick', 'focusAfterOpen', 'autoPan'];
+  // Shown while a popup's content is on its way: three pulsing dots, no text.
+  var POPUP_LOADING = '<div class="smap-popup-loading" role="status"><span></span><span></span><span></span></div>';
+  var HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+  function escapeHtml(value) {
+    return String(value).replace(/[&<>"']/g, function (c) { return HTML_ESCAPES[c]; });
+  }
+
+  /**
+   * A popup function from a template: every {name} is replaced by the feature's property of that name, HTML-escaped
+   * (empty when the feature has none). The template itself is trusted HTML. Compiled once; nothing runs until a click.
+   *   popupTemplate('<b>{name}</b><br>{address}')
+   */
+  function popupTemplate(template) {
+    // Even entries are the template's own text, odd entries property names.
+    var parts = String(template).split(/\{([^{}]+)\}/);
+    for (var i = 1; i < parts.length; i += 2) { parts[i] = parts[i].trim(); }
+    return function (properties) {
+      var out = parts[0];
+      for (var j = 1; j < parts.length; j += 2) {
+        var v = properties ? properties[parts[j]] : undefined;
+        out += (v === undefined || v === null ? '' : escapeHtml(v)) + parts[j + 1];
+      }
+      return out;
+    };
+  }
+
+  function isThenable(v) { return !!v && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function'; }
+
+  function cssSize(v) { return typeof v === 'number' ? v + 'px' : v; }
+
+  // ------------------------------------------------------------------ drawn images (pins, numbers, badges, arrows)
+
+  // A style value: a constant, {property: 'name'} (the feature's property, `default` when it has none), or an engine
+  // expression (an array).
+  function valueExpr(v, fallback) {
+    if (v === undefined || v === null) { return fallback; }
+    if (Array.isArray(v)) { return v; }
+    if (typeof v === 'object' && v.property) {
+      return v['default'] !== undefined ? ['coalesce', ['get', v.property], v['default']] : ['get', v.property];
+    }
+    return v;
+  }
+
+  // Image ids carry what the image shows; the map draws each one the first time a feature needs it (see _drawImage).
+  var IMAGE_PREFIX = 'smap-img|';
+  var SQRT1_2 = Math.SQRT1_2;
+
+  // The pin of Superroute's route map: a square with three rounded corners turned 45 degrees, its sharp corner the tip.
+  // tipToHead: from the position up to the centre of the round part (where the number goes); badge: the badge's centre
+  // from the position (right of the round part, as the page's badge sits on the turned pin's corner).
+  function markerGeometry(shape, size) {
+    var k = size / 32;
+    if (shape === 'circle') {
+      return { k: k, tipToHead: 0, badge: [size * 0.36, -size * 0.36] };
+    }
+    var half = size * SQRT1_2; // the centre of the round part, above the tip
+    return { k: k, tipToHead: half, badge: [14.1 * k, -half] };
+  }
+
+  // A rounded rectangle path whose corners are ellipses: radii [[rx, ry] top-left, top-right, bottom-right, bottom-left].
+  function roundedPath(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    ctx.moveTo(x + r[0][0], y);
+    ctx.lineTo(x + w - r[1][0], y);
+    if (r[1][0] && r[1][1]) { ctx.ellipse(x + w - r[1][0], y + r[1][1], r[1][0], r[1][1], 0, -Math.PI / 2, 0); }
+    ctx.lineTo(x + w, y + h - r[2][1]);
+    if (r[2][0] && r[2][1]) { ctx.ellipse(x + w - r[2][0], y + h - r[2][1], r[2][0], r[2][1], 0, 0, Math.PI / 2); }
+    ctx.lineTo(x + r[3][0], y + h);
+    if (r[3][0] && r[3][1]) { ctx.ellipse(x + r[3][0], y + h - r[3][1], r[3][0], r[3][1], 0, Math.PI / 2, Math.PI); }
+    ctx.lineTo(x, y + r[0][1]);
+    if (r[0][0] && r[0][1]) { ctx.ellipse(x + r[0][0], y + r[0][1], r[0][0], r[0][1], 0, Math.PI, Math.PI * 1.5); }
+    ctx.closePath();
+  }
+
+  var PIN_PAD = 6; // room for the shadow around a pin, in pixels
+
+  // Each draw function gets a 2D context already scaled to the pixel ratio and returns nothing; sizes are in pixels.
+  var IMAGE_KINDS = {
+    // pin|shape|fill|border|borderWidth|size
+    pin: function (args) {
+      var shape = args[0], fill = args[1], border = args[2], bw = Number(args[3]), size = Number(args[4]);
+      var g = markerGeometry(shape, size);
+      var reach = shape === 'circle' ? size / 2 : g.tipToHead; // farthest the shape goes from its centre
+      var w = Math.ceil(2 * reach + 2 * PIN_PAD), h = w;
+      return {
+        width: w, height: h,
+        draw: function (ctx, ratio) {
+          var c = w / 2;
+          ctx.save();
+          ctx.translate(c, c);
+          var s = size / 2;
+          var outer, inner;
+          if (shape === 'circle') {
+            outer = function () { ctx.beginPath(); ctx.arc(0, 0, s, 0, Math.PI * 2); };
+            inner = function () { ctx.beginPath(); ctx.arc(0, 0, Math.max(0, s - bw), 0, Math.PI * 2); };
+            ctx.shadowOffsetY = 3 * ratio;
+          } else {
+            ctx.rotate(Math.PI / 4);
+            outer = function () { roundedPath(ctx, -s, -s, size, size, [[s, s], [s, size], [0, 0], [size, s]]); };
+            var t = Math.max(0, s - bw), r2 = Math.max(0, size - bw);
+            inner = function () { roundedPath(ctx, -s + bw, -s + bw, size - 2 * bw, size - 2 * bw, [[t, t], [t, r2], [0, 0], [r2, t]]); };
+            // The page's box-shadow (0 3px) turns with the pin.
+            ctx.shadowOffsetX = -3 * SQRT1_2 * ratio;
+            ctx.shadowOffsetY = 3 * SQRT1_2 * ratio;
+          }
+          ctx.shadowColor = 'rgba(0,0,0,0.3)';
+          ctx.shadowBlur = 8 * ratio;
+          outer();
+          ctx.fillStyle = border;
+          ctx.fill();
+          ctx.shadowColor = 'transparent';
+          inner();
+          ctx.fillStyle = fill;
+          ctx.fill();
+          ctx.restore();
+        },
+      };
+    },
+    // num|color|size|text   (bold, with the route map's text shadow)
+    num: function (args, measure) {
+      var color = args[0], size = Number(args[1]), text = args.slice(2).join('|');
+      var px = 14 * size / 32;
+      var font = 'bold ' + px + 'px monospace';
+      var w = Math.ceil(measure(font, text) + 6), h = Math.ceil(px * 1.4 + 4);
+      return {
+        width: w, height: h,
+        draw: function (ctx, ratio) {
+          ctx.font = font;
+          ctx.textAlign = 'center';
+          ctx.textBaseline = 'middle';
+          ctx.shadowColor = 'rgba(0,0,0,0.5)';
+          ctx.shadowOffsetX = ratio;
+          ctx.shadowOffsetY = ratio;
+          ctx.shadowBlur = 2 * ratio;
+          ctx.fillStyle = color;
+          ctx.fillText(text, w / 2, h / 2);
+        },
+      };
+    },
+    // badge|text   (red circle, white border, at least 18 px inside the border)
+    badge: function (args, measure) {
+      var text = args.join('|');
+      var font = 'bold 10px sans-serif';
+      var inner = Math.max(18, Math.ceil(measure(font, text) + 4));
+      var w = inner + 4 + 6, h = 18 + 4 + 6;
+      return {
+        width: w, height: h,
+        draw: function (ctx, ratio) {
+          var bw = inner + 4, bh = 22, x = 3, y = 2;
+          var r = bh / 2;
+          ctx.shadowColor = 'rgba(0,0,0,0.4)';
+          ctx.shadowOffsetY = 2 * ratio;
+          ctx.shadowBlur = 4 * ratio;
+          roundedPath(ctx, x, y, bw, bh, [[r, r], [r, r], [r, r], [r, r]]);
+          ctx.fillStyle = '#ffffff';
+          ctx.fill();
+          ctx.shadowColor = 'transparent';
+          roundedPath(ctx, x + 2, y + 2, bw - 4, bh - 4, [[r - 2, r - 2], [r - 2, r - 2], [r - 2, r - 2], [r - 2, r - 2]]);
+          ctx.fillStyle = '#e74c3c';
+          ctx.fill();
+          ctx.font = font;
+          ctx.textAlign = 'center';
+          ctx.textBaseline = 'middle';
+          ctx.fillStyle = '#ffffff';
+          ctx.fillText(text, x + bw / 2, y + bh / 2 + 0.5);
+        },
+      };
+    },
+    // arrow|size|color   (an open arrowhead pointing along the line, like the route map's)
+    arrow: function (args) {
+      var size = Number(args[0]), color = args.slice(1).join('|');
+      var w = Math.ceil(size + 4), h = w;
+      return {
+        width: w, height: h,
+        draw: function (ctx) {
+          var len = size, back = len * Math.cos(Math.PI / 6), half = len * Math.sin(Math.PI / 6);
+          var tipX = w / 2 + back / 2, cy = h / 2;
+          ctx.strokeStyle = color;
+          ctx.lineWidth = 2;
+          ctx.lineCap = 'round';
+          ctx.lineJoin = 'round';
+          ctx.beginPath();
+          ctx.moveTo(tipX - back, cy - half);
+          ctx.lineTo(tipX, cy);
+          ctx.lineTo(tipX - back, cy + half);
+          ctx.stroke();
+        },
+      };
+    },
+  };
+
+  function drawnImageId(kind, parts) { return ['concat', IMAGE_PREFIX + kind].concat(parts.reduce(function (a, p) { return a.concat(['|', p]); }, [])); }
+
   var NODE_TTL = 3600 * 1000;
 
   function timed(url, ms) {
@@ -27042,6 +27246,9 @@ function smapCreateSdk(engine) {
    * @param {boolean} [options.nearest=true]  read from the nearest sMap node (asked of baseUrl, remembered for an hour)
    * @param {string[]} [options.nodes]        node URLs known in advance, used while baseUrl is down
    * @param {'mercator'|'globe'} [options.projection]
+   * @param {Object} [options.popup]          default popup options of every layer and openPopup (className, maxWidth,
+   *                                          minWidth, offset, anchor, closeButton, closeOnClick, focusAfterOpen)
+   * @param {string|Node} [options.popupLoading]  shown while a popup's content is a pending promise (default: dots)
    * Every other option (center, zoom, pitch, bearing, minZoom, maxZoom, maxBounds, hash, …) goes to the engine.
    */
   function SMap(options) {
@@ -27061,6 +27268,12 @@ function smapCreateSdk(engine) {
     this._buildings = false;
     this._handlers = {};
     this._refreshTimer = null;
+    this._popupDefaults = options.popup || {};
+    this._popupLoading = options.popupLoading;
+    this._autoZoom = options.autoZoom !== false;
+    this._wasd = options.keyboard3D;
+    this._popup = null;
+    this._popupSeq = 0;
     // True between a style's load and the next style change. The engine's own isStyleLoaded() turns false while any
     // source is loading data, which would leave layers added meanwhile waiting for a load that never comes.
     this._styleReady = false;
@@ -27068,7 +27281,7 @@ function smapCreateSdk(engine) {
     var self = this;
     var engineOptions = {};
     for (var k in options) {
-      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes'].indexOf(k) < 0) {
+      if (Object.prototype.hasOwnProperty.call(options, k) && ['token', 'getToken', 'apiKey', 'style', 'language', 'baseUrl', 'projection', 'nearest', 'nodes', 'popup', 'popupLoading', 'autoZoom', 'keyboard3D'].indexOf(k) < 0) {
         engineOptions[k] = options[k];
       }
     }
@@ -27101,6 +27314,14 @@ function smapCreateSdk(engine) {
         badge._place();
       }
       self.engine.on('style.load', function () { self._styleReady = true; self._restore(); });
+      self._keyboard3D();
+      // One click handler for every layer's popup: the engine's hit test over those layers, the top feature opens.
+      self.engine.on('click', function (e) { self._popupClick(e); });
+      self._styleClass();
+      // Pins, numbers, badges and arrows are drawn the first time a feature needs one (and again after a style change).
+      if (self.engine.setMissingStyleImageResolver) {
+        self.engine.setMissingStyleImageResolver(function (id) { self._drawImage(id); });
+      }
       return new Promise(function (resolve) { self.engine.once('load', function () { resolve(self); }); });
     });
     if (this._token && this._getToken) { this._scheduleRefresh(); }
@@ -27136,10 +27357,242 @@ function smapCreateSdk(engine) {
     if (FLAVORS.indexOf(style) >= 0) { this._flavor = style; this._customStyle = null; } else { this._customStyle = style; }
     this._styleReady = false;
     this.engine.setStyle(this._styleUrl());
+    this._styleClass();
+    return this;
+  };
+
+  // The map container carries smap-style-<scheme>, so the stylesheet can follow the scheme (dark popups).
+  SMap.prototype._styleClass = function () {
+    var c = this.engine && this.engine.getContainer && this.engine.getContainer();
+    if (!c || !c.classList) { return; }
+    for (var i = 0; i < FLAVORS.length; i++) { c.classList.remove('smap-style-' + FLAVORS[i]); }
+    if (!this._customStyle) { c.classList.add('smap-style-' + this._flavor); }
+  };
+
+  // Draws an image the SDK named (IMAGE_PREFIX + kind|args) and adds it to the map; other names are left alone.
+  SMap.prototype._drawImage = function (id) {
+    if (typeof id !== 'string' || id.indexOf(IMAGE_PREFIX) !== 0) { return; }
+    var m = this.engine;
+    if (m.hasImage(id)) { return; }
+    var parts = id.slice(IMAGE_PREFIX.length).split('|');
+    var kind = IMAGE_KINDS[parts[0]];
+    if (!kind) { return; }
+    var doc = m.getContainer().ownerDocument;
+    var win = doc.defaultView || {};
+    var ratio = Math.min(3, Math.max(1, Math.ceil(win.devicePixelRatio || 1)));
+    var canvas = doc.createElement('canvas');
+    var ctx = canvas.getContext('2d');
+    var measure = function (font, text) { ctx.font = font; return ctx.measureText(text).width; };
+    var image = kind(parts.slice(1), measure);
+    canvas.width = Math.ceil(image.width * ratio);
+    canvas.height = Math.ceil(image.height * ratio);
+    ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+    image.draw(ctx, ratio);
+    m.addImage(id, ctx.getImageData(0, 0, canvas.width, canvas.height), { pixelRatio: ratio });
+    this._imagesDrawn = (this._imagesDrawn || 0) + 1;
+  };
+
+  /**
+   * Opens the map's popup at a position, closing the one open before (there is one popup per map).
+   * @param {Array|Object} lngLat              [lng, lat] or {lng, lat}
+   * @param {string|Node|Promise} content      trusted HTML (inserted as is, never sanitized), a DOM node, or a promise
+   *                                           of either (popupLoading shows meanwhile; a rejection closes the popup
+   *                                           and is reported as the map's 'error' event)
+   * @param {Object} [options]                 popup options over the map's `popup` defaults, and `loading`
+   */
+  SMap.prototype.openPopup = function (lngLat, content, options) {
+    var self = this;
+    if (!this.engine) { this.ready.then(function () { self.openPopup(lngLat, content, options); }); return this; }
+    this.closePopup();
+    if (!content) { return this; }
+    var seq = ++this._popupSeq;
+    var o = Object.assign({}, this._popupDefaults, options || {});
+    var engineOptions = { offset: 12, className: 'smap-popup' + (o.className ? ' ' + o.className : '') };
+    for (var i = 0; i < POPUP_OPTIONS.length; i++) {
+      var k = POPUP_OPTIONS[i];
+      if (k !== 'className' && k !== 'minWidth' && k !== 'autoPan' && o[k] !== undefined) { engineOptions[k] = k === 'maxWidth' ? cssSize(o[k]) : o[k]; }
+    }
+    var popup = new engine.Popup(engineOptions).setLngLat(lngLat);
+    this._popup = popup;
+    var pending = isThenable(content);
+    var loading = o.loading !== undefined ? o.loading : (this._popupLoading !== undefined ? this._popupLoading : POPUP_LOADING);
+    this._popupContent(popup, pending ? loading : content);
+    popup.addTo(this.engine);
+    var el = popup.getElement && popup.getElement();
+    if (el && o.minWidth !== undefined) { el.style.minWidth = cssSize(o.minWidth); }
+    if (o.autoPan !== false) {
+      // After the engine has placed it (next frame), so its box is final.
+      var raf = (typeof requestAnimationFrame === 'function') ? requestAnimationFrame : function (fn) { return setTimeout(fn, 16); };
+      raf(function () { if (self._popup === popup) { self._panIntoView(popup); } });
+    }
+    if (pending) {
+      content.then(function (answer) {
+        // A later popup, or a close, makes this answer stale.
+        if (seq !== self._popupSeq || self._popup !== popup) { return; }
+        if (answer) { self._popupContent(popup, answer); } else { self.closePopup(); }
+      }, function (error) {
+        if (seq !== self._popupSeq || self._popup !== popup) { return; }
+        self.closePopup();
+        self._reportError(error);
+      });
+    }
+    return this;
+  };
+
+  /** Pans the map so the popup is fully inside it, with a small margin (Leaflet's autoPan). */
+  SMap.prototype._panIntoView = function (popup) {
+    var m = this.engine, el = popup.getElement && popup.getElement();
+    if (!el || !m.getContainer || !m.panBy || !el.getBoundingClientRect) { return; }
+    var box = el.getBoundingClientRect(), frame = m.getContainer().getBoundingClientRect(), pad = 10, dx = 0, dy = 0;
+    if (box.top < frame.top + pad) { dy = box.top - frame.top - pad; } else if (box.bottom > frame.bottom - pad) { dy = box.bottom - frame.bottom + pad; }
+    if (box.left < frame.left + pad) { dx = box.left - frame.left - pad; } else if (box.right > frame.right - pad) { dx = box.right - frame.right + pad; }
+    if (dx || dy) { m.panBy([dx, dy], { duration: 250 }); }
+  };
+
+  /** Closes the map's popup, if one is open. */
+  SMap.prototype.closePopup = function () {
+    var popup = this._popup;
+    this._popup = null;
+    this._popupSeq++;
+    if (popup) { popup.remove(); }
     return this;
   };
 
+  SMap.prototype._popupContent = function (popup, content) {
+    if (typeof content === 'string') { popup.setHTML(content); } else { popup.setDOMContent(content); }
+  };
+
+  SMap.prototype._reportError = function (error) {
+    var m = this.engine;
+    if (m && engine.ErrorEvent && m.fire) { m.fire(new engine.ErrorEvent(error)); } else if (typeof console !== 'undefined') { console.error(error); }
+  };
+
+  // A click on the map: the top feature of the layers with a popup, if any, opens its layer's popup.
+  SMap.prototype._popupClick = function (e) {
+    var m = this.engine;
+    var ids = [];
+    var byEngineLayer = {};
+    for (var i = 0; i < this._order.length; i++) {
+      var def = this._layers[this._order[i]];
+      if (def.o.popup && def.popupLayer && !def.hidden && m.getLayer(def.popupLayer)) {
+        ids.push(def.popupLayer);
+        byEngineLayer[def.popupLayer] = def;
+        if (def.hoverLayer && m.getLayer(def.hoverLayer)) { ids.push(def.hoverLayer); byEngineLayer[def.hoverLayer] = def; }
+      }
+    }
+    if (!ids.length) { return; }
+    var hits = m.queryRenderedFeatures(e.point, { layers: ids });
+    if (!hits || !hits.length) { return; }
+    var f = hits[0];
+    var hit = byEngineLayer[f.layer && f.layer.id];
+    if (!hit) { return; }
+    // A tight pile of pins: zoom in around the click so they come apart, or, when they still overlap close up (or
+    // share one spot), offer a chooser. A layer turns this off with marker.overlap === false.
+    if (this._autoZoom && hit.o.marker && hit.o.marker.overlap !== false && e.point && m.project) {
+      var ov = hit.o.marker.overlap || {}, near = ov.radius || 12, threshold = ov.threshold || 4;
+      var box = [[e.point.x - near, e.point.y - near], [e.point.x + near, e.point.y + near]];
+      var seen = {}, pile = [];
+      (m.queryRenderedFeatures(box, { layers: ids }) || []).forEach(function (x) {
+        var d = byEngineLayer[x.layer && x.layer.id];
+        if (d !== hit || !x.geometry || x.geometry.type !== 'Point') { return; }
+        var key = JSON.stringify(x.geometry.coordinates) + JSON.stringify(x.properties || {});
+        if (!seen[key]) { seen[key] = true; pile.push(x); }
+      });
+      if (pile.length >= 2) {
+        var spots = {};
+        pile.forEach(function (x) { spots[x.geometry.coordinates.map(function (c) { return c.toFixed(6); }).join(',')] = true; });
+        var oneSpot = Object.keys(spots).length === 1;
+        var closeUp = m.getZoom() >= (ov.maxZoom || 17);
+        if (pile.length >= threshold && !oneSpot && !closeUp) {
+          m.easeTo({ center: e.lngLat, zoom: Math.min(m.getZoom() + (ov.zoomBy || 2), ov.maxZoom || 17), duration: 400 });
+          return;
+        }
+        if (pile.length >= threshold || oneSpot) { this._chooser(hit, pile, e.lngLat); return; }
+      }
+    }
+    this._openFeaturePopup(hit, f, e.lngLat);
+  };
+
+  /** A small list of the pins under a click; choosing one opens its popup. */
+  SMap.prototype._chooser = function (hit, pile, lngLat) {
+    var self = this, mk = hit.o.marker, doc = this.engine.getContainer().ownerDocument;
+    var list = doc.createElement('div');
+    list.className = 'smap-chooser';
+    var esc = function (v) { return String(v == null ? '' : v).replace(/[&<>"']/g, function (c) { return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]; }); };
+    var plainValue = function (v, p) {
+      if (v && typeof v === 'object' && !Array.isArray(v) && v.property) { return p[v.property] !== undefined ? p[v.property] : v.default; }
+      return Array.isArray(v) ? undefined : v;
+    };
+    pile.slice(0, 50).forEach(function (x, i) {
+      var p = x.properties || {};
+      var label = mk.overlap && typeof mk.overlap.label === 'function' ? mk.overlap.label(p, x) : null;
+      var number = plainValue(mk.text, p), fill = plainValue(mk.fill, p) || '#ffffff', border = plainValue(mk.border, p) || hit.o.color || '#4f46e5';
+      var item = doc.createElement('button');
+      item.type = 'button';
+      item.className = 'smap-chooser-item';
+      item.innerHTML = '<span class="smap-chooser-pin" style="background:' + esc(fill) + ';border-color:' + esc(border) + '">' + esc(number == null ? '' : number) + '</span>'
+        + '<span class="smap-chooser-label">' + esc(label != null ? label : (number != null ? number : i + 1)) + '</span>';
+      item.addEventListener('click', function (ev) { ev.stopPropagation(); self._openFeaturePopup(hit, x, x.geometry.coordinates); });
+      list.appendChild(item);
+    });
+    this._unpin();
+    this.openPopup(lngLat, list, { className: 'smap-chooser-popup', anchor: 'bottom', offset: 12 });
+  };
+
+  /** Opens a feature's own popup (the layer's popup function), above a pin when the layer draws pins. */
+  SMap.prototype._openFeaturePopup = function (hit, f, lngLat) {
+    var m = this.engine;
+    // Points open at their own position; lines and areas where they were clicked.
+    var at = hit.kind === 'points' && f.geometry && f.geometry.type === 'Point' ? f.geometry.coordinates : lngLat;
+    var content;
+    try { content = hit.o.popup(f.properties || {}, f); } catch (error) { this._reportError(error); return; }
+    var popupOptions = Object.assign({}, hit.o.popupOptions || {});
+    if (hit.o.marker && popupOptions.offset === undefined && this._popupDefaults.offset === undefined) {
+      // Just above the pin as it is drawn now (its scale may follow the zoom).
+      var mk = hit.o.marker, size = mk.size || 32, k = scaleAt(mk.scale, m.getZoom ? m.getZoom() : 0);
+      popupOptions.offset = mk.shape === 'circle' ? Math.round((size / 2) * k + 4) : Math.round((markerGeometry('pin', size).tipToHead + size / 2) * k + 2);
+    }
+    // Above the pin, always (as on Superroute's route map); the map pans to make room instead of flipping it below.
+    if (hit.o.marker && popupOptions.anchor === undefined && this._popupDefaults.anchor === undefined) { popupOptions.anchor = 'bottom'; }
+    if (hit.o.popupLoading !== undefined) { popupOptions.loading = hit.o.popupLoading; }
+    this._unpin();
+    this.openPopup(at, content, popupOptions);
+    // The clicked pin stays in front while its popup is open (the route map's rule).
+    if (hit.hoverSource && this._popup) {
+      var self = this, popup = this._popup;
+      this._setHover(null, hit, f, 'popup');
+      hit.pinned = popup;
+      this._pinnedDef = hit;
+      if (popup.on) { popup.on('close', function () { if (hit.pinned === popup) { self._unpin(); } }); }
+    }
+  };
+
   /** Switches the label language; your layers are kept. */
+  /**
+   * A marker scale at a zoom: a number, or the linear / step zoom expressions the SDK documents
+   * (['interpolate', ['linear'], ['zoom'], z, v, …], ['step', ['zoom'], v, z, v, …]); anything else counts as 1.
+   */
+  function scaleAt(scale, zoom) {
+    if (scale === undefined || scale === null) { return 1; }
+    if (typeof scale === 'number') { return scale; }
+    if (!Array.isArray(scale)) { return 1; }
+    var isZoom = function (x) { return Array.isArray(x) && x[0] === 'zoom'; };
+    if (scale[0] === 'interpolate' && isZoom(scale[2])) {
+      var stops = scale.slice(3);
+      if (zoom <= stops[0]) { return stops[1]; }
+      for (var i = 2; i < stops.length; i += 2) {
+        if (zoom <= stops[i]) { var t = (zoom - stops[i - 2]) / (stops[i] - stops[i - 2]); return stops[i - 1] + t * (stops[i + 1] - stops[i - 1]); }
+      }
+      return stops[stops.length - 1];
+    }
+    if (scale[0] === 'step' && isZoom(scale[1])) {
+      var value = scale[2];
+      for (var j = 3; j < scale.length; j += 2) { if (zoom >= scale[j]) { value = scale[j + 1]; } }
+      return value;
+    }
+    return 1;
+  }
+
   SMap.prototype.setLanguage = function (language) {
     this._language = language;
     if (!this._customStyle) { this._styleReady = false; this.engine.setStyle(this._styleUrl()); }
@@ -27154,6 +27607,33 @@ function smapCreateSdk(engine) {
   };
 
   /** Shows buildings in 3D (and tilts the map when it is flat). */
+  /**
+   * Auto Zoom: a click on pins piled up zooms the map in around it, or lists them close up (see marker.overlap).
+   * On by default (`autoZoom: false` in the options turns it off).
+   */
+  SMap.prototype.setAutoZoom = function (on) { this._autoZoom = !!on; return this; };
+  SMap.prototype.autoZoom = function () { return this._autoZoom; };
+
+  /**
+   * In 3D (3D buildings on, or the map tilted) W / S tilt the view and A / D turn it; Shift takes bigger steps. Only
+   * while the map has the keyboard focus, so typing elsewhere on the page is never taken.
+   */
+  SMap.prototype._keyboard3D = function () {
+    var self = this, m = this.engine;
+    var el = m.getCanvasContainer ? m.getCanvasContainer() : (m.getContainer ? m.getContainer() : null);
+    if (!el || !el.addEventListener || this._wasd === false) { return; }
+    el.addEventListener('keydown', function (e) {
+      if (e.altKey || e.ctrlKey || e.metaKey) { return; }
+      if (!self._buildings && m.getPitch() < 1) { return; }
+      var big = e.shiftKey, key = (e.key || '').toLowerCase();
+      var pitch = m.getPitch(), bearing = m.getBearing();
+      if (key === 'w') { pitch = Math.min(85, pitch + (big ? 15 : 5)); } else if (key === 's') { pitch = Math.max(0, pitch - (big ? 15 : 5)); }
+      else if (key === 'a') { bearing -= big ? 45 : 15; } else if (key === 'd') { bearing += big ? 45 : 15; } else { return; }
+      e.preventDefault();
+      m.easeTo({ pitch: pitch, bearing: bearing, duration: 200 });
+    });
+  };
+
   SMap.prototype.setBuildings3D = function (on, options) {
     this._buildings = !!on;
     this._buildingOptions = options || this._buildingOptions || {};
@@ -27192,8 +27672,9 @@ function smapCreateSdk(engine) {
    * @param {Object|Array} data   GeoJSON, or an array of {lng, lat, …properties}
    * @param {Object} [o]
    *   cluster: true | {radius, maxZoom}; color; radius; strokeColor; icon (image URL); iconSize; label (property name);
-   *   minzoom; maxzoom; zIndex (higher draws on top); onClick(feature, event); popup(properties) → trusted HTML
-   *   (inserted as is, never sanitized: escape feature data) or a DOM node
+   *   minzoom; maxzoom; zIndex (higher draws on top); onClick(feature, event);
+   *   popup(properties, feature) → trusted HTML (inserted as is, never sanitized: escape feature data, or use
+   *   sMap.popupTemplate), a DOM node, or a promise of either; popupOptions (over the map's `popup`); popupLoading
    */
   SMap.prototype.addPoints = function (id, data, o) {
     o = o || {};
@@ -27221,6 +27702,7 @@ function smapCreateSdk(engine) {
     var def = this._layers[id];
     if (!def) { throw new Error('sMap: no layer ' + id); }
     def.data = toFeatureCollection(data);
+    if (def.hovered) { this._setHover(id, def, null); }
     var src = this.engine.getSource('smap-' + id);
     if (src) { src.setData(def.data); }
     return this;
@@ -27299,7 +27781,9 @@ function smapCreateSdk(engine) {
     if (!m) { return; }
     def.engineLayers.forEach(function (l) { if (m.getLayer(l)) { m.removeLayer(l); } });
     if (m.getSource('smap-' + id)) { m.removeSource('smap-' + id); }
-    (this._handlers[id] || []).forEach(function (h) { m.off(h[0], h[1], h[2]); });
+    if (m.getSource('smap-' + id + '-hover')) { m.removeSource('smap-' + id + '-hover'); }
+    def.hoverLayer = null; def.hovered = null;
+    (this._handlers[id] || []).forEach(function (h) { if (h[1]) { m.off(h[0], h[1], h[2]); } else { m.off(h[0], h[2]); } });
     this._handlers[id] = [];
     def.engineLayers = [];
   };
@@ -27332,7 +27816,10 @@ function smapCreateSdk(engine) {
       layer.source = src;
       // The engine refuses a filter key whose value is undefined (unclustered points have none).
       if (layer.filter === undefined) { delete layer.filter; }
-      for (var k in range) { layer[k] = range[k]; }
+      if (layer.minzoom === undefined) { delete layer.minzoom; }
+      if (layer.paint === undefined) { delete layer.paint; }
+      // A layer's own minzoom (a marker's textMinzoom / badgeMinzoom) never shows it before the layer's own range.
+      for (var k in range) { layer[k] = k === 'minzoom' && layer.minzoom !== undefined ? Math.max(layer.minzoom, range.minzoom) : range[k]; }
       layer.layout = Object.assign({ visibility: visibility }, layer.layout || {});
       m.addLayer(layer, before);
       def.engineLayers.push(layer.id);
@@ -27362,7 +27849,57 @@ function smapCreateSdk(engine) {
         });
       }
       var only = o.cluster ? ['!', ['has', 'point_count']] : undefined;
-      if (o.icon) {
+      var both = function (extra) { return only ? ['all', only, extra] : extra; };
+      if (o.marker) {
+        // Pins like Superroute's route map, drawn on the GPU: one image per colour pair (and per number, per badge),
+        // made the first time a feature shows it. Numbers and badges are their own layers above the pins.
+        var mk = o.marker;
+        var shape = mk.shape === 'circle' ? 'circle' : 'pin';
+        var size = mk.size || 32;
+        var bw = mk.borderWidth !== undefined ? mk.borderWidth : 3;
+        var g = markerGeometry(shape, size);
+        var str = function (v, d) { return ['to-string', valueExpr(v, d)]; };
+        // One scale for the pin, its number and its badge (a number, or an engine expression such as one of the zoom),
+        // so the three stay together at every size: the offsets are in icon units and scale with them.
+        var scale = mk.scale !== undefined ? mk.scale : 1;
+        // Opacity of the pin, its number and its badge together (the route map draws settled stops at .72).
+        var markerPaint = mk.opacity !== undefined ? { 'icon-opacity': valueExpr(mk.opacity, 1) } : undefined;
+        main = src + '-points';
+        var markerSpecs = [];
+        var addMarker = function (layer) { markerSpecs.push(JSON.parse(JSON.stringify(layer))); add(layer); };
+        addMarker({
+          id: main, type: 'symbol', filter: only, paint: markerPaint,
+          layout: {
+            'icon-image': drawnImageId('pin', [shape, str(mk.fill, '#ffffff'), str(mk.border, color), String(bw), String(size)]),
+            'icon-anchor': shape === 'circle' ? 'center' : 'bottom',
+            // The image has room for the shadow below the tip: the tip, not the image's edge, is at the position.
+            'icon-offset': [0, shape === 'circle' ? 0 : PIN_PAD], 'icon-size': scale,
+            'icon-allow-overlap': true, 'icon-ignore-placement': true,
+          },
+        });
+        if (mk.text !== undefined) {
+          var text = str(mk.text, '');
+          addMarker({
+            id: src + '-numbers', type: 'symbol', filter: both(['!=', text, '']), minzoom: mk.textMinzoom, paint: markerPaint,
+            layout: {
+              'icon-image': drawnImageId('num', [str(mk.textColor, '#ffffff'), String(size), text]),
+              'icon-offset': [0, -g.tipToHead], 'icon-size': scale, 'icon-allow-overlap': true, 'icon-ignore-placement': true,
+            },
+          });
+        }
+        if (mk.badge !== undefined) {
+          var badge = ['to-number', valueExpr(mk.badge, 0), 0];
+          addMarker({
+            id: src + '-badges', type: 'symbol', filter: both(['>', badge, 1]), minzoom: mk.badgeMinzoom, paint: markerPaint,
+            layout: {
+              'icon-image': drawnImageId('badge', [['to-string', badge]]),
+              'icon-offset': g.badge, 'icon-size': scale,
+              'icon-allow-overlap': true, 'icon-ignore-placement': true,
+            },
+          });
+        }
+        if (mk.hoverRaise !== false) { this._hoverRaise(id, def, src, markerSpecs, main); }
+      } else if (o.icon) {
         var imageId = src + '-icon';
         main = src + '-points';
         var placeIcon = function () {
@@ -27396,9 +27933,35 @@ function smapCreateSdk(engine) {
       }
     } else if (def.kind === 'lines') {
       main = src + '-lines';
-      var paint = { 'line-color': color, 'line-width': o.width || 3, 'line-opacity': o.opacity !== undefined ? o.opacity : 1 };
+      var lineColor = valueExpr(o.color, '#4f46e5');
+      var round = { 'line-cap': 'round', 'line-join': 'round' };
+      // Bottom to top: casing, shadow, the line, its arrows (as on Superroute's route map).
+      if (o.casing) {
+        var cs = o.casing === true ? {} : o.casing;
+        add({ id: src + '-casing', type: 'line', layout: round, paint: {
+          'line-color': valueExpr(cs.color, '#ffffff'), 'line-width': cs.width || 9, 'line-opacity': cs.opacity !== undefined ? cs.opacity : 1 } });
+      }
+      if (o.shadow) {
+        var sh = o.shadow === true ? {} : o.shadow;
+        add({ id: src + '-shadow', type: 'line', layout: round, paint: {
+          'line-color': valueExpr(sh.color, '#000000'), 'line-width': sh.width || 7, 'line-opacity': sh.opacity !== undefined ? sh.opacity : 0.3 } });
+      }
+      var paint = { 'line-color': lineColor, 'line-width': o.width || 3, 'line-opacity': o.opacity !== undefined ? o.opacity : 1 };
       if (o.dash) { paint['line-dasharray'] = o.dash; }
-      add({ id: main, type: 'line', layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: paint });
+      add({ id: main, type: 'line', layout: round, paint: paint });
+      if (o.arrows) {
+        var ar = o.arrows === true ? {} : o.arrows;
+        var arrowSize = ar.size || 14;
+        add({
+          id: src + '-arrows', type: 'symbol',
+          layout: {
+            'symbol-placement': 'line', 'symbol-spacing': ar.spacing || 80,
+            'icon-image': drawnImageId('arrow', [String(arrowSize), ['to-string', valueExpr(ar.color, lineColor)]]),
+            'icon-rotation-alignment': 'map', 'icon-allow-overlap': true, 'icon-ignore-placement': true,
+          },
+          paint: { 'icon-opacity': ar.opacity !== undefined ? ar.opacity : 0.8 },
+        });
+      }
     } else {
       if (o.extrude) {
         main = src + '-extrusion';
@@ -27418,32 +27981,74 @@ function smapCreateSdk(engine) {
         add({ id: src + '-outline', type: 'line', paint: { 'line-color': o.outline || o.fill || color, 'line-width': o.outlineWidth || 1.5 } });
       }
     }
+    // The popup is opened by the map's one click handler (_popupClick), from this layer's own hit test.
+    def.popupLayer = o.popup ? main : null;
     if (main && (o.popup || o.onClick)) {
-      this._listen(id, 'click', main, function (e) {
-        var f = e.features[0];
-        if (o.onClick) { o.onClick(f, e); }
-        if (o.popup) {
-          // A string is inserted as HTML as it is (never sanitized): it must be trusted, with feature data escaped.
-          // A DOM node is inserted as it is.
-          var content = o.popup(f.properties, f);
-          if (content) {
-            var popup = new engine.Popup({ offset: 12 }).setLngLat(e.lngLat);
-            if (typeof content === 'string') { popup.setHTML(content); } else { popup.setDOMContent(content); }
-            popup.addTo(m);
-          }
-        }
-      });
+      if (o.onClick) {
+        this._listen(id, 'click', main, function (e) { o.onClick(e.features[0], e); });
+      }
       this._listen(id, 'mouseenter', main, function () { m.getCanvas().style.cursor = 'pointer'; });
       this._listen(id, 'mouseleave', main, function () { m.getCanvas().style.cursor = ''; });
     }
   };
 
+  /**
+   * Overlapping pins: the one under the pointer comes to the front, as on Superroute's route map, so it can be read
+   * and clicked. A copy of that one feature is drawn in its own source above everything else; nothing is done per
+   * feature, only for the feature under the pointer.
+   */
+  SMap.prototype._hoverRaise = function (id, def, src, specs, main) {
+    var m = this.engine, self = this;
+    var hoverSrc = src + '-hover';
+    m.addSource(hoverSrc, { type: 'geojson', data: { type: 'FeatureCollection', features: [] } });
+    var top = null;
+    specs.forEach(function (spec) {
+      var layer = JSON.parse(JSON.stringify(spec));
+      layer.id = spec.id.replace(src + '-', src + '-hover-');
+      layer.source = hoverSrc;
+      if (layer.filter === undefined) { delete layer.filter; }
+      if (layer.paint === undefined) { delete layer.paint; }
+      if (layer.minzoom === undefined) { delete layer.minzoom; }
+      m.addLayer(layer);
+      def.engineLayers.push(layer.id);
+      if (!top) { top = layer.id; }
+    });
+    def.hoverLayer = top;
+    def.hoverSource = hoverSrc;
+    var keyOf = function (f) { return JSON.stringify(f.geometry && f.geometry.coordinates) + JSON.stringify(f.properties || {}); };
+    this._listen(id, 'mousemove', null, function (e) {
+      if (def.hidden || !m.getLayer(main) || def.pinned) { return; }
+      // Still over the raised pin: keep it. Otherwise raise the top pin under the pointer, if any.
+      if (def.hovered && m.getLayer(top) && m.queryRenderedFeatures(e.point, { layers: [top] }).length) { return; }
+      var hits = m.queryRenderedFeatures(e.point, { layers: [main] });
+      var f = hits && hits[0];
+      if (!f) { if (def.hovered) { self._setHover(id, def, null); } return; }
+      if (def.hovered && def.hovered.key === keyOf(f)) { return; }
+      self._setHover(id, def, f, keyOf(f));
+    });
+    this._listen(id, 'mouseout', null, function () { if (def.hovered && !def.pinned) { self._setHover(id, def, null); } });
+  };
+
+  SMap.prototype._unpin = function () {
+    var def = this._pinnedDef;
+    this._pinnedDef = null;
+    if (def) { def.pinned = null; this._setHover(null, def, null); }
+  };
+
+  SMap.prototype._setHover = function (id, def, f, key) {
+    var source = def.hoverSource && this.engine.getSource(def.hoverSource);
+    def.hovered = f ? { key: key } : null;
+    if (!source) { return; }
+    // A plain copy: the engine's own feature objects cannot be sent to its worker.
+    source.setData({ type: 'FeatureCollection', features: f ? [JSON.parse(JSON.stringify({ type: 'Feature', properties: f.properties || {}, geometry: f.geometry }))] : [] });
+  };
+
   SMap.prototype._listen = function (id, type, layer, fn) {
-    this.engine.on(type, layer, fn);
+    if (layer) { this.engine.on(type, layer, fn); } else { this.engine.on(type, fn); }
     (this._handlers[id] = this._handlers[id] || []).push([type, layer, fn]);
   };
 
-  return { Map: SMap, version: VERSION, styles: FLAVORS.slice(), engine: engine };
+  return { Map: SMap, version: VERSION, styles: FLAVORS.slice(), engine: engine, popupTemplate: popupTemplate };
 });
 
   return module.exports;