@superrouteca/smap-mapbox 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.1.0 — 2026-10-27
+
+- First version. sMap in Mapbox GL JS: `new SMapMapbox(mapboxgl, options)` draws sMap's style with Mapbox GL JS
+  itself — the five colour schemes and saved custom styles (`custom:<id>`), any label language, basemap overrides
+  (`setBasemap`), 3D buildings — and keeps your own sources and layers when the style, language or overrides change.
+- Map key or token on every sMap request (renewed through `getToken`), the nearest map node and the next one when a
+  node fails; your own `transformRequest` still handles every other host.
+- Style Specification layers at the basemap's slots (`bottom`, `roads`, `labels`, `top`, and Mapbox's `middle`),
+  raster and vector tile layers.
+- sMap's pins, lines and areas with their options, popups and Auto Zoom on a layer above that follows the camera.
+- The data credit and every source credit in the attribution, with the sMap badge.
+- `switchBasemap()` moves an existing Mapbox GL JS map onto sMap's basemap without touching its own layers.
+- Mapbox GL JS on sMap: `loadMapboxStyle()`, `addMapboxLayers()` and `copyMapboxLayers()` put Mapbox GL JS styles
+  and layers on an sMap map, listing what is hosted by Mapbox and left out.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goodneo Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Goodneo-Solutions/smap-sdk/main/assets/smap-logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/Goodneo-Solutions/smap-sdk/main/assets/smap-logo.svg" alt="sMap" height="56">
+</picture>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# sMap for Mapbox GL JS: `@superrouteca/smap-mapbox`
+
+Two ways round:
+
+- **sMap in Mapbox GL JS.** sMap's style drawn by Mapbox GL JS itself: the five colour schemes and your saved
+  custom styles, labels in any language, basemap overrides, 3D buildings and tilting, map key or token on every
+  request (renewed through `getToken`), the nearest map node and the next one when a node fails, the credits and the
+  sMap badge. sMap's pins, lines and areas with all their options, popups and Auto Zoom on a layer above.
+- **Mapbox GL JS on sMap.** Mapbox GL JS styles and layers (from Mapbox Studio, Maputnik or an existing page) on an
+  sMap map, and an existing Mapbox GL JS map switched to sMap's basemap without rewriting its layers.
+
+- Version 1.1.0, MIT licence (see `LICENSE` at the repository root)
+- Mapbox GL JS 3 (you pass it in; it is a peer dependency and never bundled). Mapbox GL JS itself is used under
+  Mapbox's terms, which ask for a Mapbox access token (`mapboxgl.accessToken`).
+- ES module with types
+
+## Installation
+
+```sh
+npm install @superrouteca/smap-mapbox mapbox-gl
+```
+
+```js
+import 'mapbox-gl/dist/mapbox-gl.css';
+import '@superrouteca/smap/smap.css';   // popups and the Auto Zoom chooser of sMap's layers
+```
+
+## sMap in Mapbox GL JS
+
+```js
+import mapboxgl from 'mapbox-gl';
+import { SMapMapbox } from '@superrouteca/smap-mapbox';
+
+mapboxgl.accessToken = 'pk.…';           // Mapbox's own terms
+
+const smap = new SMapMapbox(mapboxgl, {
+  container: 'map',
+  apiKey: 'smk_…',                        // a map key that allows this site, or token / getToken
+  style: 'light',                         // light, white, grayscale, dark, black, or 'custom:sms_…'
+  language: 'en',
+  center: [-79.38, 43.65],
+  zoom: 12,
+  pitch: 50,
+  buildings3D: true,
+});
+await smap.ready;
+const map = smap.map;                     // the Mapbox GL JS map, for everything else
+
+smap.setBasemap({ water: { color: '#9cc0e6' }, pois: { visible: false }, roads: { width: 1.4 } });
+smap.setStyle('dark');
+smap.setLanguage('fr');
+
+// Style Specification layers go into the Mapbox GL JS map, at a slot of the sMap basemap or under a layer:
+smap.addSource('zones', { type: 'geojson', data: zones });
+smap.addStyleLayer({ id: 'zones-fill', type: 'fill', source: 'zones', paint: { 'fill-color': '#f97316' } }, { slot: 'labels' });
+smap.addRasterLayer('radar', { tiles: ['https://radar.example/{z}/{x}/{y}.png'], opacity: 0.6, slot: 'roads' });
+
+// sMap's own layers (pins, numbers, route lines, popups, Auto Zoom):
+smap.addPoints('stops', stops, {
+  marker: { fill: { property: 'status_color' }, border: { property: 'route_color' }, text: { property: 'stop_number' } },
+  popup: (p) => `<b>${p.stop_number}</b>`,
+});
+smap.addLines('routes', routes, { color: { property: 'color' }, width: 5, casing: true, arrows: true });
+```
+
+What happens where:
+
+- **The basemap** is sMap's style document, read from the nearest node with your key, with your overrides applied
+  (`setBasemap`, as on every sMap map) and drawn by Mapbox GL JS. `setStyle`, `setLanguage`, `setBasemap` and
+  `setBuildings3D` replace the basemap and keep your own sources and layers where they were.
+- **Every request to sMap** goes through the adapter's `transformRequest`: to the node in use, with the token and
+  the map key. A node that fails (no answer or a 5xx) is tried last from then on. Pass your own `transformRequest`
+  for other hosts; it is called for everything that is not sMap's.
+- **Slots**: `addStyleLayer(layer, { slot })` puts a layer under the basemap's roads (`roads`), labels (`labels`, or
+  Mapbox's own `middle`), over the land and water (`bottom`) or on top (`top`); without a slot or `before` a layer
+  goes on top in the order added.
+- **sMap's own layers** (`addPoints`, `addLines`, `addPolygons`, `addData`, `setData`, `setVisible`, `removeLayer`,
+  `fitLayer`, `openPopup`, `closePopup`, `setAutoZoom`, `addWmsLayer`, `addWmtsLayer`, `addArcGisLayer`,
+  `addDeckLayer`, `loadLayers`) are drawn by an sMap map above the Mapbox GL JS map that follows its camera (tilt and
+  rotation included) and hears its clicks; its own moves (Auto Zoom, `fitLayer`) move the Mapbox GL JS map.
+  `await smap.overlay()` gives that sMap map; `await smap.call('toGeoJSON', 'stops')` answers a value.
+- **Credits and badge**: the data credit comes from sMap's style; credits of layers drawn above are added beside
+  it; the sMap badge sits in the bottom-right corner.
+- The map is in Web Mercator unless you pass `projection` (sMap's layers above follow Web Mercator only).
+
+### An existing Mapbox GL JS map
+
+```js
+import { switchBasemap, smapAccess, smapTransformRequest } from '@superrouteca/smap-mapbox';
+
+const access = smapAccess({ getToken: () => myServer.mapToken() });
+const map = new mapboxgl.Map({ container: 'map', style: 'mapbox://styles/mapbox/streets-v12', transformRequest: smapTransformRequest(access) });
+// … the app adds its own sources and layers …
+const smap = await switchBasemap(mapboxgl, map, { access, style: 'light' });
+```
+
+The Mapbox-hosted basemap (its `mapbox://` sources, the layers reading them, its background and sky) goes; every
+other source and layer stays, on top of sMap's basemap. `keep(layer)` decides instead which layers stay. A map made
+without `smapTransformRequest()` can use a map key (it travels in sMap's style URLs) but not a token.
+
+## Mapbox GL JS on sMap
+
+```js
+import { Map } from '@superrouteca/smap';
+import { loadMapboxStyle, copyMapboxLayers, addMapboxLayers } from '@superrouteca/smap-mapbox/on-smap';
+
+const smap = new Map({ container: 'map', apiKey: 'smk_…', style: 'light' });
+await smap.ready;
+
+const report = await loadMapboxStyle(smap, studioStyle);          // a style document or its address
+console.log(report.layers, report.skipped, report.warnings);
+
+await copyMapboxLayers(mapboxMap, smap, { filter: (l) => l.id.startsWith('app-') });
+await addMapboxLayers(smap, [{ id: 'dots', type: 'circle', source: 'orders' }], { sources: { orders: { type: 'geojson', data } } });
+```
+
+Sources and layers go on the sMap map as they are (`addSource`, `addStyleLayer`). Left out, and listed in
+`skipped`: sources hosted by Mapbox (`mapbox://`, `api.mapbox.com`; they need a Mapbox account), the layers reading
+them, and `background` / `sky` / `fog` layers (they would cover sMap's basemap). A Mapbox GL JS v3 `slot` becomes an
+sMap slot (`bottom` → `bottom`, `middle` → `labels`, `top` → `top`); options `slot` / `before` place layers that name
+none; without any, a layer draws on top in the order added. `prefix` renames every source and layer; `layers` or
+`filter` choose them. Icons of the style's own sprite are not loaded (a warning says so).
+
+## Example
+
+`examples/index.html` shows both ways. Serve the repository root (for example `npx serve .`) and open
+`/mapbox/examples/?key=smk_…&mapbox=pk.…` with a map key that allows your host and a Mapbox access token.
+
+## Tests
+
+```sh
+npm test            # over a stand-in for Mapbox GL JS, which needs WebGL
+npm run typecheck
+```

package/examples/index.html

@@ -0,0 +1,81 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>sMap for Mapbox GL JS</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mapbox-gl@3.33.0/dist/mapbox-gl.css">
+  <link rel="stylesheet" href="../../js/dist/smap.css">
+  <style>
+    body { margin: 0; font: 14px/1.4 system-ui, sans-serif; }
+    .bar { display: flex; gap: 8px; align-items: center; padding: 8px 12px; flex-wrap: wrap; }
+    .maps { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; padding: 0 12px 12px; }
+    .maps > div { height: 70vh; border: 1px solid #cbd5e1; border-radius: 6px; position: relative; }
+    h2 { font-size: 14px; margin: 0 12px; }
+    @media (max-width: 800px) { .maps { grid-template-columns: 1fr; } }
+  </style>
+  <!-- Serve the repository root (npx serve .) and open /mapbox/examples/?key=smk_…&mapbox=pk.… -->
+  <script src="https://cdn.jsdelivr.net/npm/mapbox-gl@3.33.0/dist/mapbox-gl.js"></script>
+  <script type="importmap">
+  {
+    "imports": {
+      "@superrouteca/smap": "../../js/dist/smap.mjs",
+      "@superrouteca/smap/client": "../../js/dist/smap-client.mjs",
+      "@superrouteca/smap-mapbox": "../src/index.js",
+      "@superrouteca/smap-mapbox/on-smap": "../src/on-smap.js"
+    }
+  }
+  </script>
+</head>
+<body>
+  <div class="bar">
+    <label>Scheme <select id="scheme"><option>light</option><option>white</option><option>grayscale</option><option>dark</option><option>black</option></select></label>
+    <label>Language <select id="lang"><option>en</option><option>fr</option><option>de</option><option>zh-Hans</option></select></label>
+    <label><input type="checkbox" id="buildings" checked> 3D buildings</label>
+    <button id="water">Blue water</button>
+  </div>
+  <h2>sMap in Mapbox GL JS (left) · Mapbox GL JS layers on an sMap map (right)</h2>
+  <div class="maps"><div id="mapbox"></div><div id="smap"></div></div>
+  <script type="module">
+    const mapboxgl = window.mapboxgl;   // the browser build of Mapbox GL JS, loaded above
+    import { Map as SMap, popupTemplate } from '@superrouteca/smap';
+    import { SMapMapbox } from '@superrouteca/smap-mapbox';
+    import { addMapboxLayers } from '@superrouteca/smap-mapbox/on-smap';
+
+    const q = new URLSearchParams(location.search);
+    const apiKey = q.get('key') || undefined;
+    mapboxgl.accessToken = q.get('mapbox') || '';
+    const stops = [
+      { lng: -79.3832, lat: 43.6532, n: 1, status: '#16a34a', name: 'City Hall' },
+      { lng: -79.3871, lat: 43.6426, n: 2, status: '#f97316', name: 'CN Tower' },
+      { lng: -79.3957, lat: 43.6677, n: 3, status: '#2563eb', name: 'Queen’s Park' },
+      { lng: -79.3806, lat: 43.6629, n: 4, status: '#e11d48', name: 'Church St' },
+    ];
+    const zone = { type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [[[-79.392, 43.648], [-79.378, 43.648], [-79.378, 43.658], [-79.392, 43.658], [-79.392, 43.648]]] } };
+
+    // ① sMap in Mapbox GL JS
+    const smap = new SMapMapbox(mapboxgl, { container: 'mapbox', apiKey, style: 'light', language: 'en', center: [-79.387, 43.652], zoom: 14.5, pitch: 55, bearing: -20, buildings3D: true });
+    await smap.ready;
+    smap.addSource('zone', { type: 'geojson', data: zone });
+    smap.addStyleLayer({ id: 'zone-fill', type: 'fill', source: 'zone', paint: { 'fill-color': '#f97316', 'fill-opacity': 0.25 } }, { slot: 'roads' });
+    smap.addLines('route', { type: 'LineString', coordinates: stops.map((s) => [s.lng, s.lat]) }, { color: '#2563eb', width: 5, casing: true, arrows: true });
+    smap.addPoints('stops', stops, { marker: { fill: { property: 'status' }, border: '#1e293b', text: { property: 'n' } }, popup: popupTemplate('<b>{n}</b> {name}') });
+
+    const scheme = document.getElementById('scheme');
+    const lang = document.getElementById('lang');
+    scheme.onchange = () => smap.setStyle(scheme.value);
+    lang.onchange = () => smap.setLanguage(lang.value);
+    document.getElementById('buildings').onchange = (e) => smap.setBuildings3D(e.target.checked);
+    document.getElementById('water').onclick = () => smap.setBasemap({ water: { color: '#60a5fa' } });
+
+    // ② Mapbox GL JS layers on an sMap map
+    const plain = new SMap({ container: 'smap', apiKey, style: 'grayscale', language: 'en', center: [-79.387, 43.655], zoom: 13 });
+    await plain.ready;
+    const report = await addMapboxLayers(plain, [
+      { id: 'zone-line', type: 'line', source: 'zone', paint: { 'line-color': '#f97316', 'line-width': 3 }, slot: 'middle' },
+      { id: 'stop-dots', type: 'circle', source: 'stops', paint: { 'circle-radius': 7, 'circle-color': ['get', 'status'], 'circle-stroke-color': '#fff', 'circle-stroke-width': 2 } },
+    ], { sources: { zone: { type: 'geojson', data: zone }, stops: { type: 'geojson', data: { type: 'FeatureCollection', features: stops.map((s) => ({ type: 'Feature', properties: s, geometry: { type: 'Point', coordinates: [s.lng, s.lat] } })) } } } });
+    console.log('Mapbox GL JS layers on sMap', report);
+  </script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@superrouteca/smap-mapbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "sMap for Mapbox GL JS: maps from Superroute's sMap service in Mapbox GL JS, and Mapbox GL JS styles and layers on an sMap map.",
+  "license": "MIT",
+  "author": "Goodneo Solutions",
+  "homepage": "https://github.com/Goodneo-Solutions/smap-sdk/tree/main/mapbox#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Goodneo-Solutions/smap-sdk.git",
+    "directory": "mapbox"
+  },
+  "keywords": [
+    "map",
+    "maps",
+    "mapbox",
+    "mapbox-gl",
+    "vector-tiles",
+    "smap",
+    "superroute"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./on-smap": {
+      "types": "./types/on-smap.d.ts",
+      "default": "./src/on-smap.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepack": "cp ../LICENSE LICENSE",
+    "typecheck": "tsc -p test/tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "mapbox-gl": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mapbox-gl": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@superrouteca/smap": "1.1.0"
+  },
+  "devDependencies": {
+    "@types/geojson": "7946.0.16",
+    "jsdom": "30.1.3",
+    "mapbox-gl": "3.33.0",
+    "typescript": "6.0.3"
+  }
+}

package/src/common/access.js

@@ -0,0 +1,198 @@
+// sMap tool adapters — access to the service: map key or token (renewed through getToken), the nearest node and the
+// next one when a node fails. Kept identical in leaflet/, openlayers/ and mapbox/ (test/common.test.mjs checks); the
+// node choice, the token renewal and the failover of requests are the JS client's (@superrouteca/smap/client).
+import SMapClient from '@superrouteca/smap/client';
+import * as sMapModule from '@superrouteca/smap';
+
+const SDK = sMapModule.default && sMapModule.default.Map ? sMapModule.default : sMapModule;
+const PLACEHOLDER = 'https://smap.invalid';
+
+/** The SDK's own URL builder (rasterUrl, styleUrl of @superrouteca/smap 1.1.0); throws when the SDK is older. */
+function builder(name) {
+  if (typeof SDK[name] !== 'function') { throw new Error('sMap: the adapters need @superrouteca/smap 1.1.0 or later (' + name + ')'); }
+  return SDK[name];
+}
+
+/** A path of the SDK's URL builders, without their address. */
+function pathOf(url) { return url.slice(PLACEHOLDER.length); }
+
+export const DEFAULT_BASE = 'https://tile.srsr.ca';
+export const FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
+const CUSTOM = /^custom:([A-Za-z0-9_-]+)$/;
+
+/** Checks a style name: a scheme or `custom:<id>`; anything else throws with the name in the message. */
+export function checkStyle(style) {
+  const s = style == null ? 'light' : String(style);
+  if (FLAVORS.indexOf(s) >= 0 || CUSTOM.test(s)) { return s; }
+  throw new Error('sMap: unknown style "' + s + '" (use ' + FLAVORS.join(', ') + ' or custom:<id>)');
+}
+
+/** The path of one raster tile on an sMap node (interop contract §5, the SDK's rasterUrl): 256 px, or 512 px with `retina`. */
+export function rasterPath(style, z, x, y, options) {
+  const o = options || {};
+  const url = builder('rasterUrl')(checkStyle(style), { lang: o.lang || o.language, retina: !!o.retina, baseUrl: PLACEHOLDER });
+  return pathOf(url).replace('{z}', String(z | 0)).replace('{x}', String(x | 0)).replace('{y}', String(y | 0));
+}
+
+/** The path of a style document (the SDK's styleUrl): a scheme or a saved custom style, with labels in `lang`. */
+export function stylePath(style, lang) {
+  return pathOf(builder('styleUrl')(checkStyle(style), { lang: lang, baseUrl: PLACEHOLDER }));
+}
+
+function strip(url) { return String(url).replace(/\/$/, ''); }
+
+export class SMapAccess {
+  /**
+   * @param {Object} [o]  baseUrl, token, getToken, apiKey, nodes, nearest, fetch, timeoutMs (as the JS client), or
+   *                      `client`: a JS client of your own.
+   */
+  constructor(o) {
+    o = o || {};
+    this.client = o.client || new SMapClient({
+      baseUrl: o.baseUrl || DEFAULT_BASE,
+      token: o.token,
+      getToken: o.getToken,
+      apiKey: o.apiKey,
+      nodes: o.nodes,
+      nearest: o.nearest,
+      fetch: o.fetch,
+      timeoutMs: o.timeoutMs,
+    });
+    this.baseUrl = strip(this.client.baseUrl);
+    this.apiKey = o.apiKey || null;
+    this._getToken = o.getToken || null;
+    this._token = o.token || null;
+    this._seeds = (o.nodes || []).map(strip);
+    this._order = null;
+    this._timer = null;
+    this._starting = null;
+    this._stopped = false;
+    this._listeners = [];
+  }
+
+  /** Reads the first token and the node order; resolves once both are known (never rejects for the nodes). */
+  start() {
+    if (!this._starting) {
+      const self = this;
+      this._starting = Promise.all([
+        this.refresh(),
+        this.client.nodes().then(function (order) { self._order = order; }, function () { self._order = [self.baseUrl]; }),
+      ]).then(function () { return self; });
+    }
+    return this._starting;
+  }
+
+  /** Asks the client for the current token (getToken is called when it is missing or expires within 2 minutes). */
+  refresh() {
+    const self = this;
+    return this.client.token().then(function (t) {
+      const changed = t !== self._token;
+      self._token = t || null;
+      self._schedule();
+      if (changed) { self._emit('token', self._token); }
+      return self._token;
+    });
+  }
+
+  _schedule() {
+    clearTimeout(this._timer);
+    this._timer = null;
+    if (this._stopped || !this._getToken || !this._token) { return; }
+    const exp = SMapClient.tokenExpiry(this._token);
+    if (!exp) { return; }
+    // One second past the client's renewal point (2 minutes before expiry), so the client asks getToken again.
+    const wait = Math.max(5, exp - Math.floor(Date.now() / 1000) - 119) * 1000;
+    const self = this;
+    this._timer = setTimeout(function () {
+      self.refresh().catch(function () {
+        clearTimeout(self._timer);
+        self._timer = setTimeout(function () { self._schedule(); self.refresh().catch(function () {}); }, 30000);
+      });
+    }, Math.min(wait, 2147483000));
+    if (this._timer && typeof this._timer.unref === 'function') { this._timer.unref(); }
+  }
+
+  /** The token to send now (null without one). */
+  token() { return this._token; }
+
+  /** The nodes in the order they are tried, nearest first (baseUrl alone before start() resolves). */
+  nodes() { return this._order ? this._order.slice() : [this.baseUrl]; }
+
+  /** The node requests go to now. */
+  head() { return (this._order && this._order[0]) || this.baseUrl; }
+
+  _nodeOf(url) {
+    const u = String(url);
+    const all = [this.baseUrl].concat(this._seeds, this._order || []);
+    for (let i = 0; i < all.length; i++) {
+      const n = all[i];
+      if (u === n || u.indexOf(n + '/') === 0 || u.indexOf(n + '?') === 0) { return n; }
+    }
+    return null;
+  }
+
+  /** True for a URL on the sMap service (baseUrl, a seed or a listed node). */
+  isOurs(url) { return this._nodeOf(url) !== null; }
+
+  /** The headers an sMap request carries (token, map key); none for any other host. */
+  headers(url) {
+    const h = {};
+    if (!this.isOurs(url)) { return h; }
+    if (this._token) { h.Authorization = 'Bearer ' + this._token; }
+    if (this.apiKey) { h['X-SMap-Key'] = this.apiKey; }
+    return h;
+  }
+
+  /** An sMap URL moved onto the node requests go to now; other URLs unchanged. */
+  rewrite(url) {
+    const n = this._nodeOf(url);
+    const head = this.head();
+    if (!n || n === head) { return url; }
+    return head + String(url).slice(n.length);
+  }
+
+  /** Reports that a request to `url` failed: its node is tried last from now on. */
+  failed(url) {
+    const n = this._nodeOf(url);
+    if (!n || !this._order || this._order.length < 2) { return; }
+    // The client's own order is the one moved, so its requests and these rewrites agree.
+    if (typeof this.client.demote === 'function') { this.client.demote(n); }
+    else {
+      const i = this._order.indexOf(n);
+      if (i >= 0) { this._order.splice(i, 1); this._order.push(n); }
+    }
+    this._emit('nodes', this.nodes());
+  }
+
+  /** A path appended with the map key (styles and TileJSON: the service writes it into the tile URLs). */
+  withKey(path) {
+    if (!this.apiKey) { return path; }
+    return path + (path.indexOf('?') >= 0 ? '&' : '?') + 'key=' + encodeURIComponent(this.apiKey);
+  }
+
+  /** A style document (a scheme or `custom:<id>`) from the nearest node that answers. */
+  style(style, lang) {
+    return this.client.request(this.withKey(stylePath(style, lang))).then(function (r) { return r.json(); });
+  }
+
+  /** One raster tile as a Blob, from the nearest node that answers (contract §5). */
+  rasterTile(style, z, x, y, options) {
+    return this.client.request(rasterPath(style, z, x, y, options)).then(function (r) { return r.blob(); });
+  }
+
+  /** A `{z}/{x}/{y}` raster URL on the current node, for tools that load images by URL (map key in the query). */
+  rasterTemplate(style, options) {
+    const o = options || {};
+    return builder('rasterUrl')(checkStyle(style), { lang: o.lang || o.language, retina: !!o.retina, baseUrl: this.head(), apiKey: this.apiKey || undefined });
+  }
+
+  /** Called with ('token', token) after a renewal and ('nodes', order) after a node failed. */
+  on(fn) { this._listeners.push(fn); return this; }
+
+  _emit(type, value) { this._listeners.slice().forEach(function (fn) { try { fn(type, value); } catch (e) { /* listener error */ } }); }
+
+  /** Stops renewing the token. */
+  stop() { this._stopped = true; clearTimeout(this._timer); this._timer = null; this._listeners = []; }
+}
+
+export { SMapClient };

package/src/common/badge.js

@@ -0,0 +1,56 @@
+// sMap tool adapters — the sMap badge and the data credit shown in another tool's corner. Kept identical in leaflet/,
+// openlayers/ and mapbox/ (test/common.test.mjs checks).
+
+/** The data credit every sMap map keeps visible (the data licence requires it). */
+export const OSM_ATTRIBUTION = '<a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">&copy; OpenStreetMap contributors</a>';
+
+const 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>';
+
+const CSS = [
+  '.smap-adapter-badge{display:flex;align-items:center;gap:4px;height:20px;padding:0 7px 0 3px;border-radius:10px;',
+  'background:rgba(255,255,255,.82);box-shadow:0 0 0 1px rgba(15,23,42,.12);color:#1e293b;',
+  'font:600 11px/20px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;',
+  'letter-spacing:.01em;pointer-events:none;-webkit-user-select:none;user-select:none;margin:4px 6px;width:max-content}',
+  '.smap-adapter-badge svg{display:block;flex:none;width:14px;height:14px}',
+  // An sMap map drawn inside another tool: the tool takes the input; only popups take clicks; the tool's corner
+  // shows the badge and the credit, so the embedded map's own are hidden.
+  '.smap-embedded{position:absolute;top:0;left:0;pointer-events:none;overflow:hidden}',
+  '.smap-embedded .smap-badge,.smap-embedded .maplibregl-ctrl-attrib{display:none!important}',
+  '.smap-embedded .maplibregl-popup{pointer-events:auto}',
+].join('');
+
+/** Adds the adapters' stylesheet to a document once. */
+export function injectCss(doc) {
+  if (!doc || !doc.head || doc.getElementById('smap-adapter-css')) { return; }
+  const style = doc.createElement('style');
+  style.id = 'smap-adapter-css';
+  style.textContent = CSS;
+  doc.head.appendChild(style);
+}
+
+/** The badge element (not a link): the sMap icon and name on a semi-transparent pill. */
+export function createBadge(doc) {
+  injectCss(doc);
+  const el = doc.createElement('div');
+  el.className = 'smap-adapter-badge';
+  el.setAttribute('aria-label', 'sMap');
+  el.innerHTML = ICON + '<span>sMap</span>';
+  return el;
+}
+
+/**
+ * The credits to show: the data credit first, then every other credit a source names (once each; a source's own
+ * OpenStreetMap credit is the data credit and is not repeated).
+ */
+export function mergeAttributions(list) {
+  const out = [OSM_ATTRIBUTION];
+  (list || []).forEach(function (a) {
+    if (!a || typeof a !== 'string') { return; }
+    if (/openstreetmap/i.test(a)) { return; }
+    if (out.indexOf(a) < 0) { out.push(a); }
+  });
+  return out;
+}