@superrouteca/smap-deckgl 0.0.0-stage → 1.1.1

package/src/layers.js

@@ -0,0 +1,227 @@
+// sMap's points, pins, lines and areas as deck.gl layers, with the options of the sMap SDK's addPoints / addLines /
+// addPolygons, so a layer looks the same on a deck.gl-only map as on an sMap map. GeoJSON simplestyle properties
+// (marker-color, stroke, fill, …) colour a layer that gives no colour of its own, as on an sMap map.
+import { ScatterplotLayer, IconLayer, TextLayer, PathLayer, GeoJsonLayer } from '@deck.gl/layers';
+import { parseColor, evaluate } from './style.js';
+
+const GEOMETRY_TYPES = ['Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', 'MultiPolygon', 'GeometryCollection'];
+
+/** sMap layer data (a FeatureCollection, a Feature, a geometry, or an array of points / features) as features. */
+export function toFeatures(data) {
+  if (!data) { return []; }
+  if (data.type === 'FeatureCollection') { return data.features || []; }
+  if (data.type === 'Feature') { return [data]; }
+  if (GEOMETRY_TYPES.includes(data.type)) { return [{ type: 'Feature', properties: {}, geometry: data }]; }
+  if (Array.isArray(data)) {
+    return data.map((p) => {
+      if (p && p.type === 'Feature') { return p; }
+      let lng = p.lng ?? p.lon ?? p.longitude;
+      let lat = p.lat ?? p.latitude;
+      if (p.coordinates) { [lng, lat] = p.coordinates; }
+      return { type: 'Feature', id: p.id, properties: p, geometry: { type: 'Point', coordinates: [lng, lat] } };
+    });
+  }
+  return [];
+}
+
+/** A per-feature accessor for an sMap style value (a constant, `{ property, default }`, or an expression). */
+export function accessor(value, fallback, simplestyleKey) {
+  const read = (f) => {
+    let v;
+    if (value === undefined || value === null) {
+      v = simplestyleKey && f.properties ? f.properties[simplestyleKey] : undefined;
+    } else if (Array.isArray(value)) {
+      v = evaluate(value, f, 0);
+    } else if (typeof value === 'object' && value.property) {
+      v = f.properties ? f.properties[value.property] : undefined;
+      if (v === undefined || v === null) { v = value.default; }
+    } else {
+      v = value;
+    }
+    return v === undefined || v === null ? fallback : v;
+  };
+  return read;
+}
+
+const colorOf = (get, opacity = 1) => (f) => {
+  const c = parseColor(get(f)) || [0, 0, 0, 255];
+  const o = typeof opacity === 'function' ? opacity(f) : opacity;
+  return [c[0], c[1], c[2], Math.round(c[3] * (o ?? 1))];
+};
+
+const PIN_H = 42 / 32;
+
+function pinSvg(shape, fill, border, borderWidth) {
+  const w = Math.max(0.5, borderWidth);
+  const body = shape === 'circle' || shape === 'vehicle'
+    ? '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 32 32"><circle cx="16" cy="16" r="' + (15 - w / 2) + '" fill="' + fill + '" stroke="' + border + '" stroke-width="' + w + '"/></svg>'
+    : '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="84" viewBox="0 0 32 42"><path d="M16 40.5C16 40.5 2.5 25 2.5 15.5a13.5 13.5 0 1 1 27 0C29.5 25 16 40.5 16 40.5Z" fill="' + fill + '" stroke="' + border + '" stroke-width="' + w + '" stroke-linejoin="round"/></svg>';
+  return 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(body);
+}
+
+const registry = new Map();
+
+function remember(layer, options) {
+  if (options && options.popup) { registry.set(layer.id, options.popup); }
+  return layer;
+}
+
+/**
+ * Points as deck.gl layers: circles (`color`, `radius`, `strokeColor`, `strokeWidth`), an `icon`, or route-map pins
+ * (`marker: { shape, fill, border, borderWidth, size, text, textColor, opacity }`), with a `label` under each.
+ *
+ * @returns {object[]} deck.gl layers, bottom first
+ */
+export function pointsLayers(id, data, options = {}) {
+  const features = toFeatures(data);
+  const out = [];
+  const pos = (f) => f.geometry.coordinates;
+  const pickable = Boolean(options.popup || options.onClick || options.pickable);
+  const onClick = options.onClick ? (info, event) => options.onClick(info.object, info, event) : undefined;
+  const mk = options.marker;
+  if (mk) {
+    const size = mk.size || 32;
+    const shape = mk.shape || 'pin';
+    const color = accessor(options.color, '#2563eb', 'marker-color');
+    const fill = accessor(mk.fill, '#ffffff');
+    const border = accessor(mk.border, undefined);
+    const opacity = accessor(mk.opacity, 1);
+    out.push(remember(new IconLayer({
+      id, data: features, pickable, onClick,
+      getPosition: pos,
+      getIcon: (f) => {
+        const b = border(f) ?? color(f);
+        const url = pinSvg(shape, fill(f), b, mk.borderWidth ?? 3);
+        const round = shape !== 'pin';
+        return { id: shape + '|' + fill(f) + '|' + b, url, width: 64, height: round ? 64 : 84, anchorY: round ? 32 : 84, mask: false };
+      },
+      getSize: shape === 'pin' ? size * PIN_H : size,
+      sizeUnits: 'pixels',
+      opacity: typeof mk.opacity === 'number' ? mk.opacity : 1,
+      getColor: (f) => [255, 255, 255, Math.round(255 * opacity(f))],
+    }), options));
+    if (mk.text !== undefined) {
+      const text = accessor(mk.text, '');
+      const textColor = accessor(mk.textColor, '#ffffff');
+      out.push(new TextLayer({
+        id: id + '-text', data: features.filter((f) => text(f) !== '' && text(f) !== null),
+        getPosition: pos, getText: (f) => String(text(f)), getColor: colorOf(textColor), getSize: Math.round(size * 0.42),
+        sizeUnits: 'pixels', characterSet: 'auto', fontWeight: 700,
+        getPixelOffset: shape === 'pin' ? [0, -Math.round(size * PIN_H - size / 2)] : [0, 0],
+        fontFamily: options.fontFamily || 'Helvetica, Arial, sans-serif',
+      }));
+    }
+  } else if (options.icon) {
+    const s = options.iconSize || 1;
+    out.push(remember(new IconLayer({
+      id, data: features, pickable, onClick, getPosition: pos, sizeUnits: 'pixels', getSize: 32 * s,
+      getIcon: () => ({ id: options.icon, url: options.icon, width: 64, height: 64, anchorY: options.iconAnchor === 'bottom' ? 64 : 32 }),
+    }), options));
+  } else {
+    const color = accessor(options.color, '#2563eb', 'marker-color');
+    const sizes = { small: 5, medium: 7, large: 10 };
+    const radius = options.radius !== undefined ? () => options.radius
+      : (f) => sizes[(f.properties || {})['marker-size']] || 6;
+    out.push(remember(new ScatterplotLayer({
+      id, data: features, pickable, onClick, getPosition: pos,
+      radiusUnits: 'pixels', getRadius: radius,
+      getFillColor: colorOf(color), stroked: true, lineWidthUnits: 'pixels',
+      getLineColor: colorOf(accessor(options.strokeColor, '#ffffff')), getLineWidth: options.strokeWidth ?? 2,
+    }), options));
+  }
+  if (options.label) {
+    const right = options.labelPosition === 'right';
+    out.push(new TextLayer({
+      id: id + '-label', data: features.filter((f) => f.properties && f.properties[options.label] != null),
+      getPosition: pos, getText: (f) => String(f.properties[options.label]), getSize: 12, sizeUnits: 'pixels',
+      characterSet: 'auto', getColor: [51, 51, 51, 255], fontSettings: { sdf: true }, outlineWidth: 2, outlineColor: [255, 255, 255, 255],
+      getTextAnchor: right ? 'start' : 'middle', getAlignmentBaseline: right ? 'center' : 'top',
+      getPixelOffset: right ? [12, 0] : [0, 10],
+    }));
+  }
+  return out;
+}
+
+function paths(f) {
+  const g = f.geometry;
+  if (g.type === 'LineString') { return [g.coordinates]; }
+  if (g.type === 'MultiLineString') { return g.coordinates; }
+  if (g.type === 'Polygon') { return g.coordinates; }
+  if (g.type === 'MultiPolygon') { return g.coordinates.flat(); }
+  return [];
+}
+
+/**
+ * Lines as deck.gl PathLayers: `color`, `width`, `opacity`, an optional `casing` and `shadow` under the line.
+ * (`dash` and `arrows` need deck.gl extensions and are not drawn.)
+ */
+export function linesLayers(id, data, options = {}) {
+  const rows = [];
+  for (const f of toFeatures(data)) { for (const p of paths(f)) { rows.push({ path: p, feature: f }); } }
+  const pickable = Boolean(options.popup || options.onClick || options.pickable);
+  const onClick = options.onClick ? (info, event) => options.onClick(info.object && info.object.feature, info, event) : undefined;
+  const color = accessor(options.color, '#2563eb', 'stroke');
+  const width = options.width ?? 4;
+  const strokeWidth = (r) => (options.width === undefined && r.feature.properties && r.feature.properties['stroke-width']) || width;
+  const out = [];
+  const under = (key, defaults) => {
+    const o = options[key];
+    if (!o) { return; }
+    const c = o === true ? {} : o;
+    const cColor = accessor(c.color, defaults.color);
+    out.push(new PathLayer({
+      id: id + '-' + key, data: rows, getPath: (r) => r.path, widthUnits: 'pixels', capRounded: true, jointRounded: true,
+      getWidth: c.width ?? defaults.width, getColor: (r) => colorOf(cColor, c.opacity ?? defaults.opacity)(r.feature),
+    }));
+  };
+  under('casing', { color: '#ffffff', width: Math.max(9, width + 4), opacity: 1 });
+  under('shadow', { color: '#000000', width: Math.max(7, width + 2), opacity: 0.3 });
+  const opacity = options.opacity ?? null;
+  out.push(remember(new PathLayer({
+    id, data: rows, pickable, onClick, getPath: (r) => r.path, widthUnits: 'pixels', capRounded: true, jointRounded: true,
+    getWidth: strokeWidth,
+    getColor: (r) => colorOf(color, opacity ?? ((r.feature.properties || {})['stroke-opacity'] ?? 1))(r.feature),
+  }), options));
+  return out;
+}
+
+/**
+ * Areas as a deck.gl GeoJsonLayer: `fill` (or `color`), `opacity`, `outline`, `outlineWidth`, and `extrude`
+ * (`{ height, base }` in metres, a number or a property name) for 3D.
+ */
+export function polygonsLayers(id, data, options = {}) {
+  const features = toFeatures(data).filter((f) => f.geometry && /Polygon$/.test(f.geometry.type));
+  const pickable = Boolean(options.popup || options.onClick || options.pickable);
+  const onClick = options.onClick ? (info, event) => options.onClick(info.object, info, event) : undefined;
+  const fill = accessor(options.fill ?? options.color, '#2563eb', 'fill');
+  const outline = accessor(options.outline, undefined, 'stroke');
+  const opacity = options.opacity ?? null;
+  const num = (v, f) => (typeof v === 'string' ? Number((f.properties || {})[v]) || 0 : Number(v) || 0);
+  const ex = options.extrude;
+  return [remember(new GeoJsonLayer({
+    id, data: features, pickable, onClick,
+    filled: true, stroked: true, lineWidthUnits: 'pixels',
+    getFillColor: (f) => colorOf(fill, opacity ?? ((f.properties || {})['fill-opacity'] ?? (ex ? 0.9 : 0.3)))(f),
+    getLineColor: (f) => colorOf((g) => outline(g) ?? fill(g))(f),
+    getLineWidth: options.outlineWidth ?? 1,
+    extruded: Boolean(ex),
+    getElevation: ex ? (f) => Math.max(0, num(ex.height ?? 0, f) - num(ex.base ?? 0, f)) : 0,
+  }), options)];
+}
+
+/**
+ * A deck.gl `getTooltip` that shows the `popup` of the layer under the pointer (the layers made by pointsLayers,
+ * linesLayers and polygonsLayers with a `popup` option). Popups returning a promise or a DOM node are not shown here;
+ * on an sMap map use the map's own popups instead.
+ */
+export function popupTooltip(fallback) {
+  return (info) => {
+    const fn = info && info.layer ? registry.get(info.layer.id) : null;
+    if (fn && info.object) {
+      const feature = info.object.feature || info.object;
+      const html = fn(feature.properties || {}, feature);
+      if (typeof html === 'string' && html) { return { html, className: 'smap-deck-popup' }; }
+    }
+    return fallback ? fallback(info) : null;
+  };
+}

