@superrouteca/smap-openlayers 0.0.0-stage → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.1.1 — 2026-10-27
+
+- The version follows the shared 1.1.1 release; no change of its own.
+
+## 1.1.0 — 2026-10-27
+
+- First version. sMap in OpenLayers: `smapLayer()` draws the sMap vector map as an OpenLayers layer 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; the OpenLayers view keeps the camera (rotation included) and
+  the input, and the sMap map's own moves are made by the view. `smapRasterSource()` / `smapRasterLayer()` give raster
+  tiles as an XYZ source; `smapBasemap()` picks vector or raster.
+- 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 OpenLayers' attribution, with the sMap badge beside it.
+- OpenLayers on sMap: `addOpenLayersLayer()` / `addOpenLayersLayers()` add XYZ, OSM, TileJSON, TileWMS, ImageWMS,
+  WMTS, VectorTile and Vector sources (or whole OpenLayers maps) to an sMap map.

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,149 @@
-# 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 OpenLayers: `@superrouteca/smap-openlayers`
+
+Two ways round:
+
+- **sMap in OpenLayers.** The sMap map as an OpenLayers 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 as an OpenLayers layer, rotation
+  included) or raster tiles as an XYZ source.
+- **OpenLayers on sMap.** OpenLayers sources and layers — XYZ, OSM, TileJSON, TileWMS, ImageWMS, WMTS, VectorTile and
+  Vector — added to an sMap map as they are.
+
+- Version 1.1.0, MIT licence (see `LICENSE` at the repository root)
+- OpenLayers 10 (a peer dependency)
+- ES module with types
+
+## Installation
+
+```sh
+npm install @superrouteca/smap-openlayers ol
+```
+
+```js
+import 'ol/ol.css';
+import '@superrouteca/smap/smap.css';   // popups and the Auto Zoom chooser
+```
+
+## sMap in OpenLayers
+
+```js
+import Map from 'ol/Map.js';
+import View from 'ol/View.js';
+import { fromLonLat } from 'ol/proj.js';
+import { smapLayer } from '@superrouteca/smap-openlayers';
+
+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',
+});
+
+const map = new Map({
+  target: 'map',
+  layers: [basemap /* , your OpenLayers layers */],
+  view: new View({ center: fromLonLat([-79.38, 43.65]), zoom: 12 }),
+});
+
+basemap.addPoints('stops', stops, {
+  marker: { fill: { property: 'status_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.setBasemap({ water: { color: '#9cc0e6' }, roads: { width: 1.5 } });
+basemap.setStyle('dark');
+```
+
+The layer forwards every sMap map call once its map is ready (`setStyle`, `setLanguage`, `setBasemap`,
+`setAutoZoom`, `addPoints`, `addLines`, `addPolygons`, `addData`, `setData`, `fitLayer`, `openPopup`, `closePopup`,
+`addSource`, `addStyleLayer`, `setPaint`, `setLayout`, `setFilter`, `addRasterLayer`, `addWmsLayer`, `addWmtsLayer`,
+`addVectorTiles`, `addArcGisLayer`, `loadLayers`). `setSMapVisible(id, on)` shows or hides one of the sMap map's
+layers and `removeSMapLayer(id)` removes one (OpenLayers keeps its own `setVisible`). Calls that answer a value:
+`await basemap.call('basemap')`. `await basemap.ready` (or `basemap.getSMap()`) gives the sMap map itself.
+
+How it works with OpenLayers:
+
+- The OpenLayers view owns the camera and the input; the sMap map follows it on every frame, rotation included.
+  Every move the sMap map asks for (Auto Zoom, `fitLayer`, a popup panning into view) is made by the view.
+- Clicks and pointer moves reach sMap's layers (popups, Auto Zoom, `onClick`, hover); `interactive: false` turns
+  this off. Popups sit above the map and keep their own clicks.
+- The credits are the layer's attributions in OpenLayers' attribution control (the data credit and every source you
+  add to the sMap map); the sMap badge sits above it (one per map).
+- OpenLayers' zoom levels are one above the sMap map's own. The view must be in Web Mercator (EPSG:3857, the
+  default); for other projections use raster tiles from a reprojecting source.
+- Opacity, visibility, `zIndex`, `minZoom` / `maxZoom` are OpenLayers layer options as usual.
+
+### Raster tiles
+
+```js
+import { smapRasterLayer, smapRasterSource, smapBasemap } from '@superrouteca/smap-openlayers';
+
+map.addLayer(smapRasterLayer({ apiKey: 'smk_…', style: 'grayscale', language: 'de' }));   // an XYZ tile layer
+const source = smapRasterSource({ getToken, style: 'dark' });                             // the source alone
+map.addLayer(smapBasemap({ apiKey: 'smk_…' }));   // vector where WebGL 2 exists, raster elsewhere
+```
+
+Tiles are 256 px (512 px on high-density screens, `retina`), read with the map key or token from the nearest node,
+moving to the next node when one fails. `source.setStyle()` and `source.setLanguage()` reload them. sMap also
+publishes the same tiles as TileJSON and WMTS capabilities for tools that read those.
+
+### 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`, `nearest` (default true).
+
+## OpenLayers on sMap
+
+```js
+import { Map } from '@superrouteca/smap';
+import TileLayer from 'ol/layer/Tile.js';
+import TileWMS from 'ol/source/TileWMS.js';
+import VectorTileSource from 'ol/source/VectorTile.js';
+import MVT from 'ol/format/MVT.js';
+import { addOpenLayersLayer, addOpenLayersLayers } from '@superrouteca/smap-openlayers/on-smap';
+
+const smap = new Map({ container: 'map', apiKey: 'smk_…', style: 'light' });
+await smap.ready;
+
+await addOpenLayersLayer(smap, 'radar', new TileLayer({
+  source: new TileWMS({ url: 'https://wms.example/ows', params: { LAYERS: 'radar' } }),
+  opacity: 0.6,
+}), { slot: 'roads' });
+
+await addOpenLayersLayer(smap, 'parcels', new VectorTileSource({ format: new MVT(), url: 'https://vt.example/{z}/{x}/{y}.pbf' }), {
+  layers: [{ id: 'parcels-line', type: 'line', 'source-layer': 'parcels', paint: { 'line-color': '#475569' } }],
+});
+
+// Or every layer of an existing OpenLayers map, in order:
+const { added, skipped } = await addOpenLayersLayers(smap, olMap);
+```
+
+| OpenLayers | On the sMap map |
+|---|---|
+| `XYZ`, `OSM`, `TileJSON`, `TileImage` | raster layer (`{a-c}` subdomains expanded, `{-y}` as TMS, tile size kept) |
+| `TileWMS`, `ImageWMS` | WMS layer with the source's parameters |
+| `WMTS` | raster layer when the matrix set is Web Mercator by zoom (REST or KVP), otherwise a WMTS layer read from the service |
+| `VectorTile` | vector tiles drawn by the Style Specification layers you give in `layers` (OpenLayers style functions have no counterpart) |
+| `Vector` | the features as GeoJSON in WGS 84, points, lines and areas as `<id>`, `<id>:lines`, `<id>:areas`; a layer's fixed `Style` becomes their colours; sMap layer options (`popup`, `marker`, …) apply |
+
+A layer's opacity, zoom range and the source's attributions come along. Without `slot` or `before` a layer draws on
+top, in the order added. `addOpenLayersLayers` skips an sMap basemap already in the OpenLayers map and lists what it
+could not add in `skipped`.
+
+## Example
+
+`examples/index.html` shows both ways. Serve the repository root (for example `npx serve .`) and open
+`/openlayers/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,97 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>sMap for OpenLayers</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.11.0/ol.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 /openlayers/examples/?key=smk_… -->
+  <script type="importmap">
+  {
+    "imports": {
+      "ol/": "https://cdn.jsdelivr.net/npm/ol@10.11.0/",
+      "@superrouteca/smap": "../../js/dist/smap.mjs",
+      "@superrouteca/smap/client": "../../js/dist/smap-client.mjs",
+      "@superrouteca/smap-openlayers": "../src/index.js",
+      "@superrouteca/smap-openlayers/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="raster"> Raster tiles</label>
+    <button id="rotate">Rotate</button>
+  </div>
+  <h2>sMap in OpenLayers (left) · OpenLayers sources on an sMap map (right)</h2>
+  <div class="maps"><div id="ol"></div><div id="smap"></div></div>
+  <script type="module">
+    import OlMap from 'ol/Map.js';
+    import View from 'ol/View.js';
+    import VectorLayer from 'ol/layer/Vector.js';
+    import VectorSource from 'ol/source/Vector.js';
+    import TileLayer from 'ol/layer/Tile.js';
+    import OSM from 'ol/source/OSM.js';
+    import Feature from 'ol/Feature.js';
+    import Point from 'ol/geom/Point.js';
+    import { Style, Circle, Fill, Stroke } from 'ol/style.js';
+    import { fromLonLat } from 'ol/proj.js';
+    import { Map as SMap, popupTemplate } from '@superrouteca/smap';
+    import { smapLayer, smapRasterLayer } from '@superrouteca/smap-openlayers';
+    import { addOpenLayersLayer } from '@superrouteca/smap-openlayers/on-smap';
+
+    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' },
+    ];
+
+    // ① sMap in OpenLayers
+    let base = smapLayer({ apiKey, style: 'light', language: 'en' });
+    const decorate = (layer) => layer.addPoints('stops', stops, {
+      marker: { fill: { property: 'status' }, border: '#1e293b', text: { property: 'n' } },
+      popup: popupTemplate('<b>{n}</b> {name}'),
+    });
+    decorate(base);
+    const own = new VectorLayer({
+      source: new VectorSource({ features: [new Feature(new Point(fromLonLat([-79.3817, 43.6487])))] }),
+      style: new Style({ image: new Circle({ radius: 8, fill: new Fill({ color: '#7c3aed' }), stroke: new Stroke({ color: '#fff', width: 2 }) }) }),
+    });
+    const map = new OlMap({ target: 'ol', layers: [base, own], view: new View({ center: fromLonLat([-79.387, 43.655]), zoom: 14 }) });
+
+    const scheme = document.getElementById('scheme');
+    const lang = document.getElementById('lang');
+    scheme.onchange = () => base.setStyle(scheme.value);
+    lang.onchange = () => base.setLanguage(lang.value);
+    document.getElementById('rotate').onclick = () => map.getView().animate({ rotation: map.getView().getRotation() + Math.PI / 6 });
+    document.getElementById('raster').onchange = (e) => {
+      map.removeLayer(base);
+      base = e.target.checked ? smapRasterLayer({ apiKey, style: scheme.value, language: lang.value }) : smapLayer({ apiKey, style: scheme.value, language: lang.value });
+      if (!e.target.checked) { decorate(base); }
+      map.getLayers().insertAt(0, base);
+    };
+
+    // ② OpenLayers sources on an sMap map
+    const smap = new SMap({ container: 'smap', apiKey, style: 'grayscale', language: 'en', center: [-79.387, 43.655], zoom: 12 });
+    await smap.ready;
+    await addOpenLayersLayer(smap, 'osm', new TileLayer({ source: new OSM(), opacity: 0.35 }), { slot: 'roads' });
+    await addOpenLayersLayer(smap, 'mine', new VectorLayer({
+      source: new VectorSource({ features: stops.map((s) => new Feature({ geometry: new Point(fromLonLat([s.lng, s.lat])), name: s.name })) }),
+      style: new Style({ image: new Circle({ radius: 7, fill: new Fill({ color: '#e11d48' }) }) }),
+    }), { popup: popupTemplate('{name}') });
+  </script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@superrouteca/smap-openlayers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "sMap for OpenLayers: maps from Superroute's sMap service as an OpenLayers layer (vector or raster), and OpenLayers sources and layers on an sMap map.",
+  "license": "MIT",
+  "author": "Goodneo Solutions",
+  "homepage": "https://github.com/Goodneo-Solutions/smap-sdk/tree/main/openlayers#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Goodneo-Solutions/smap-sdk.git",
+    "directory": "openlayers"
+  },
+  "keywords": [
+    "map",
+    "maps",
+    "openlayers",
+    "ol",
+    "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": {
+    "ol": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ol": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@superrouteca/smap": "1.1.1"
+  },
+  "devDependencies": {
+    "jsdom": "30.1.3",
+    "ol": "10.11.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;
+}