@superrouteca/smap-mapbox 0.0.0-stage → 1.1.0

package/src/common/embed.js

@@ -0,0 +1,166 @@
+// sMap tool adapters — an sMap map (the Web SDK) drawn inside another tool. The tool owns the camera and the input;
+// the embedded map draws the basemap and sMap's layers. Its own camera moves (Auto Zoom, fitLayer, flyTo, a popup
+// panning into view) are handed to the tool, and the tool's clicks and pointer moves are handed to it, so popups,
+// Auto Zoom, hover and onClick work as on an sMap map. Kept identical in leaflet/, openlayers/ and mapbox/
+// (test/common.test.mjs checks).
+import { injectCss, mergeAttributions } from './badge.js';
+
+/** The engine's camera calls that are sent to the tool instead of moving the embedded map on its own. */
+export const CAMERA_CALLS = ['jumpTo', 'easeTo', 'flyTo', 'fitBounds', 'panBy', 'panTo', 'setCenter', 'setZoom', 'zoomTo',
+  'zoomIn', 'zoomOut', 'setBearing', 'rotateTo', 'setPitch'];
+const INSTANT = ['jumpTo', 'setCenter', 'setZoom', 'setBearing', 'setPitch'];
+
+/** The SDK options the embedding sets itself. */
+const OWN_OPTIONS = { interactive: false, attributionControl: false, keyboard3D: false };
+
+function lngLatOf(engineModule, v) {
+  if (v == null) { return null; }
+  if (engineModule && engineModule.LngLat && engineModule.LngLat.convert) {
+    const c = engineModule.LngLat.convert(v);
+    return { lng: c.lng, lat: c.lat };
+  }
+  if (Array.isArray(v)) { return { lng: +v[0], lat: +v[1] }; }
+  return { lng: +(v.lng !== undefined ? v.lng : v.lon), lat: +v.lat };
+}
+
+/**
+ * Where a camera call would take the engine: { center: {lng, lat}, zoom, bearing, pitch } and how to get there
+ * ({ animate, duration, fly }). Pure over the engine's read-only calls (getCenter, project, cameraForBounds, …).
+ */
+export function cameraTarget(engine, engineModule, call, args) {
+  const c = engine.getCenter();
+  const t = { center: { lng: c.lng, lat: c.lat }, zoom: engine.getZoom(), bearing: engine.getBearing ? engine.getBearing() : 0, pitch: engine.getPitch ? engine.getPitch() : 0 };
+  let o = {};
+  const take = function (cam) {
+    if (!cam) { return; }
+    if (cam.center !== undefined) { t.center = lngLatOf(engineModule, cam.center); }
+    if (typeof cam.zoom === 'number') { t.zoom = cam.zoom; }
+    if (typeof cam.bearing === 'number') { t.bearing = cam.bearing; }
+    if (typeof cam.pitch === 'number') { t.pitch = cam.pitch; }
+  };
+  switch (call) {
+    case 'jumpTo': case 'easeTo': case 'flyTo': o = args[0] || {}; take(o); break;
+    case 'fitBounds': o = args[1] || {}; take(engine.cameraForBounds ? engine.cameraForBounds(args[0], o) : null); break;
+    case 'panBy': {
+      o = args[1] || {};
+      const off = Array.isArray(args[0]) ? args[0] : [args[0].x, args[0].y];
+      const p = engine.project([t.center.lng, t.center.lat]);
+      take({ center: engine.unproject([p.x + off[0], p.y + off[1]]) });
+      break;
+    }
+    case 'panTo': o = args[1] || {}; take({ center: args[0] }); break;
+    case 'setCenter': take({ center: args[0] }); break;
+    case 'setZoom': take({ zoom: args[0] }); break;
+    case 'zoomTo': o = args[1] || {}; take({ zoom: args[0] }); break;
+    case 'zoomIn': o = args[0] || {}; t.zoom += 1; break;
+    case 'zoomOut': o = args[0] || {}; t.zoom -= 1; break;
+    case 'setBearing': take({ bearing: args[0] }); break;
+    case 'rotateTo': o = args[1] || {}; take({ bearing: args[0] }); break;
+    case 'setPitch': take({ pitch: args[0] }); break;
+    default: break;
+  }
+  const animate = INSTANT.indexOf(call) < 0 && o.animate !== false && o.duration !== 0;
+  return { target: t, how: { animate: animate, duration: typeof o.duration === 'number' ? o.duration : undefined, fly: call === 'flyTo' } };
+}
+
+/**
+ * Creates the embedded sMap map.
+ *
+ * @param {Object} sdk         the sMap Web SDK module (`Map`, `getEngine`)
+ * @param {HTMLElement} el     the element it draws in (sized and placed by the caller)
+ * @param {Object} options     sMap map options (style, language, apiKey, token, getToken, baseUrl, …)
+ * @param {Object} hooks       move(target, how): move the tool's camera; attribution(list): the credits changed
+ */
+export function createEmbedded(sdk, el, options, hooks) {
+  injectCss(el.ownerDocument);
+  el.classList.add('smap-embedded');
+  const map = new sdk.Map(Object.assign({ minZoom: -2, maxZoom: 24 }, options, OWN_OPTIONS, { container: el }));
+  const engineModule = typeof sdk.getEngine === 'function' ? sdk.getEngine() : null;
+  const state = { jumpTo: null, engine: null, credits: [], removed: false };
+
+  function credits() {
+    const engine = state.engine;
+    const list = [];
+    try {
+      const caches = engine.style && (engine.style.sourceCaches || engine.style._sourceCaches);
+      const ids = caches ? Object.keys(caches) : Object.keys((engine.getStyle() || {}).sources || {});
+      ids.forEach(function (id) {
+        const s = engine.getSource(id);
+        if (s && typeof s.attribution === 'string') { list.push(s.attribution); }
+      });
+    } catch (e) { /* no style yet */ }
+    const merged = mergeAttributions(list);
+    if (merged.join('\n') !== state.credits.join('\n')) {
+      state.credits = merged;
+      if (hooks.attribution) { hooks.attribution(merged.slice()); }
+    }
+  }
+
+  function adopt(engine) {
+    if (state.engine || !engine) { return; }
+    state.engine = engine;
+    state.jumpTo = engine.jumpTo.bind(engine);
+    CAMERA_CALLS.forEach(function (call) {
+      if (typeof engine[call] !== 'function') { return; }
+      engine[call] = function () {
+        const r = cameraTarget(engine, engineModule, call, Array.prototype.slice.call(arguments));
+        if (hooks.move) { hooks.move(r.target, r.how); }
+        return engine;
+      };
+    });
+    if (engine.on) {
+      engine.on('sourcedata', function (e) { if (!e || e.sourceDataType === 'metadata' || e.isSourceLoaded) { credits(); } });
+      engine.on('styledata', credits);
+    }
+    credits();
+    if (hooks.adopted) { hooks.adopted(engine); }
+  }
+
+  const ready = map.ready.then(function (m) { adopt(m.engine); return m; });
+
+  const api = {
+    map: map,
+    ready: ready,
+    /** The engine once created (null before). */
+    engine: function () { return state.engine || (map.engine && (adopt(map.engine), state.engine)) || null; },
+    /** Puts the embedded camera where the tool's is (zoom in the engine's 512 px scale). */
+    sync: function (camera) {
+      const engine = api.engine();
+      if (!engine || state.removed) { return; }
+      state.jumpTo({ center: [camera.center.lng, camera.center.lat], zoom: camera.zoom, bearing: camera.bearing || 0, pitch: camera.pitch || 0 });
+      if (camera.redraw && typeof engine.redraw === 'function') { engine.redraw(); }
+    },
+    resize: function () { const engine = api.engine(); if (engine && engine.resize) { engine.resize(); } },
+    /**
+     * Hands one of the tool's pointer events to the embedded map (click, dblclick, mousemove, mouseout, contextmenu):
+     * `x`, `y` in pixels of the embedded map's element, the position, and the browser event.
+     */
+    forward: function (type, x, y, lngLat, originalEvent) {
+      const engine = api.engine();
+      if (!engine || state.removed) { return; }
+      const point = engineModule && engineModule.Point ? new engineModule.Point(x, y) : { x: x, y: y };
+      const ll = engineModule && engineModule.LngLat ? new engineModule.LngLat(lngLat.lng, lngLat.lat) : lngLat;
+      engine.fire(type, { point: point, lngLat: ll, originalEvent: originalEvent, type: type });
+      // The tool's element shows the pointer the embedded map asks for (a hand over a clickable feature).
+      if (type === 'mousemove' && hooks.cursor && engine.getCanvas) { hooks.cursor(engine.getCanvas().style.cursor || ''); }
+    },
+    /** True when the browser event happened inside one of the embedded map's popups (the popup handles it). */
+    inPopup: function (originalEvent) {
+      const t = originalEvent && originalEvent.target;
+      return !!(t && typeof t.closest === 'function' && t.closest('.maplibregl-popup'));
+    },
+    credits: function () { return state.credits.slice(); },
+    remove: function () { state.removed = true; map.remove(); },
+  };
+  return api;
+}
+
+/** True where the browser can draw the vector map (WebGL 2). */
+export function hasWebGL2(doc) {
+  try {
+    const d = doc || (typeof document !== 'undefined' ? document : null);
+    if (!d) { return false; }
+    const c = d.createElement('canvas');
+    return !!(c.getContext && c.getContext('webgl2'));
+  } catch (e) { return false; }
+}