package/src/overlay.js

@@ -0,0 +1,133 @@
+// deck.gl and an sMap map together, through the map's own deck.gl overlay (addDeckLayer of @superrouteca/smap 1.1.0:
+// deck.gl's MapboxOverlay, interleaved with the basemap; one overlay per map).
+//  - createSMapDeck: a deck.gl app whose basemap is an sMap map, with deck.gl's own props (getTooltip, onClick, …).
+//  - deckLayers: deck.gl layers on an existing sMap map, kept by id, placed by slot or before a layer.
+import * as deckMapbox from '@deck.gl/mapbox';
+import { useDeck } from '@superrouteca/smap';
+import { ATTRIBUTION } from './session.js';
+
+// Options of createSMapDeck itself; every other option is the sMap map's.
+const OWN_OPTIONS = ['deck', 'layers', 'sMap'];
+
+let registered = null;
+/** Hands deck.gl's map overlay module to the SDK once (its addDeckLayer draws through it). */
+export function registerDeck(sMap) {
+  const use = (sMap && sMap.useDeck) || useDeck;
+  if (registered !== use) { use(deckMapbox); registered = use; }
+}
+
+/**
+ * An sMap map with deck.gl drawn interleaved with the basemap (deck.gl layers between sMap's layers and sharing its
+ * depth, so 3D buildings and deck.gl columns hide each other correctly).
+ *
+ * @param {object} options  sMap map options (container, apiKey / token / getToken, style, language, center, zoom, …),
+ *                          plus `layers` (deck.gl layers), `deck` (other deck.gl props of the overlay: getTooltip,
+ *                          onClick, pickingRadius, …) and `sMap` (the @superrouteca/smap module; imported when not given).
+ * @returns {Promise<{ map, overlay, setLayers(layers), setProps(props), remove() }>}
+ */
+export async function createSMapDeck(options = {}) {
+  const sMap = options.sMap || await import('@superrouteca/smap');
+  registerDeck(sMap);
+  const mapOptions = {};
+  for (const k of Object.keys(options)) {
+    if (!OWN_OPTIONS.includes(k)) { mapOptions[k] = options[k]; }
+  }
+  const map = new sMap.Map(mapOptions);
+  await map.ready;
+  const { layers: deckPropLayers, ...deckProps } = options.deck || {};
+  const layers = deckLayers(map);
+  layers.set(options.layers || deckPropLayers || []);
+  // The overlay is the map's own (deckOverlay of @superrouteca/smap 1.1.0); its other props (tooltips, clicks) are
+  // deck.gl's own.
+  const overlay = () => map.deckOverlay();
+  const applyProps = (props) => {
+    if (!Object.keys(props).length) { return; }
+    map.deckOverlay(props);
+  };
+  applyProps(deckProps);
+  return {
+    map,
+    get overlay() { return overlay(); },
+    layers,
+    setLayers(next) { layers.set(next); return this; },
+    setProps(props) {
+      const { layers: l, ...rest } = props || {};
+      if (l) { layers.set(l); }
+      applyProps(rest);
+      return this;
+    },
+    pickObject(opts) { return overlay() ? overlay().pickObject(opts) : null; },
+    remove() { layers.clear(); map.remove(); },
+  };
+}
+
+/**
+ * deck.gl layers on an sMap map, kept by id: `add` replaces a layer of the same id (deck.gl's way of updating a
+ * layer: make a new one with the same id), `set` replaces them all. Builds on the map's addDeckLayer /
+ * removeDeckLayer; `placement` is the map's `{ slot, before }` (a layer without one draws on top, as added).
+ *
+ * @param {object} map  an sMap map (1.1.0 or later)
+ */
+export function deckLayers(map) {
+  if (!map || typeof map.addDeckLayer !== 'function') {
+    throw new Error('sMap: this map has no addDeckLayer (needs @superrouteca/smap 1.1.0 or later)');
+  }
+  registerDeck();
+  const current = new Map();
+  const api = {
+    add(layers, placement) {
+      for (const layer of [].concat(layers).flat()) {
+        if (!layer) { continue; }
+        if (placement && (placement.slot || placement.before)) { map.addDeckLayer(layer, placement); } else { map.addDeckLayer(layer); }
+        current.set(layer.id, layer);
+      }
+      return api;
+    },
+    remove(...ids) {
+      for (const id of ids.flat()) {
+        if (current.has(id)) { map.removeDeckLayer(id); current.delete(id); }
+      }
+      return api;
+    },
+    set(layers, placement) {
+      const next = new Set([].concat(layers || []).flat().filter(Boolean).map((l) => l.id));
+      for (const id of [...current.keys()]) { if (!next.has(id)) { api.remove(id); } }
+      return api.add(layers || [], placement);
+    },
+    get(id) { return current.get(id) || null; },
+    ids() { return [...current.keys()]; },
+    clear() { return api.remove([...current.keys()]); },
+  };
+  return api;
+}
+
+const BADGE_ICON = '<svg viewBox="0 0 56 56" width="14" height="14" aria-hidden="true" focusable="false">' +
+  '<rect x="2" y="2" width="52" height="52" rx="13" fill="#2563eb"/>' +
+  '<path d="M38 15H22a8 8 0 0 0 0 16h12a8 8 0 0 1 0 16H18" fill="none" stroke="#fff" stroke-width="7" ' +
+  'stroke-linecap="round" stroke-linejoin="round"/></svg>';
+
+/**
+ * The sMap badge and the data credit in the bottom-right corner of a deck.gl canvas's container (for the deck.gl-only
+ * basemap, which has no attribution control of its own). Returns the element; `remove()` takes it away.
+ *
+ * @param {HTMLElement} container  the element deck.gl draws in (position: relative or absolute)
+ * @param {{ attribution?: string|string[] }} [options]  credits of other sources, shown after the OpenStreetMap one
+ */
+export function addAttribution(container, options = {}) {
+  const doc = container.ownerDocument;
+  const el = doc.createElement('div');
+  el.className = 'smap-deck-attribution';
+  el.setAttribute('style', 'position:absolute;right:0;bottom:0;z-index:1;display:flex;gap:6px;align-items:center;' +
+    'padding:2px 6px;background:rgba(255,255,255,.75);font:11px/16px Helvetica,Arial,sans-serif;color:#333;pointer-events:auto');
+  const badge = doc.createElement('span');
+  badge.className = 'smap-badge';
+  badge.setAttribute('style', 'display:inline-flex;gap:3px;align-items:center;font-weight:600');
+  badge.innerHTML = BADGE_ICON + '<span>sMap</span>';
+  const credit = doc.createElement('span');
+  const extra = [].concat(options.attribution || []).filter((a) => a && a !== ATTRIBUTION);
+  credit.textContent = [ATTRIBUTION, ...extra].join(' | ');
+  el.appendChild(badge);
+  el.appendChild(credit);
+  container.appendChild(el);
+  return el;
+}

