@superrouteca/smap-leaflet 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.1.0 — 2026-10-27
+
+- First version. sMap in Leaflet: `smapLayer()` draws the sMap vector map in a Leaflet pane with the five colour
+  schemes and saved custom styles (`custom:<id>`), any label language, basemap overrides, sMap's pins, lines and
+  areas with their options, popups and Auto Zoom; Leaflet keeps the view and the input, and the sMap map's own moves
+  are made by Leaflet. `smapRasterLayer()` gives raster tiles for browsers without WebGL; `smapBasemap()` picks one.
+- Map key or token with renewal through `getToken`, the nearest map node and the next one when a node fails.
+- The data credit and every source credit appear in Leaflet's attribution, with the sMap badge beside it.
+- Leaflet on sMap: `createLeafletCompat(smapMap)` gives Leaflet-style calls on an sMap map (`L.map`, `L.marker`,
+  `L.circleMarker`, `L.circle`, `L.polyline`, `L.polygon`, `L.rectangle`, `L.geoJSON`, `L.tileLayer`,
+  `L.tileLayer.wms`, `L.layerGroup`, `L.featureGroup`, `L.popup`, `bindPopup`, `addTo`, events).

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,159 @@
-# 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 Leaflet: `@superrouteca/smap-leaflet`
+
+Two ways round:
+
+- **sMap in Leaflet.** The sMap map as a Leaflet layer: the five colour schemes and your saved custom styles, labels
+  in any language, basemap overrides, sMap's pins, lines and areas with all their options, popups and Auto Zoom, map
+  key or token with renewal, the nearest map node. Vector (drawn with WebGL inside a Leaflet pane) or raster tiles for
+  browsers without WebGL.
+- **Leaflet on sMap.** Leaflet-style calls (`L.marker`, `L.circleMarker`, `L.polyline`, `L.polygon`, `L.geoJSON`,
+  `L.tileLayer`, `bindPopup`, `L.layerGroup`, `addTo`, events) on an sMap map, so code written for Leaflet runs on
+  sMap.
+
+- Version 1.1.0, MIT licence (see `LICENSE` at the repository root)
+- Leaflet 1.9 (a peer dependency; not needed for the Leaflet-style calls on an sMap map)
+- ES module with types
+
+## Installation
+
+```sh
+npm install @superrouteca/smap-leaflet leaflet
+```
+
+Load Leaflet's stylesheet and the sMap stylesheet (popups, Auto Zoom chooser):
+
+```js
+import 'leaflet/dist/leaflet.css';
+import '@superrouteca/smap/smap.css';
+```
+
+## sMap in Leaflet
+
+```js
+import L from 'leaflet';
+import { smapLayer } from '@superrouteca/smap-leaflet';
+
+const map = L.map('map').setView([43.65, -79.38], 12);
+
+const basemap = smapLayer({
+  apiKey: 'smk_…',            // a map key that allows this site, or token / getToken
+  style: 'light',             // light, white, grayscale, dark, black, or 'custom:sms_…'
+  language: 'en',
+}).addTo(map);
+
+// Your Leaflet layers stay as they are:
+L.marker([43.65, -79.38]).addTo(map);
+
+// sMap's own layers, on the sMap map (drawn on the GPU, popups and Auto Zoom included):
+basemap.addPoints('stops', stops, {
+  marker: { fill: { property: 'status_color' }, border: { property: 'route_color' }, text: { property: 'stop_number' } },
+  popup: (p) => `<b>${p.stop_number}</b>`,
+});
+basemap.addLines('routes', routes, { color: { property: 'color' }, width: 5, casing: true, arrows: true });
+basemap.addPolygons('zones', zones, { fill: '#f97316', opacity: 0.3 });
+basemap.setBasemap({ water: { color: '#9cc0e6' }, pois: { visible: false } });
+basemap.setStyle('dark');
+basemap.setLanguage('fr');
+```
+
+The layer forwards every sMap map call once its map is ready (`setStyle`, `setLanguage`, `setBasemap`,
+`setAutoZoom`, `addPoints`, `addLines`, `addPolygons`, `addData`, `setData`, `setVisible`, `fitLayer`, `addSource`,
+`addStyleLayer`, `setPaint`, `setLayout`, `setFilter`, `addRasterLayer`, `addWmsLayer`, `addWmtsLayer`,
+`addVectorTiles`, `addArcGisLayer`, `loadLayers`); `openSMapPopup` / `closeSMapPopup` open and close the sMap map's
+popup and `removeSMapLayer(id)` removes one of its layers (Leaflet keeps its own `openPopup` and `removeLayer`). Calls
+that answer a value: `await basemap.call('basemap')`, `await basemap.call('toJSON')`. `await basemap.ready` (or
+`basemap.getSMap()`) gives the sMap map itself.
+
+How it works with Leaflet:
+
+- Leaflet owns the view and the input. Every move and zoom of Leaflet moves the sMap map; every move the sMap map
+  asks for (Auto Zoom on piled-up pins, `fitLayer`, a popup panning into view) is made by Leaflet.
+- Clicks and pointer moves on the map reach sMap's layers: popups, Auto Zoom, `onClick`, the pin under the pointer
+  coming to the front, the pointer cursor. `interactive: false` turns this off.
+- The data credit and the credit of every source you add appear in Leaflet's attribution; the sMap badge sits above
+  it in the bottom-right corner (one badge per map).
+- Leaflet's zoom levels are one above the sMap map's own (`map.getZoom()` 12 is sMap zoom 11).
+- Leaflet draws flat maps: 3D buildings and tilting are for the tools that draw 3D (see the Mapbox GL JS adapter).
+- `pane` (default `tilePane`) chooses the Leaflet pane.
+
+### Raster tiles
+
+For browsers without WebGL, or wherever images are wanted:
+
+```js
+import { smapRasterLayer, smapBasemap } from '@superrouteca/smap-leaflet';
+
+smapRasterLayer({ apiKey: 'smk_…', style: 'grayscale', language: 'de' }).addTo(map);   // 256 px tiles, 512 on high-density screens
+smapBasemap({ apiKey: 'smk_…', style: 'light' }).addTo(map);   // vector where WebGL 2 exists, raster elsewhere
+```
+
+Tiles are read with the map key or token from the nearest node and move to the next node when one fails.
+`setStyle()` and `setLanguage()` reload them. Every Leaflet grid layer option (`opacity`, `zIndex`, `minZoom`, …)
+applies.
+
+### Map keys and tokens
+
+- **Map key** (`apiKey: 'smk_…'`): created in the Superroute developer center with the sites it may be used from.
+- **Token** (`token: 'sm1.…'`, or `getToken: async () => …`): signed by your own server; with `getToken` a new token
+  is asked for two minutes before the current one expires.
+- `baseUrl` (default `https://tile.srsr.ca`), `nodes` (node addresses known in advance), `nearest` (default true).
+
+## Leaflet on sMap
+
+```js
+import { Map } from '@superrouteca/smap';
+import { createLeafletCompat } from '@superrouteca/smap-leaflet/compat';
+
+const smap = new Map({ container: 'map', apiKey: 'smk_…', style: 'light', center: [-79.38, 43.65], zoom: 11 });
+await smap.ready;
+const L = createLeafletCompat(smap);
+const map = L.map;                                   // a Leaflet-style map over the sMap map
+
+L.marker([43.65, -79.38]).addTo(map).bindPopup('<b>Depot</b>');
+L.circleMarker([43.66, -79.4], { radius: 8, color: '#e11d48' }).addTo(map);
+L.polyline(latlngs, { color: '#16a34a', weight: 5, dashArray: '10, 5' }).addTo(map);
+L.polygon(ring, { color: '#2563eb', fillOpacity: 0.3 }).addTo(map);
+L.geoJSON(zones, {
+  style: (f) => ({ color: f.properties.color }),
+  onEachFeature: (f, layer) => layer.bindPopup(f.properties.name),
+}).addTo(map);
+L.tileLayer('https://{s}.tiles.example/{z}/{x}/{y}.png', { attribution: '© Example' }).addTo(map);
+L.layerGroup([L.marker([43.7, -79.4])]).addTo(map);
+
+map.setView([43.65, -79.38], 13);
+map.on('click', (e) => console.log(e.latlng));
+```
+
+What is there: `L.map` (`setView`, `getCenter`, `getZoom`, `setZoom`, `zoomIn`, `zoomOut`, `panTo`, `panBy`,
+`flyTo`, `fitBounds`, `getBounds`, `addLayer`, `removeLayer`, `hasLayer`, `eachLayer`, `on` / `off` with `latlng`,
+`openPopup`, `closePopup`, `invalidateSize`, `project`, `unproject`), `L.marker` (with `L.icon`), `L.circleMarker`,
+`L.circle` (radius in metres), `L.polyline`, `L.polygon` (holes and multi-polygons), `L.rectangle`, `L.geoJSON`
+(`style`, `pointToLayer`, `onEachFeature`, `filter`, `addData`, `resetStyle`), `L.tileLayer` and `L.tileLayer.wms`,
+`L.layerGroup`, `L.featureGroup`, `L.popup`, `L.latLng`, `L.latLngBounds`. Layers have `addTo`, `remove`,
+`bindPopup` (text, an element or a function of the layer), `openPopup`, `setStyle`, `setLatLng` / `setLatLngs`,
+`getBounds`, `toGeoJSON`, and `on` / `off` / `fire` (a click carries `latlng` and `layer`; a feature group hears its
+layers' clicks).
+
+Each layer added to the map draws on top of the ones before, as in Leaflet. Layers that share their look are drawn
+together, so a GeoJSON layer of thousands of features costs a few map layers. Moving a marker only replaces its data.
+`L.divIcon` has no counterpart (the default pin is drawn); for many points use `smap.addPoints` with its pins and
+clustering.
+
+`addTo()` takes `L.map`, a layer group, or the sMap map itself.
+
+## Example
+
+`examples/index.html` shows both ways. Serve the repository root (for example `npx serve .`) and open
+`/leaflet/examples/?key=smk_…` with a map key that allows your host.
+
+## Tests
+
+```sh
+npm test
+npm run typecheck
+```

package/examples/index.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>sMap for Leaflet</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.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; }
+    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 /leaflet/examples/?key=smk_… -->
+  <script type="importmap">
+  {
+    "imports": {
+      "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet-src.esm.js",
+      "@superrouteca/smap": "../../js/dist/smap.mjs",
+      "@superrouteca/smap/client": "../../js/dist/smap-client.mjs",
+      "@superrouteca/smap-leaflet": "../src/index.js",
+      "@superrouteca/smap-leaflet/compat": "../src/compat.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="raster"> Raster tiles</label>
+    <button id="water">Blue water</button>
+  </div>
+  <h2>sMap in Leaflet (left) · Leaflet calls on an sMap map (right)</h2>
+  <div class="maps"><div id="leaflet"></div><div id="smap"></div></div>
+  <script type="module">
+    import * as Leaflet from 'leaflet';
+    import { Map as SMap, popupTemplate } from '@superrouteca/smap';
+    import { smapLayer, smapRasterLayer } from '@superrouteca/smap-leaflet';
+    import { createLeafletCompat } from '@superrouteca/smap-leaflet/compat';
+
+    const L = Leaflet.default || Leaflet;
+    const apiKey = new URLSearchParams(location.search).get('key') || undefined;
+    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 route = { type: 'LineString', coordinates: stops.map((s) => [s.lng, s.lat]) };
+
+    // ① sMap in Leaflet
+    const map = L.map('leaflet').setView([43.655, -79.387], 14);
+    let base = smapLayer({ apiKey, style: 'light', language: 'en' }).addTo(map);
+    function decorate(layer) {
+      layer.addLines('route', route, { color: '#2563eb', width: 5, casing: true, arrows: true });
+      layer.addPoints('stops', stops, {
+        marker: { fill: { property: 'status' }, border: '#1e293b', text: { property: 'n' } },
+        popup: popupTemplate('<b>{n}</b> {name}'),
+      });
+    }
+    decorate(base);
+    L.marker([43.6487, -79.3817]).addTo(map).bindPopup('A Leaflet marker over sMap');
+
+    const scheme = document.getElementById('scheme');
+    const lang = document.getElementById('lang');
+    scheme.onchange = () => base.setStyle(scheme.value);
+    lang.onchange = () => base.setLanguage(lang.value);
+    document.getElementById('water').onclick = () => base.setBasemap && base.setBasemap({ water: { color: '#60a5fa' } });
+    document.getElementById('raster').onchange = (e) => {
+      map.removeLayer(base);
+      base = e.target.checked
+        ? smapRasterLayer({ apiKey, style: scheme.value, language: lang.value }).addTo(map)
+        : smapLayer({ apiKey, style: scheme.value, language: lang.value }).addTo(map);
+      if (!e.target.checked) { decorate(base); }
+    };
+
+    // ② Leaflet calls on an sMap map
+    const smap = new SMap({ container: 'smap', apiKey, style: 'light', language: 'en', center: [-79.387, 43.655], zoom: 13 });
+    await smap.ready;
+    const C = createLeafletCompat(smap);
+    C.polyline(stops.map((s) => [s.lat, s.lng]), { color: '#16a34a', weight: 5, dashArray: '10, 6' }).addTo(C.map);
+    C.geoJSON({ type: 'FeatureCollection', features: stops.map((s) => ({ type: 'Feature', properties: s, geometry: { type: 'Point', coordinates: [s.lng, s.lat] } })) }, {
+      pointToLayer: (f, latlng) => C.circleMarker(latlng, { radius: 9, color: '#fff', weight: 2, fillColor: f.properties.status, fillOpacity: 1 }),
+      onEachFeature: (f, layer) => layer.bindPopup(`<b>${f.properties.n}</b> ${f.properties.name}`),
+    }).addTo(C.map);
+    C.circle([43.6532, -79.3832], { radius: 300, color: '#f97316' }).addTo(C.map);
+    C.map.on('click', (e) => console.log('clicked', e.latlng));
+  </script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@superrouteca/smap-leaflet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "sMap for Leaflet: maps from Superroute's sMap service as a Leaflet layer (vector or raster), and Leaflet-style calls on an sMap map.",
+  "license": "MIT",
+  "author": "Goodneo Solutions",
+  "homepage": "https://github.com/Goodneo-Solutions/smap-sdk/tree/main/leaflet#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Goodneo-Solutions/smap-sdk.git",
+    "directory": "leaflet"
+  },
+  "keywords": [
+    "map",
+    "maps",
+    "leaflet",
+    "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"
+    },
+    "./compat": {
+      "types": "./types/compat.d.ts",
+      "default": "./src/compat.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": {
+    "leaflet": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "leaflet": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@superrouteca/smap": "1.1.0"
+  },
+  "devDependencies": {
+    "@types/leaflet": "1.9.22",
+    "jsdom": "30.1.3",
+    "leaflet": "1.9.4",
+    "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;
+}