package/src/index.js

@@ -0,0 +1,475 @@
+// @superrouteca/smap-mapbox — sMap in Mapbox GL JS: sMap's style drawn by Mapbox GL JS itself (schemes, custom
+// styles, labels in any language, basemap overrides, 3D buildings), map key or token with renewal on every request,
+// the nearest node with failover, the credits and the sMap badge; sMap's pins, lines and areas (popups, Auto Zoom)
+// on a layer above, drawn by the sMap Web SDK and following Mapbox GL JS' camera. Mapbox GL JS styles and layers on an
+// sMap map are in './on-smap.js' (`@superrouteca/smap-mapbox/on-smap`).
+//
+// Mapbox GL JS is passed in (`new SMapMapbox(mapboxgl, options)`), so this package never bundles or imports it.
+import * as sMapModule from '@superrouteca/smap';
+import { SMapAccess, checkStyle, rasterPath, stylePath, FLAVORS, DEFAULT_BASE } from './common/access.js';
+import { OSM_ATTRIBUTION, createBadge, injectCss } from './common/badge.js';
+import { createEmbedded } from './common/embed.js';
+
+const SDK = sMapModule.default && sMapModule.default.Map ? sMapModule.default : sMapModule;
+
+export const version = '1.1.0';
+export { FLAVORS as styles, checkStyle, rasterPath, stylePath, SMapAccess, DEFAULT_BASE, OSM_ATTRIBUTION };
+
+const ACCESS_OPTIONS = ['baseUrl', 'token', 'getToken', 'apiKey', 'nodes', 'nearest', 'fetch', 'timeoutMs', 'client', 'access'];
+const OWN_OPTIONS = ['style', 'language', 'basemap', 'buildings3D', 'sdk', 'popup', 'popupLoading', 'autoZoom', 'overlay'];
+const BUILDINGS_LAYER = 'smap-buildings-3d';
+const BASEMAP_SOURCE = 'basemap';
+/** Mapbox GL JS v3 slots, as sMap slots. */
+const MAPBOX_SLOTS = { bottom: 'bottom', middle: 'labels', top: 'top' };
+
+function pick(o, keys, inside) {
+  const out = {};
+  Object.keys(o || {}).forEach(function (k) { if ((keys.indexOf(k) >= 0) === inside) { out[k] = o[k]; } });
+  return out;
+}
+
+function sdkCall(sdk, name) {
+  if (typeof sdk[name] !== 'function') { throw new Error('sMap: the adapter needs @superrouteca/smap 1.1.0 or later (' + name + ')'); }
+  return sdk[name];
+}
+
+/**
+ * A Mapbox GL JS `transformRequest` for sMap: sMap URLs go to the node requests go to now and carry the token (renewed
+ * through getToken) and the map key; every other URL is passed on unchanged (or to your own `next(url, type)`).
+ */
+export function smapTransformRequest(access, next) {
+  return function (url, resourceType) {
+    if (!access.isOurs(url)) { return next ? next(url, resourceType) : { url: url }; }
+    const to = access.rewrite(url);
+    return { url: to, headers: access.headers(to) };
+  };
+}
+
+/** The sMap badge as a Mapbox GL JS control. */
+export class SMapBadgeControl {
+  onAdd(map) {
+    this._el = createBadge(map.getContainer().ownerDocument);
+    this._el.classList.add('mapboxgl-ctrl');
+    this._el.style.clear = 'both';
+    return this._el;
+  }
+  onRemove() { if (this._el && this._el.parentNode) { this._el.parentNode.removeChild(this._el); } this._el = null; }
+}
+
+/** The layer ids of a style that come from its basemap (all of them, for a style document of sMap's). */
+function idsOf(doc) { return ((doc && doc.layers) || []).map(function (l) { return l.id; }); }
+
+/**
+ * What is the app's in a live style: the sources and layers not in the basemap document, each layer with the basemap
+ * layer it stood under (to put it back at the same place in a new basemap).
+ */
+export function userPart(style, basemapDoc, extraBasemapLayers) {
+  const baseSources = Object.keys((basemapDoc && basemapDoc.sources) || {});
+  const baseLayers = idsOf(basemapDoc).concat(extraBasemapLayers || []);
+  const sources = {};
+  Object.keys((style && style.sources) || {}).forEach(function (id) { if (baseSources.indexOf(id) < 0) { sources[id] = style.sources[id]; } });
+  const layers = [];
+  const list = (style && style.layers) || [];
+  list.forEach(function (l, i) {
+    if (baseLayers.indexOf(l.id) >= 0) { return; }
+    let before = null;
+    for (let j = i + 1; j < list.length; j++) { if (baseLayers.indexOf(list[j].id) >= 0 && (extraBasemapLayers || []).indexOf(list[j].id) < 0) { before = list[j].id; break; } }
+    layers.push({ layer: l, before: before });
+  });
+  return { sources: sources, layers: layers };
+}
+
+/** A basemap document with the app's sources and layers put back in (each under the basemap layer it stood under). */
+export function mergeUserPart(doc, part) {
+  const out = Object.assign({}, doc, { sources: Object.assign({}, doc.sources, part.sources), layers: (doc.layers || []).slice() });
+  part.layers.forEach(function (x) {
+    const at = x.before ? out.layers.findIndex(function (l) { return l.id === x.before; }) : -1;
+    if (at >= 0) { out.layers.splice(at, 0, x.layer); } else { out.layers.push(x.layer); }
+  });
+  return out;
+}
+
+/** The style's sMap URLs moved onto the node requests go to now (sources, glyphs, sprite). */
+function onNode(doc, access) {
+  const out = JSON.parse(JSON.stringify(doc));
+  const move = function (u) { return typeof u === 'string' ? access.rewrite(u) : u; };
+  if (out.glyphs) { out.glyphs = move(out.glyphs); }
+  if (typeof out.sprite === 'string') { out.sprite = move(out.sprite); }
+  Object.keys(out.sources || {}).forEach(function (id) {
+    const s = out.sources[id];
+    if (s.url) { s.url = move(s.url); }
+    if (Array.isArray(s.tiles)) { s.tiles = s.tiles.map(move); }
+  });
+  return out;
+}
+
+/**
+ * sMap in Mapbox GL JS.
+ *
+ *   const smap = new SMapMapbox(mapboxgl, { container: 'map', apiKey: 'smk_…', style: 'light', language: 'en' });
+ *   await smap.ready;          // smap.map is the Mapbox GL JS map
+ *
+ * Options: the access options (apiKey, token, getToken, baseUrl, nodes, nearest), `style` (a scheme or
+ * `custom:<id>`), `language`, `basemap` (class overrides), `buildings3D` (true or { color, opacity }), `popup` /
+ * `popupLoading` / `autoZoom` for sMap's layers, and every Mapbox GL JS map option (container, center, zoom, pitch,
+ * bearing, …; `projection` is Web Mercator unless given). `map` instead of `container` attaches to a Mapbox GL JS map
+ * you made (see attach()).
+ */
+export class SMapMapbox {
+  constructor(mapboxgl, options) {
+    options = options || {};
+    if (!mapboxgl || (!mapboxgl.Map && !options.map)) { throw new Error('sMap: pass the Mapbox GL JS module: new SMapMapbox(mapboxgl, options)'); }
+    this.mapboxgl = mapboxgl;
+    this.access = options.access || new SMapAccess(pick(options, ACCESS_OPTIONS, true));
+    this._sdk = options.sdk || SDK;
+    this._style = checkStyle(options.style || 'light');
+    this._language = options.language || (typeof navigator !== 'undefined' && navigator.language) || 'en';
+    this._overrides = options.basemap || {};
+    this._buildings = options.buildings3D ? (options.buildings3D === true ? {} : options.buildings3D) : null;
+    this._overlayOptions = pick(options, ['popup', 'popupLoading', 'autoZoom'], true);
+    this._doc = null;        // the basemap document as served (before overrides)
+    this._shown = null;      // the basemap document as shown (overrides applied)
+    this._overlay = null;
+    this._queue = [];
+    this.map = null;
+    const self = this;
+    const mapOptions = pick(options, ACCESS_OPTIONS.concat(OWN_OPTIONS).concat(['map']), false);
+    this.ready = this.access.start()
+      .then(function () { return self._fetchDoc(); })
+      .then(function () {
+        if (options.map) { self._attachTo(options.map, options); } else { self._create(mapOptions); }
+        return new Promise(function (resolve) {
+          const done = function () { resolve(self); };
+          if (self.map.isStyleLoaded && self.map.isStyleLoaded()) { done(); } else { self.map.once('style.load', done); }
+        });
+      });
+  }
+
+  /** Attaches to a Mapbox GL JS map you made: its basemap becomes sMap's and its own layers stay (see switchBasemap). */
+  static attach(mapboxgl, map, options) { return new SMapMapbox(mapboxgl, Object.assign({}, options, { map: map })); }
+
+  _fetchDoc() {
+    const self = this;
+    return this.access.style(this._style, this._language).then(function (doc) { self._doc = doc; return doc; });
+  }
+
+  _shownDoc() {
+    const apply = sdkCall(this._sdk, 'applyBasemapOverrides');
+    const doc = onNode(apply(this._doc, this._overrides), this.access);
+    // 3D buildings are part of the basemap as shown, under its labels.
+    if (this._buildings && doc.sources && doc.sources[BASEMAP_SOURCE]) {
+      const anchors = typeof this._sdk.slotAnchors === 'function' ? this._sdk.slotAnchors(idsOf(doc)) : {};
+      const at = anchors.labels ? doc.layers.findIndex(function (l) { return l.id === anchors.labels; }) : -1;
+      doc.layers.splice(at >= 0 ? at : doc.layers.length, 0, this._buildingsLayer());
+    }
+    this._shown = doc;
+    return doc;
+  }
+
+  _create(mapOptions) {
+    const o = Object.assign({ projection: 'mercator' }, mapOptions, {
+      style: this._shownDoc(),
+      transformRequest: smapTransformRequest(this.access, mapOptions.transformRequest),
+    });
+    this.map = new this.mapboxgl.Map(o);
+    this._wire();
+  }
+
+  _attachTo(map, options) {
+    this.map = map;
+    // Without this adapter's transformRequest (it can only be given when the map is made) the map key reaches the
+    // tiles through the style's URLs; a token cannot.
+    if ((options.token || options.getToken) && typeof console !== 'undefined') {
+      console.warn('sMap: a map made without smapTransformRequest() cannot send tokens; make it with transformRequest: smapTransformRequest(access) or use a map key.');
+    }
+    const keep = options.keep;
+    const style = map.getStyle() || { sources: {}, layers: [] };
+    const part = userPart(style, { sources: {}, layers: [] });
+    part.sources = pick(part.sources, Object.keys(part.sources).filter(function (id) { return !isMapboxSource(style.sources[id]); }), true);
+    part.layers = part.layers.filter(function (x) {
+      if (keep) { return keep(x.layer); }
+      if (!x.layer.source) { return false; }   // background, sky: the old basemap's
+      return typeof x.layer.source === 'object' || !!part.sources[x.layer.source];
+    }).map(function (x) { return { layer: x.layer, before: null }; });
+    map.setStyle(mergeUserPart(this._shownDoc(), part));
+    this._wire();
+  }
+
+  _wire() {
+    const map = this.map;
+    const self = this;
+    if (map.addControl) { this._badge = new SMapBadgeControl(); map.addControl(this._badge, 'bottom-right'); }
+    // A tile or style request to a node that failed: that node is tried last from now on.
+    map.on('error', function (e) {
+      const err = e && e.error;
+      const url = err && (err.url || (err.message && (/https?:\/\/\S+/.exec(err.message) || [])[0]));
+      const status = err && err.status;
+      if (url && self.access.isOurs(url) && (!status || status >= 500)) { self.access.failed(url); }
+    });
+    ['move', 'resize'].forEach(function (type) { map.on(type, function () { self._syncOverlay(type); }); });
+    ['click', 'dblclick', 'contextmenu', 'mousemove', 'mouseout'].forEach(function (type) {
+      map.on(type, function (e) {
+        if (!self._overlay || !e || !e.point) { return; }
+        if (self._overlay.inPopup(e.originalEvent)) { return; }
+        self._overlay.forward(type, e.point.x, e.point.y, { lng: e.lngLat.lng, lat: e.lngLat.lat }, e.originalEvent);
+      });
+    });
+  }
+
+  /** Sets the basemap again, keeping the app's sources and layers where they were. */
+  _restyle() {
+    const map = this.map;
+    const part = userPart(map.getStyle(), this._shown);
+    const doc = mergeUserPart(this._shownDoc(), part);
+    map.setStyle(doc, { diff: true });
+  }
+
+  _whenReady(fn) { const self = this; return this.ready.then(function () { return fn.call(self); }); }
+
+  /** Switches to a scheme or `custom:<id>`; the app's layers and sMap's layers stay. */
+  setStyle(style) {
+    this._style = checkStyle(style);
+    const self = this;
+    this._pending = this._whenReady(function () { return self._fetchDoc().then(function () { self._restyle(); }); });
+    return this;
+  }
+
+  /** Switches the label language; the app's layers and sMap's layers stay. */
+  setLanguage(language) {
+    this._language = language;
+    const self = this;
+    this._pending = this._whenReady(function () { return self._fetchDoc().then(function () { self._restyle(); }); });
+    return this;
+  }
+
+  /** Shows, hides and recolours the basemap by class (contract §1); replaces the previous overrides ({} clears). */
+  setBasemap(overrides) {
+    // Checked now (an unknown class or field throws here, not later).
+    sdkCall(this._sdk, 'applyBasemapOverrides')({ layers: [] }, overrides || {});
+    this._overrides = overrides || {};
+    const self = this;
+    this._pending = this._whenReady(function () { self._restyle(); });
+    return this;
+  }
+
+  /** The basemap overrides in force. */
+  basemap() { return JSON.parse(JSON.stringify(this._overrides)); }
+
+  /** 3D buildings from the basemap's buildings (Mapbox GL JS draws them; the map tilts to show them). */
+  setBuildings3D(on, options) {
+    this._buildings = on ? (options || {}) : null;
+    const self = this;
+    this._whenReady(function () {
+      self._restyle();
+      if (on && self.map.getPitch && self.map.getPitch() < 30) { self.map.easeTo({ pitch: 55, duration: 800 }); }
+    });
+    return this;
+  }
+
+  _buildingsLayer() {
+    const o = this._buildings || {};
+    const dark = this._style === 'dark' || this._style === 'black';
+    return {
+      id: BUILDINGS_LAYER,
+      type: 'fill-extrusion',
+      source: BASEMAP_SOURCE,
+      'source-layer': 'buildings',
+      minzoom: 13,
+      paint: {
+        'fill-extrusion-color': o.color || (dark ? '#3b4252' : '#d9dee7'),
+        'fill-extrusion-height': ['coalesce', ['get', 'height'], 8],
+        'fill-extrusion-base': ['coalesce', ['get', 'min_height'], 0],
+        'fill-extrusion-opacity': o.opacity !== undefined ? o.opacity : 0.85,
+      },
+    };
+  }
+
+  /** Where a slot begins in the basemap now (a layer id to add before; undefined for `top`). */
+  slotLayer(slot) {
+    if (!slot) { return undefined; }
+    const anchors = sdkCall(this._sdk, 'slotAnchors')(idsOf(this._shown));
+    return anchors[slot];
+  }
+
+  /** Adds a Style Specification v8 source to the Mapbox GL JS map (kept across style and language changes). */
+  addSource(id, source) { const self = this; this._whenReady(function () { self.map.addSource(id, source); }); return this; }
+
+  /** Removes a source and the layers that read it. */
+  removeSource(id) {
+    const self = this;
+    this._whenReady(function () {
+      (self.map.getStyle().layers || []).forEach(function (l) { if (l.source === id) { self.map.removeLayer(l.id); } });
+      if (self.map.getSource(id)) { self.map.removeSource(id); }
+    });
+    return this;
+  }
+
+  /**
+   * Adds a Style Specification v8 layer to the Mapbox GL JS map as it is: under `before`, at a slot (`bottom`,
+   * `roads`, `labels`, `top`, or Mapbox's own `middle`), or on top when neither is given.
+   */
+  addStyleLayer(layer, placement) {
+    const p = placement || {};
+    const self = this;
+    this._whenReady(function () {
+      const slot = p.slot || (layer.slot && MAPBOX_SLOTS[layer.slot]);
+      const before = p.before || self.slotLayer(MAPBOX_SLOTS[slot] || slot);
+      const copy = Object.assign({}, layer);
+      delete copy.slot;   // a Mapbox slot of the sMap basemap is resolved here, not by Mapbox GL JS
+      self.map.addLayer(copy, before && self.map.getLayer(before) ? before : undefined);
+    });
+    return this;
+  }
+
+  setPaint(id, name, value) { const self = this; this._whenReady(function () { self.map.setPaintProperty(id, name, value); }); return this; }
+  setLayout(id, name, value) { const self = this; this._whenReady(function () { self.map.setLayoutProperty(id, name, value); }); return this; }
+  setFilter(id, filter) { const self = this; this._whenReady(function () { self.map.setFilter(id, filter); }); return this; }
+
+  /** Raster tiles (XYZ templates or a TileJSON address) as a Mapbox GL JS raster source and layer. */
+  addRasterLayer(id, o) {
+    o = o || {};
+    const source = { type: 'raster', tileSize: o.tileSize || 256 };
+    if (o.tiles) { source.tiles = Array.isArray(o.tiles) ? o.tiles : [o.tiles]; }
+    else if (o.url && /\{z\}/.test(o.url)) { source.tiles = [o.url]; }
+    else if (o.url) { source.url = o.url; }
+    ['attribution', 'minzoom', 'maxzoom', 'bounds', 'scheme'].forEach(function (k) { if (o[k] !== undefined) { source[k] = o[k]; } });
+    const layer = { id: id, type: 'raster', source: id, paint: {} };
+    if (o.opacity !== undefined) { layer.paint['raster-opacity'] = o.opacity; }
+    return this.addSource(id, source).addStyleLayer(layer, { slot: o.slot, before: o.before });
+  }
+
+  /** Vector tiles (templates or a TileJSON address) drawn by your Style Specification layers. */
+  addVectorTiles(id, o) {
+    o = o || {};
+    const source = { type: 'vector' };
+    if (o.tiles) { source.tiles = Array.isArray(o.tiles) ? o.tiles : [o.tiles]; } else if (o.url) { source.url = o.url; }
+    ['attribution', 'minzoom', 'maxzoom', 'bounds', 'promoteId'].forEach(function (k) { if (o[k] !== undefined) { source[k] = o[k]; } });
+    this.addSource(id, source);
+    const self = this;
+    (o.layers || []).forEach(function (l) { self.addStyleLayer(Object.assign({ source: id }, l), { slot: o.slot, before: o.before }); });
+    return this;
+  }
+
+  // ---------------------------------------------------------------- sMap's own layers (the overlay)
+
+  /**
+   * The sMap map drawing sMap's own layers (pins, lines, areas, popups, Auto Zoom, files, WMS / WMTS / ArcGIS
+   * layers) above the Mapbox GL JS map, following its camera; made on first use. Resolves to the sMap map.
+   */
+  overlay() {
+    const self = this;
+    return this.ready.then(function () {
+      if (self._overlay) { return self._overlay.ready; }
+      const map = self.map;
+      const container = map.getContainer();
+      injectCss(container.ownerDocument);
+      const el = container.ownerDocument.createElement('div');
+      el.className = 'smap-mapbox-overlay';
+      el.style.width = '100%';
+      el.style.height = '100%';
+      const controls = container.querySelector && container.querySelector('.mapboxgl-control-container');
+      if (controls) { container.insertBefore(el, controls); } else { container.appendChild(el); }
+      const head = self.access.head();
+      const c = map.getCenter();
+      self._overlay = createEmbedded(self._sdk, el, Object.assign({}, self._overlayOptions, {
+        // An empty style: no basemap of its own, the basemap's glyphs for labels; its own requests go to the node
+        // the Mapbox GL JS map reads from, with the same key and token.
+        style: { version: 8, glyphs: (self._shown && self._shown.glyphs) || head + '/v1/fonts/{fontstack}/{range}', sources: {}, layers: [] },
+        baseUrl: head,
+        nearest: false,
+        apiKey: self.access.apiKey || undefined,
+        token: self.access.token() || undefined,
+        getToken: self.access._getToken ? function () { return self.access.refresh(); } : undefined,
+        center: [c.lng, c.lat],
+        zoom: map.getZoom(),
+        bearing: map.getBearing(),
+        pitch: map.getPitch(),
+      }), {
+        move: function (t, how) {
+          const cam = { center: [t.center.lng, t.center.lat], zoom: t.zoom, bearing: t.bearing, pitch: t.pitch };
+          if (!how.animate) { map.jumpTo(cam); return; }
+          if (how.duration !== undefined) { cam.duration = how.duration; }
+          map[how.fly ? 'flyTo' : 'easeTo'](cam);
+        },
+        cursor: function (cursor) { map.getCanvas().style.cursor = cursor; },
+        attribution: function (list) { self._overlayCredits(list); },
+      });
+      return self._overlay.ready.then(function (m) { self._syncOverlay(); return m; });
+    });
+  }
+
+  _syncOverlay(type) {
+    if (!this._overlay) { return; }
+    if (type === 'resize') { this._overlay.resize(); }
+    const map = this.map;
+    const c = map.getCenter();
+    this._overlay.sync({ center: { lng: c.lng, lat: c.lat }, zoom: map.getZoom(), bearing: map.getBearing(), pitch: map.getPitch() });
+  }
+
+  // Credits of layers drawn by the overlay (beyond the data credit, which the basemap's own source carries) are
+  // added to the Mapbox GL JS attribution through a hidden source.
+  _overlayCredits(list) {
+    const map = this.map;
+    const extra = list.slice(1).join(' | ');
+    const id = 'smap-overlay-credits';
+    if (map.getLayer(id)) { map.removeLayer(id); }
+    if (map.getSource(id)) { map.removeSource(id); }
+    // An empty source a layer reads: the attribution control shows the credits of sources in use only.
+    if (extra) {
+      map.addSource(id, { type: 'geojson', data: { type: 'FeatureCollection', features: [] }, attribution: extra });
+      map.addLayer({ id: id, type: 'circle', source: id });
+    }
+  }
+
+  /** An sMap map call on the overlay, resolving to its answer. */
+  call(name) {
+    const args = Array.prototype.slice.call(arguments, 1);
+    return this.overlay().then(function (m) {
+      if (typeof m[name] !== 'function') { throw new Error('sMap: this version of @superrouteca/smap has no ' + name + '()'); }
+      return m[name].apply(m, args);
+    });
+  }
+
+  /** Removes the Mapbox GL JS map and the overlay. */
+  remove() {
+    this.access.stop();
+    if (this._overlay) { this._overlay.remove(); this._overlay = null; }
+    if (this.map) { this.map.remove(); }
+  }
+}
+
+/** sMap map calls made on the overlay (each returns the SMapMapbox). */
+export const OVERLAY_CALLS = ['addPoints', 'addLines', 'addPolygons', 'addData', 'setData', 'setVisible', 'removeLayer', 'fitLayer',
+  'openPopup', 'closePopup', 'setAutoZoom', 'addWmsLayer', 'addWmtsLayer', 'addArcGisLayer', 'addDeckLayer', 'removeDeckLayer', 'loadLayers'];
+
+OVERLAY_CALLS.forEach(function (name) {
+  SMapMapbox.prototype[name] = function () {
+    const args = Array.prototype.slice.call(arguments);
+    this.call.apply(this, [name].concat(args)).catch(function (e) { if (typeof console !== 'undefined') { console.error(e); } });
+    return this;
+  };
+});
+
+function isMapboxSource(s) {
+  if (!s) { return false; }
+  const urls = [s.url].concat(s.tiles || []).filter(Boolean);
+  return urls.some(function (u) { return /^mapbox:\/\//.test(u) || /(^|\.)mapbox\.com\//.test(u.replace(/^https?:\/\//, '')); });
+}
+
+/**
+ * Switches an existing Mapbox GL JS map's basemap to sMap without touching its own layers: the old basemap (Mapbox
+ * sources and the layers reading them, background, sky) goes, every other source and layer stays.
+ * `keep(layer)` decides instead which layers stay. Resolves to the SMapMapbox.
+ */
+export function switchBasemap(mapboxgl, map, options) { return SMapMapbox.attach(mapboxgl, map, options).ready; }
+
+/** Creates sMap in Mapbox GL JS; resolves once the style has loaded. */
+export function createMap(mapboxgl, options) { return new SMapMapbox(mapboxgl, options).ready; }
+
+/** The service access (key or token, nearest node), to share with smapTransformRequest(). */
+export function smapAccess(options) { return new SMapAccess(options); }
+
+export { isMapboxSource, OSM_ATTRIBUTION as attribution };
+
+const SMapMapboxModule = { version, styles: FLAVORS, SMapMapbox, createMap, switchBasemap, smapAccess, smapTransformRequest, SMapBadgeControl, SMapAccess, checkStyle, rasterPath };
+export default SMapMapboxModule;