package/src/session.js

@@ -0,0 +1,198 @@
+// One connection to sMap for a tool adapter: the JS client of @superrouteca/smap (nearest node, failover, map key,
+// token and its refresh) plus the URLs a tool needs on the node read from now (built by the SDK's styleUrl, rasterUrl
+// and rasterTileJsonUrl) and the headers a tool's own requests carry. The node, key, token and URL logic is the
+// SDK's; this file only asks it.
+//
+// The same file is used by @superrouteca/smap-deckgl, -arcgis and -cesium.
+import SMapClient from '@superrouteca/smap/client';
+import { styleUrl as sdkStyleUrl, rasterUrl as sdkRasterUrl, rasterTileJsonUrl as sdkRasterTileJsonUrl } from '@superrouteca/smap';
+
+export const FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
+export const ATTRIBUTION = '© OpenStreetMap contributors';
+export const DEFAULT_BASE = 'https://tile.srsr.ca';
+
+const strip = (u) => String(u).replace(/\/+$/, '');
+
+/** `light` → `light`; `custom:sms_…` → `custom:sms_…`; anything else is refused with a message naming it. */
+export function checkStyle(style) {
+  const s = style == null ? 'light' : String(style);
+  if (FLAVORS.includes(s)) { return s; }
+  if (/^custom:[A-Za-z0-9_-]+$/.test(s)) { return s; }
+  throw new Error('sMap: unknown style "' + s + '" (one of ' + FLAVORS.join(', ') + ', or custom:<id>)');
+}
+
+function addQuery(url, params) {
+  const parts = [];
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null && v !== '') { parts.push(k + '=' + encodeURIComponent(v)); }
+  }
+  return parts.length ? url + (url.includes('?') ? '&' : '?') + parts.join('&') : url;
+}
+
+export class Session {
+  /**
+   * @param {object} options  the JS client's options (baseUrl, apiKey, token, getToken, nodes, nearest, fetch,
+   *                          timeoutMs), or `{ client }` with a client of your own. `baseUrl` defaults to tile.srsr.ca.
+   */
+  constructor(options = {}) {
+    if (options instanceof Session) { return options; }
+    this.client = options.client || new SMapClient({ ...options, baseUrl: options.baseUrl || DEFAULT_BASE });
+    this.baseUrl = this.client.baseUrl;
+    this.apiKey = options.apiKey || (options.client && options.client.apiKey) || null;
+    this._seeds = (options.nodes || []).map(strip);
+    this._order = [this.baseUrl];
+    this._token = options.token || null;
+    this._listeners = { nodechange: [], token: [] };
+    this._timer = null;
+    this._ready = null;
+    this._closed = false;
+  }
+
+  /** Resolves once the nearest node is known and a token (where one is used) is at hand. */
+  ready() {
+    if (!this._ready) {
+      this._ready = Promise.all([this.client.nodes(), this.client.token()]).then(([nodes, token]) => {
+        this._order = nodes && nodes.length ? nodes.slice() : [this.baseUrl];
+        this._setToken(token);
+        return this;
+      });
+    }
+    return this._ready;
+  }
+
+  /** The node read from now: the nearest one that has not failed. */
+  node() { return this._order[0] || this.baseUrl; }
+
+  /** Every node in the order they are tried. */
+  nodes() { return this._order.slice(); }
+
+  /** The token sent now (kept fresh in the background), or null. */
+  token() { return this._token; }
+
+  _setToken(token) {
+    const changed = token !== this._token;
+    this._token = token || null;
+    if (changed) { this._emit('token', this._token); }
+    this._schedule();
+  }
+
+  // The client renews a token two minutes before it expires; the adapters read it synchronously (request hooks and
+  // tile URLs cannot wait), so it is asked again shortly before that moment.
+  _schedule() {
+    clearTimeout(this._timer);
+    if (this._closed || !this._token || !this.client.renewsToken) { return; }
+    const exp = SMapClient.tokenExpiry(this._token);
+    if (!exp) { return; }
+    const wait = Math.max(5, exp - Math.floor(Date.now() / 1000) - 110) * 1000;
+    this._timer = setTimeout(() => {
+      this.client.token().then((t) => this._setToken(t), () => { this._timer = setTimeout(() => this._schedule(), 30000); });
+    }, Math.min(wait, 2147483000));
+    if (this._timer && this._timer.unref) { this._timer.unref(); }
+  }
+
+  /** The headers a request to sMap carries: the token and the map key. */
+  headers() {
+    const h = {};
+    if (this._token) { h.Authorization = 'Bearer ' + this._token; }
+    if (this.apiKey) { h['X-SMap-Key'] = this.apiKey; }
+    return h;
+  }
+
+  /** Every address requests to sMap may go to (base, seeds, measured nodes). */
+  origins() { return [...new Set([this.baseUrl, ...this._seeds, ...this._order])]; }
+
+  /** The node a URL is on, or null when it is not an sMap URL. */
+  nodeOf(url) {
+    const u = String(url);
+    return this.origins().filter((o) => u === o || u.startsWith(o + '/')).sort((a, b) => b.length - a.length)[0] || null;
+  }
+
+  /** The path (with query) of an sMap URL, or null. */
+  pathOf(url) {
+    const n = this.nodeOf(url);
+    return n === null ? null : String(url).slice(n.length) || '/';
+  }
+
+  /** The same sMap URL on the node read from now; other URLs unchanged. */
+  rebase(url) {
+    const p = this.pathOf(url);
+    return p === null ? url : this.node() + p;
+  }
+
+  /**
+   * A node did not answer: it moves to the end and the next one is read from. Returns true when the node read from
+   * changed (callers then re-point their tile URLs).
+   */
+  failed(urlOrNode) {
+    const n = this.nodeOf(urlOrNode) || strip(urlOrNode);
+    const i = this._order.indexOf(n);
+    if (i < 0 || this._order.length < 2) { return false; }
+    const before = this.node();
+    this._order.splice(i, 1);
+    this._order.push(n);
+    // The client's own order follows, so its requests (styles, TileJSON) and these tile URLs agree.
+    if (typeof this.client.demote === 'function') { this.client.demote(n); }
+    if (this.node() !== before) { this._emit('nodechange', this.node()); return true; }
+    return false;
+  }
+
+  /** Style URL of a scheme or a saved custom style (`custom:<id>`), with labels in `language`, on the current node. */
+  styleUrl(style, language) {
+    return sdkStyleUrl(checkStyle(style), { baseUrl: this.node(), lang: language, apiKey: this.apiKey || undefined });
+  }
+
+  /** TileJSON URL of a vector source (default the basemap). */
+  tileJsonUrl(source = 'basemap') {
+    return addQuery(this.node() + '/v1/tiles/' + encodeURIComponent(source), { key: this.apiKey });
+  }
+
+  /**
+   * Raster tile template (contract §5): `{z}/{x}/{y}` by default; `placeholders` renames them for tools with their
+   * own (`{ z: '{level}', x: '{col}', y: '{row}' }`).
+   */
+  rasterTemplate(style, { language, retina = false, placeholders } = {}) {
+    const url = sdkRasterUrl(checkStyle(style), { baseUrl: this.node(), lang: language, retina, apiKey: this.apiKey || undefined });
+    const p = placeholders || {};
+    return url.replace('{z}', p.z || '{z}').replace('{x}', p.x || '{x}').replace('{y}', p.y || '{y}');
+  }
+
+  /** TileJSON (raster) of a style. */
+  rasterTileJsonUrl(style, { language } = {}) {
+    return sdkRasterTileJsonUrl(checkStyle(style), { baseUrl: this.node(), lang: language, apiKey: this.apiKey || undefined });
+  }
+
+  /** WMTS 1.0.0 capabilities of the raster styles. */
+  wmtsCapabilitiesUrl() {
+    return addQuery(this.node() + '/v1/raster/wmts', { SERVICE: 'WMTS', REQUEST: 'GetCapabilities', key: this.apiKey });
+  }
+
+  /**
+   * Fetches a URL: sMap URLs through the client (nearest node, the next one on failure, token and key); any other URL
+   * with plain fetch.
+   */
+  fetch(url, init) {
+    const path = this.pathOf(url);
+    if (path === null) { return globalThis.fetch(url, init); }
+    const extra = {};
+    const h = init && init.headers;
+    if (h) { for (const [k, v] of (typeof h.entries === 'function' ? h.entries() : Object.entries(h))) { extra[k] = v; } }
+    return this.client.request(path, extra);
+  }
+
+  /** The style document of a scheme or custom style, read through the client. */
+  style(style, language) {
+    return this.fetch(this.styleUrl(style, language)).then((r) => r.json());
+  }
+
+  on(type, fn) { (this._listeners[type] || (this._listeners[type] = [])).push(fn); return () => this.off(type, fn); }
+  off(type, fn) { const l = this._listeners[type] || []; const i = l.indexOf(fn); if (i >= 0) { l.splice(i, 1); } }
+  _emit(type, value) { for (const fn of (this._listeners[type] || []).slice()) { try { fn(value); } catch (e) { /* listener */ } } }
+
+  /** Stops the token refresh. */
+  close() { this._closed = true; clearTimeout(this._timer); }
+}
+
+/** A session from options, or the session given. */
+export function createSession(options) {
+  return options instanceof Session ? options : new Session(options || {});
+}