@superrouteca/smap-arcgis 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.1.0 — 2026-10-27
+
+- First version.
+- sMap as an ArcGIS basemap: vector tiles in sMap's style (`createSMapBasemap`, `createVectorTileLayer`; the five
+  colour schemes, custom styles and labels in any language, restyled in place) or sMap's raster tiles
+  (`createRasterTileLayer`). The map key or token on every request, the nearest map node and the next one when a node
+  fails (`installInterceptor`); the sMap badge and the OpenStreetMap credit (`addAttribution`).
+- sMap's points, pins, lines and areas as ArcGIS graphics with the SDK's options and popups (`createGraphicsLayer`).
+- ArcGIS REST services on an sMap map (`addArcGisService`): tile and vector tile services, and feature layers read as
+  GeoJSON and coloured by their renderer.

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,117 @@
-# Temporary Holding Version
+# @superrouteca/smap-arcgis
 
-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 and the [ArcGIS Maps SDK for JavaScript](https://developers.arcgis.com/javascript/) both ways:
+
+- **sMap as an ArcGIS basemap**: a `VectorTileLayer` with sMap's style and vector tiles (the five colour schemes and
+  your saved custom styles, labels in any language), or a `WebTileLayer` of sMap's raster tiles. The map key or token
+  goes on every request through ArcGIS request interceptors; requests go to the nearest map node and move to the next
+  one when a node fails; the sMap badge and the OpenStreetMap credit are shown.
+- **sMap's points, pins, lines and areas as ArcGIS graphics**, with the options of the SDK's `addPoints` / `addLines` /
+  `addPolygons` and popups as ArcGIS popups.
+- **ArcGIS REST services on an sMap map**: cached map and image services and vector tile services through the map's
+  `addArcGisLayer`, and feature layers queried as GeoJSON, coloured by their own renderer.
+
+```sh
+npm install @superrouteca/smap-arcgis @arcgis/core
+```
+
+`@arcgis/core` 5 is a peer dependency (not needed for `@superrouteca/smap-arcgis/services`). The adapter depends on
+`@superrouteca/smap` (1.1.0) for the nodes, the key and the token.
+
+## Access
+
+Every call takes the options of the sMap JS client: `apiKey` (a map key, `smk_…`, whose allowlist names your site),
+or `token` / `getToken` (short-lived tokens from your server), plus `baseUrl` (default `https://tile.srsr.ca`),
+`nodes` and `nearest`. Share one session between layers with `session: createSession({ … })`.
+
+## sMap as the basemap
+
+```js
+import Map from '@arcgis/core/Map.js';
+import MapView from '@arcgis/core/views/MapView.js';
+import { createSMapBasemap, addAttribution } from '@superrouteca/smap-arcgis';
+
+const basemap = await createSMapBasemap({ apiKey: 'smk_…', style: 'light', language: 'fr' });
+const view = new MapView({ container: 'map', map: new Map({ basemap }), center: [2.35, 48.86], zoom: 12 });
+addAttribution(view);   // the sMap badge and the OpenStreetMap credit, bottom right
+```
+
+An existing ArcGIS app switches its basemap and keeps every layer: `map.basemap = await createSMapBasemap({ … })`.
+
+- `style`: `light`, `white`, `grayscale`, `dark`, `black`, or a saved custom style `custom:sms_…`.
+- `raster: true` uses sMap's raster tiles (a `WebTileLayer`, `retina: true` for 512 px images): the exact sMap look
+  wherever vector tiles are not wanted, and in a `SceneView` as draped imagery.
+- `basemap: { pois: { visible: false }, roads: { color: '#ffffff' } }` shows, hides and recolours the basemap by
+  class (vector), as the sMap map's `setBasemap`.
+- `basemap.smap.setStyle(style)` / `setLanguage(language)` / `setBasemap(overrides)` (vector) restyle the layer in
+  place.
+
+The layers on their own: `createVectorTileLayer(options)` and `createRasterTileLayer(options)`.
+
+### Keys, tokens and nodes
+
+`createSMapBasemap` (and the layer functions) install one request interceptor per session
+(`installInterceptor(session)`, returning `{ remove() }`): every request to an sMap node is sent to the node read from
+now, with `Authorization: Bearer <token>` and `X-SMap-Key` headers; a network error or a 5xx answer moves the session
+to the next node, so the tiles that follow come from it. A map key also travels in the style's own tile URLs, so key
+access works even where a request does not pass through the interceptors. Tokens are renewed in the background
+before they expire.
+
+ArcGIS draws the Style Specification styles it supports; sMap's schemes keep to what it reads. 3D buildings are not
+drawn by ArcGIS from vector tiles: in a `SceneView` the sMap basemap is a flat, draped layer.
+
+## sMap's layers as graphics
+
+```js
+import { createGraphicsLayer } from '@superrouteca/smap-arcgis';
+import { popupTemplate } from '@superrouteca/smap';
+
+view.map.addMany([
+  createGraphicsLayer('zones', 'areas', zones, { fill: '#2563eb', opacity: 0.2, outline: '#2563eb' }),
+  createGraphicsLayer('route', 'lines', route, { color: { property: 'color' }, width: 5 }),
+  createGraphicsLayer('stops', 'points', stops, {
+    marker: { border: { property: 'color' } }, label: 'name',
+    popup: popupTemplate('<b>{name}</b><br>{address}'), popupTitle: 'Stop',
+  }),
+]);
+```
+
+Points: circles, an icon, or pins (`pin` and `circle` shapes, fill, border); lines: colour per feature, width,
+opacity, dashes; areas: fill, outline, opacity; `minzoom` / `maxzoom` become the layer's scale range; a `label` is a
+text graphic beside each point. GeoJSON simplestyle properties colour a layer that gives no colour of its own. The
+`popup` option is each graphic's popup content (a string, a DOM node or a promise of either). Numbers inside pins,
+count badges, casings, arrows, clustering, extrusion and Auto Zoom are not drawn here; they are the sMap map's own.
+
+## ArcGIS services on an sMap map
+
+```js
+import * as sMap from '@superrouteca/smap';
+import { addArcGisService } from '@superrouteca/smap-arcgis/services';
+
+const map = new sMap.Map({ container: 'map', apiKey: 'smk_…' });
+await map.ready;
+await addArcGisService(map, 'hillshade', 'https://services.arcgisonline.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer', { slot: 'bottom' });
+await addArcGisService(map, 'parcels', 'https://example.com/arcgis/rest/services/Parcels/FeatureServer/0', {
+  token: arcgisToken, where: "zoning = 'R1'", layerOptions: { popup: sMap.popupTemplate('{address}') },
+});
+```
+
+- Cached `MapServer` / `ImageServer` and `VectorTileServer` services go through the map's
+  `addArcGisLayer(id, { url, attribution, slot, ...layerOptions })`, which reads the service (its tile size, its
+  vector tile style, and its copyright text as the default attribution).
+- One layer of a feature or map service (`…/FeatureServer/0`, `…/MapServer/2`) is queried as GeoJSON in WGS 84, page
+  by page (`maxFeatures`, default 50,000), coloured by the layer's simple or unique-value renderer, and added with
+  `map.addData` (points, lines and areas as `<id>`, `<id>:lines` and `<id>:areas`).
+- `token` is an ArcGIS token for secured services. `slot` is passed only when given; a layer without one is drawn on
+  top, in the order added.
+- Helpers: `queryFeatures(url, options)`, `serviceInfo(url)`, `parseServiceUrl(url)`, `rendererStyle`,
+  `symbolToSimplestyle`.
+
+## Example
+
+[`examples/index.html`](examples/index.html): serve the repository root (`npx serve .`) and open
+`/arcgis/examples/?key=smk_…` (`&raster=1` for raster tiles).
+
+## Licence
+
+MIT. The map data is © OpenStreetMap contributors; the credit stays visible on every map.

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@superrouteca/smap-arcgis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "sMap for the ArcGIS Maps SDK for JavaScript: sMap basemaps (vector and raster), sMap layers as graphics, and ArcGIS REST services on sMap maps.",
+  "license": "MIT",
+  "author": "Goodneo Solutions",
+  "homepage": "https://github.com/Goodneo-Solutions/smap-sdk/tree/main/arcgis#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Goodneo-Solutions/smap-sdk.git",
+    "directory": "arcgis"
+  },
+  "keywords": [
+    "map",
+    "maps",
+    "arcgis",
+    "esri",
+    "vector-tiles",
+    "smap",
+    "superroute"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./services": {
+      "types": "./types/services.d.ts",
+      "default": "./src/services.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --import ./test/setup.mjs --test test/*.test.mjs",
+    "typecheck": "tsc -p test/tsconfig.json"
+  },
+  "dependencies": {
+    "@superrouteca/smap": "1.1.0"
+  },
+  "peerDependencies": {
+    "@arcgis/core": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@arcgis/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arcgis/core": "5.1.27",
+    "typescript": "6.0.3"
+  }
+}

package/src/basemap.js

@@ -0,0 +1,170 @@
+// sMap in the ArcGIS Maps SDK for JavaScript: a VectorTileLayer with sMap's style and vector tiles (the five schemes
+// and custom styles, labels in any language), a WebTileLayer of sMap's raster tiles where vector tiles are not wanted,
+// the map key / token on every request through ArcGIS request interceptors, the nearest node with failover, and the
+// sMap badge with the OpenStreetMap credit.
+import esriConfig from '@arcgis/core/config.js';
+import Basemap from '@arcgis/core/Basemap.js';
+import VectorTileLayer from '@arcgis/core/layers/VectorTileLayer.js';
+import WebTileLayer from '@arcgis/core/layers/WebTileLayer.js';
+import { applyBasemapOverrides } from '@superrouteca/smap';
+import { createSession, ATTRIBUTION } from './session.js';
+
+const installed = new WeakMap();
+
+function escapeRegExp(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function urlsFor(session) {
+  return new RegExp('^(' + session.origins().map(escapeRegExp).join('|') + ')(/|$)');
+}
+
+/**
+ * Adds an ArcGIS request interceptor for sMap URLs: each request goes to the node read from now (so a node that
+ * failed is left), with the token and the map key as headers; a failed request moves the session to the next node.
+ * Installed once per session; returns `{ interceptor, remove() }`.
+ */
+export function installInterceptor(sessionOrOptions) {
+  const session = createSession(sessionOrOptions);
+  if (installed.has(session)) { return installed.get(session); }
+  const interceptor = {
+    urls: urlsFor(session),
+    before(params) {
+      if (!params || !params.url || !session.nodeOf(params.url)) { return undefined; }
+      params.url = session.rebase(params.url);
+      const ro = params.requestOptions || (params.requestOptions = {});
+      ro.headers = { ...(ro.headers || {}), ...session.headers() };
+      return undefined;
+    },
+    error(error) {
+      const details = (error && error.details) || {};
+      const url = details.url || (error && error.url);
+      const status = details.httpStatus || details.status || 0;
+      // 4xx answers are final (a refused key stays refused on every node); network errors and 5xx move on.
+      if (url && session.nodeOf(url) && (status === 0 || status >= 500)) { session.failed(url); }
+    },
+  };
+  const update = () => { interceptor.urls = urlsFor(session); };
+  const offNode = session.on('nodechange', update);
+  session.ready().then(update, () => {});
+  esriConfig.request.interceptors = esriConfig.request.interceptors || [];
+  esriConfig.request.interceptors.push(interceptor);
+  const handle = {
+    interceptor,
+    remove() {
+      offNode();
+      const list = esriConfig.request.interceptors;
+      const i = list.indexOf(interceptor);
+      if (i >= 0) { list.splice(i, 1); }
+      installed.delete(session);
+    },
+  };
+  installed.set(session, handle);
+  return handle;
+}
+
+/**
+ * A VectorTileLayer drawing sMap's vector tiles in a scheme or custom style, labels in `language`. The style is read
+ * through the session (nearest node, failover, key, token); tiles, fonts and sprites through the interceptor.
+ *
+ * `basemap` shows, hides and recolours classes (as the sMap map's setBasemap).
+ *
+ * @returns {Promise<VectorTileLayer>} with `smap: { session, style, language, setStyle, setLanguage, setBasemap, basemap }`
+ */
+export async function createVectorTileLayer(options = {}) {
+  const session = createSession(options.session || options);
+  installInterceptor(session);
+  await session.ready();
+  let style = options.style || 'light';
+  let language = options.language;
+  let overrides = options.basemap || null;
+  // Basemap options (contract §1: show, hide and recolour by class), applied by the SDK's own function.
+  const styled = async () => {
+    const doc = await session.style(style, language);
+    return overrides && Object.keys(overrides).length ? applyBasemapOverrides(doc, overrides) : doc;
+  };
+  const layer = new VectorTileLayer({
+    id: options.id || 'smap-vector',
+    title: options.title || 'sMap',
+    style: await styled(),
+    ...(options.layerProps || {}),
+  });
+  const reload = async () => { await layer.loadStyle(await styled()); return layer; };
+  layer.smap = {
+    session,
+    get style() { return style; },
+    get language() { return language; },
+    basemap() { return overrides ? { ...overrides } : {}; },
+    setStyle(next) { style = next; return reload(); },
+    setLanguage(next) { language = next; return reload(); },
+    setBasemap(next) { overrides = next && Object.keys(next).length ? { ...next } : null; return reload(); },
+  };
+  return layer;
+}
+
+/**
+ * A WebTileLayer of sMap's raster tiles (contract §5): the same schemes, custom styles and languages as images drawn on
+ * sMap's nodes. `retina` reads 512 px tiles (the @2x images of the same tiles, shown in the 256 px grid). The layer's
+ * copyright is the OpenStreetMap credit.
+ */
+export async function createRasterTileLayer(options = {}) {
+  const session = createSession(options.session || options);
+  installInterceptor(session);
+  await session.ready();
+  const style = options.style || 'light';
+  const urlTemplate = session.rasterTemplate(style, {
+    language: options.language,
+    retina: options.retina,
+    placeholders: { z: '{level}', x: '{col}', y: '{row}' },
+  });
+  const layer = new WebTileLayer({
+    id: options.id || 'smap-raster',
+    title: options.title || 'sMap',
+    urlTemplate,
+    copyright: ATTRIBUTION,
+    ...(options.layerProps || {}),
+  });
+  layer.smap = { session, style, language: options.language };
+  return layer;
+}
+
+/**
+ * An sMap basemap for a Map or WebMap (`map.basemap = await createSMapBasemap({ … })`): vector tiles by default,
+ * raster tiles with `raster: true`. An existing ArcGIS app switches its basemap to sMap and keeps its layers.
+ */
+export async function createSMapBasemap(options = {}) {
+  const style = options.style || 'light';
+  const layer = options.raster ? await createRasterTileLayer(options) : await createVectorTileLayer(options);
+  const basemap = new Basemap({
+    id: options.basemapId || 'smap-' + style.replace(':', '-'),
+    title: options.title || 'sMap ' + style.replace(/^custom:/, ''),
+    baseLayers: [layer],
+    thumbnailUrl: layer.smap.session.rasterTemplate(style, { language: options.language }).replace('{z}', '3').replace('{x}', '2').replace('{y}', '2'),
+  });
+  basemap.smap = layer.smap;
+  return basemap;
+}
+
+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 OpenStreetMap credit in the view's bottom-right corner (beside ArcGIS's own attribution,
+ * which stays). Returns the element.
+ */
+export function addAttribution(view, options = {}) {
+  const doc = options.document || (view.container && view.container.ownerDocument) || globalThis.document;
+  const el = doc.createElement('div');
+  el.className = 'smap-arcgis-attribution esri-widget';
+  el.setAttribute('style', 'display:flex;gap:6px;align-items:center;padding:2px 6px;font:11px/16px Helvetica,Arial,sans-serif;background:rgba(255,255,255,.8)');
+  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');
+  credit.textContent = ATTRIBUTION;
+  el.appendChild(badge);
+  el.appendChild(credit);
+  view.ui.add(el, 'bottom-right');
+  return el;
+}

package/src/graphics.js

@@ -0,0 +1,169 @@
+// sMap's points, lines and areas as an ArcGIS GraphicsLayer, with the options of the sMap SDK's addPoints / addLines /
+// addPolygons and the layer's popup as the graphics' PopupTemplate. GeoJSON simplestyle properties colour a layer that
+// gives no colour of its own.
+import Graphic from '@arcgis/core/Graphic.js';
+import GraphicsLayer from '@arcgis/core/layers/GraphicsLayer.js';
+
+const GEOMETRY_TYPES = ['Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', 'MultiPolygon', 'GeometryCollection'];
+const WGS84 = { wkid: 4326 };
+
+/** 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 [];
+}
+
+function signedArea(ring) {
+  let a = 0;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) { a += (ring[i][0] - ring[j][0]) * (ring[i][1] + ring[j][1]); }
+  return a / 2; // > 0: clockwise
+}
+
+// ArcGIS polygons: outer rings clockwise, holes counter-clockwise (GeoJSON is the other way round).
+function rings(polygon) {
+  return polygon.map((ring, i) => {
+    const cw = signedArea(ring) > 0;
+    return (i === 0) === cw ? ring : ring.slice().reverse();
+  });
+}
+
+/** GeoJSON geometry → ArcGIS geometry (autocast object, WGS 84); GeometryCollection → several. */
+export function toArcGisGeometries(g) {
+  if (!g) { return []; }
+  switch (g.type) {
+    case 'Point': return [{ type: 'point', longitude: g.coordinates[0], latitude: g.coordinates[1], spatialReference: WGS84 }];
+    case 'MultiPoint': return [{ type: 'multipoint', points: g.coordinates, spatialReference: WGS84 }];
+    case 'LineString': return [{ type: 'polyline', paths: [g.coordinates], spatialReference: WGS84 }];
+    case 'MultiLineString': return [{ type: 'polyline', paths: g.coordinates, spatialReference: WGS84 }];
+    case 'Polygon': return [{ type: 'polygon', rings: rings(g.coordinates), spatialReference: WGS84 }];
+    case 'MultiPolygon': return [{ type: 'polygon', rings: g.coordinates.flatMap(rings), spatialReference: WGS84 }];
+    case 'GeometryCollection': return (g.geometries || []).flatMap(toArcGisGeometries);
+    default: return [];
+  }
+}
+
+function read(value, props, fallback, simplestyleKey) {
+  let v;
+  if (value === undefined || value === null) { v = simplestyleKey ? props[simplestyleKey] : undefined; }
+  else if (typeof value === 'object' && !Array.isArray(value) && value.property) { v = props[value.property] ?? value.default; }
+  else if (Array.isArray(value) && value.length === 2 && value[0] === 'get') { v = props[value[1]]; }
+  else { v = value; }
+  return v === undefined || v === null ? fallback : v;
+}
+
+function pinSvg(fill, border, width, round) {
+  const svg = round
+    ? '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32"><circle cx="16" cy="16" r="' + (15 - width / 2) + '" fill="' + fill + '" stroke="' + border + '" stroke-width="' + width + '"/></svg>'
+    : '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="42" 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="' + width + '" stroke-linejoin="round"/></svg>';
+  return 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg);
+}
+
+const SIZES = { small: 8, medium: 12, large: 18 };
+
+/** The ArcGIS symbol of one feature for sMap point / line / area options. */
+export function symbolFor(kind, props, options = {}) {
+  if (kind === 'points') {
+    const mk = options.marker;
+    if (mk) {
+      const round = mk.shape === 'circle' || mk.shape === 'vehicle';
+      const size = mk.size || 32;
+      const border = read(mk.border, props, read(options.color, props, '#2563eb', 'marker-color'));
+      return {
+        type: 'picture-marker', url: pinSvg(read(mk.fill, props, '#ffffff'), border, mk.borderWidth ?? 3, round),
+        width: size * 0.75, height: (round ? size : size * 42 / 32) * 0.75, yoffset: round ? 0 : size * 42 / 32 * 0.375,
+      };
+    }
+    if (options.icon) {
+      const s = (options.iconSize || 1) * 24;
+      return { type: 'picture-marker', url: options.icon, width: s, height: s };
+    }
+    const radius = options.radius ?? (SIZES[props['marker-size']] ? SIZES[props['marker-size']] / 2 : 6);
+    return {
+      type: 'simple-marker', style: 'circle', size: radius * 1.5,
+      color: read(options.color, props, '#2563eb', 'marker-color'),
+      outline: { color: read(options.strokeColor, props, '#ffffff'), width: (options.strokeWidth ?? 2) * 0.75 },
+    };
+  }
+  if (kind === 'lines') {
+    const color = read(options.color, props, '#2563eb', 'stroke');
+    const width = options.width ?? props['stroke-width'] ?? 4;
+    const dash = Array.isArray(options.dash) && options.dash.length ? 'dash' : 'solid';
+    return { type: 'simple-line', color: withAlpha(color, options.opacity ?? props['stroke-opacity']), width: width * 0.75, style: dash, cap: 'round', join: 'round' };
+  }
+  const fill = read(options.fill ?? options.color, props, '#2563eb', 'fill');
+  return {
+    type: 'simple-fill',
+    color: withAlpha(fill, options.opacity ?? props['fill-opacity'] ?? 0.3),
+    outline: { color: read(options.outline, props, fill, 'stroke'), width: (options.outlineWidth ?? 1) * 0.75 },
+  };
+}
+
+function withAlpha(color, alpha) {
+  if (alpha === undefined || alpha === null) { return color; }
+  if (typeof color === 'string' && /^#[0-9a-f]{6}$/i.test(color)) {
+    const n = (i) => parseInt(color.slice(i, i + 2), 16);
+    return [n(1), n(3), n(5), alpha];
+  }
+  return color;
+}
+
+/**
+ * A GraphicsLayer of sMap layer data. `kind` is `points`, `lines` or `areas` (the SDK's addPoints, addLines,
+ * addPolygons options apply); the `popup` option becomes each graphic's PopupTemplate (content from the feature's
+ * attributes; a promise is awaited by the popup), and `label` a text graphic beside each point.
+ */
+export function createGraphicsLayer(id, kind, data, options = {}) {
+  if (!['points', 'lines', 'areas'].includes(kind)) { throw new Error('sMap: kind is points, lines or areas, not "' + kind + '"'); }
+  const graphics = [];
+  const want = { points: /Point$/, lines: /LineString$/, areas: /Polygon$/ }[kind];
+  for (const f of toFeatures(data)) {
+    const props = { ...(f.properties || {}) };
+    const parts = f.geometry && f.geometry.type === 'GeometryCollection' ? f.geometry.geometries || [] : [f.geometry];
+    const geometries = parts.filter((g) => g && want.test(g.type)).flatMap(toArcGisGeometries);
+    for (const geometry of geometries) {
+      const graphic = { geometry, attributes: props, symbol: symbolFor(kind, props, options) };
+      if (options.popup) {
+        graphic.popupTemplate = {
+          title: options.popupTitle || '',
+          content: (event) => {
+            const attrs = (event && event.graphic && event.graphic.attributes) || props;
+            return options.popup(attrs, f);
+          },
+        };
+      }
+      graphics.push(new Graphic(graphic));
+      if (kind === 'points' && options.label && props[options.label] != null) {
+        const right = options.labelPosition === 'right';
+        graphics.push(new Graphic({
+          geometry, attributes: props,
+          symbol: {
+            type: 'text', text: String(props[options.label]), color: '#333333', haloColor: '#ffffff', haloSize: 1.5,
+            font: { size: 9, family: 'sans-serif' }, horizontalAlignment: right ? 'left' : 'center',
+            xoffset: right ? 12 : 0, yoffset: right ? 0 : -14,
+          },
+        }));
+      }
+    }
+  }
+  const layer = new GraphicsLayer({ id, title: options.title || id, graphics, ...(options.layerProps || {}) });
+  if (options.minzoom !== undefined) { layer.minScale = zoomToScale(options.minzoom); }
+  if (options.maxzoom !== undefined) { layer.maxScale = zoomToScale(options.maxzoom); }
+  return layer;
+}
+
+/** The Web Mercator map scale at a zoom (96 dpi, 256 px tiles), for minScale / maxScale. */
+export function zoomToScale(zoom) {
+  return 591657527.591555 / Math.pow(2, zoom);
+}

package/src/index.js

@@ -0,0 +1,6 @@
+// @superrouteca/smap-arcgis — sMap and the ArcGIS Maps SDK for JavaScript both ways.
+export { Session, createSession, FLAVORS, ATTRIBUTION } from './session.js';
+export { installInterceptor, createVectorTileLayer, createRasterTileLayer, createSMapBasemap, addAttribution } from './basemap.js';
+export { createGraphicsLayer, symbolFor, toArcGisGeometries, toFeatures, zoomToScale } from './graphics.js';
+export { addArcGisService, queryFeatures, serviceInfo, parseServiceUrl, withToken, symbolToSimplestyle, rendererStyle } from './services.js';
+export const version = '1.1.0';

package/src/services.js

@@ -0,0 +1,149 @@
+// ArcGIS REST services on an sMap map (works without @arcgis/core): cached map and image services and vector tile
+// services through the map's addArcGisLayer (the SDK reads them), feature layers (FeatureServer/<n>, MapServer/<n>) queried as GeoJSON and
+// added with the map's addData, coloured from the service's own renderer (simple and unique-value renderers).
+
+const KINDS = ['MapServer', 'ImageServer', 'VectorTileServer', 'FeatureServer'];
+
+/** `{ kind, base, layerId, url }` of an ArcGIS REST service URL; kind ends in `Layer` for one layer of a service. */
+export function parseServiceUrl(url) {
+  const u = String(url).split('?')[0].replace(/\/+$/, '');
+  const m = /^(.*\/(MapServer|ImageServer|VectorTileServer|FeatureServer))(?:\/(\d+))?$/.exec(u);
+  if (!m || !KINDS.includes(m[2])) { throw new Error('sMap: not an ArcGIS REST service URL: ' + url); }
+  const layerId = m[3] === undefined ? null : Number(m[3]);
+  return { kind: layerId === null ? m[2] : m[2] + 'Layer', base: m[1], layerId, url: u };
+}
+
+/** The URL with an ArcGIS token (secured services) in its query. */
+export function withToken(url, token) {
+  if (!token) { return url; }
+  const u = new URL(url);
+  u.searchParams.set('token', token);
+  return u.toString();
+}
+
+async function getJson(url, query, options) {
+  const u = new URL(url);
+  for (const [k, v] of Object.entries(query)) { u.searchParams.set(k, v); }
+  if (options.token) { u.searchParams.set('token', options.token); }
+  const f = options.fetch || globalThis.fetch;
+  const res = await f(u.toString(), options.signal ? { signal: options.signal } : undefined);
+  if (!res.ok) { throw new Error('sMap: ArcGIS service answered HTTP ' + res.status + ' for ' + url); }
+  const body = await res.json();
+  if (body && body.error) { throw new Error('sMap: ArcGIS service error ' + (body.error.code || '') + ': ' + (body.error.message || '')); }
+  return body;
+}
+
+/** The service's (or layer's) description (`?f=json`). */
+export function serviceInfo(url, options = {}) {
+  return getJson(String(url).split('?')[0], { f: 'json' }, options);
+}
+
+function hex(color) {
+  if (!Array.isArray(color)) { return null; }
+  const h = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, '0');
+  return '#' + h(color[0]) + h(color[1]) + h(color[2]);
+}
+const alpha = (color) => (Array.isArray(color) && color.length > 3 ? Math.round((color[3] / 255) * 100) / 100 : 1);
+
+/** An ArcGIS symbol (esriSMS / esriSLS / esriSFS / esriPMS) as GeoJSON simplestyle properties. */
+export function symbolToSimplestyle(symbol) {
+  if (!symbol) { return {}; }
+  const out = {};
+  switch (symbol.type) {
+    case 'esriSMS':
+      if (hex(symbol.color)) { out['marker-color'] = hex(symbol.color); }
+      if (symbol.size) { out['marker-size'] = symbol.size <= 6 ? 'small' : symbol.size >= 14 ? 'large' : 'medium'; }
+      break;
+    case 'esriSLS':
+      if (hex(symbol.color)) { out.stroke = hex(symbol.color); out['stroke-opacity'] = alpha(symbol.color); }
+      if (symbol.width) { out['stroke-width'] = Math.round((symbol.width / 0.75) * 10) / 10; }
+      break;
+    case 'esriSFS':
+      if (hex(symbol.color)) { out.fill = hex(symbol.color); out['fill-opacity'] = alpha(symbol.color); }
+      if (symbol.outline && hex(symbol.outline.color)) {
+        out.stroke = hex(symbol.outline.color);
+        if (symbol.outline.width) { out['stroke-width'] = Math.round((symbol.outline.width / 0.75) * 10) / 10; }
+      }
+      break;
+    default:
+      break;
+  }
+  return out;
+}
+
+/** The simplestyle properties a renderer gives one feature (simple and unique-value renderers; others give none). */
+export function rendererStyle(renderer, properties) {
+  if (!renderer) { return {}; }
+  if (renderer.type === 'simple') { return symbolToSimplestyle(renderer.symbol); }
+  if (renderer.type === 'uniqueValue') {
+    const fields = [renderer.field1, renderer.field2, renderer.field3].filter(Boolean);
+    const value = fields.map((f) => (properties || {})[f]).join(renderer.fieldDelimiter || ',');
+    const hit = (renderer.uniqueValueInfos || []).find((i) => String(i.value) === value);
+    return symbolToSimplestyle(hit ? hit.symbol : renderer.defaultSymbol);
+  }
+  return {};
+}
+
+/**
+ * Every feature of a feature layer as a GeoJSON FeatureCollection in WGS 84, page by page (at most `maxFeatures`,
+ * default 50,000), each coloured by the layer's renderer unless `renderer: false`.
+ */
+export async function queryFeatures(url, options = {}) {
+  const info = parseServiceUrl(url);
+  if (info.layerId === null) { throw new Error('sMap: name one layer of the service (…/FeatureServer/0): ' + url); }
+  const layerInfo = options.renderer === false ? null : await serviceInfo(info.url, options).catch(() => null);
+  const renderer = layerInfo && layerInfo.drawingInfo ? layerInfo.drawingInfo.renderer : null;
+  const max = options.maxFeatures ?? 50000;
+  const page = options.pageSize ?? 2000;
+  const features = [];
+  for (let offset = 0; features.length < max;) {
+    const fc = await getJson(info.url + '/query', {
+      where: options.where || '1=1', outFields: options.outFields || '*', outSR: '4326', f: 'geojson',
+      resultOffset: String(offset), resultRecordCount: String(Math.min(page, max - features.length)),
+    }, options);
+    const got = (fc && fc.features) || [];
+    features.push(...got);
+    offset += got.length;
+    const more = (fc && (fc.exceededTransferLimit || (fc.properties && fc.properties.exceededTransferLimit)));
+    if (!more || got.length === 0) { break; }
+  }
+  if (renderer) {
+    for (const f of features) { f.properties = { ...rendererStyle(renderer, f.properties), ...(f.properties || {}) }; }
+  }
+  return {
+    type: 'FeatureCollection',
+    features,
+    attribution: (layerInfo && layerInfo.copyrightText) || null,
+  };
+}
+
+/**
+ * An ArcGIS REST service on an sMap map. Cached MapServer / ImageServer and VectorTileServer services go through
+ * `map.addArcGisLayer(id, { url, attribution, slot })`; one layer of a feature or map service is queried and added with
+ * `map.addData(id, features, options)` (points, lines and areas as `<id>`, `<id>:lines`, `<id>:areas`). A tile
+ * service's attribution defaults to its copyright text (read by the SDK); a feature layer's is returned (addData has
+ * no attribution option). A `slot` is passed only when given; `layerOptions` go to addArcGisLayer or addData.
+ *
+ * @returns {Promise<{ kind: string, id: string, attribution: string|null, features?: number }>}
+ */
+export async function addArcGisService(map, id, url, options = {}) {
+  const info = parseServiceUrl(url);
+  const { token, slot, attribution: givenAttribution, layerOptions, ...rest } = options;
+  if (info.layerId === null && info.kind !== 'FeatureServer') {
+    if (typeof map.addArcGisLayer !== 'function') { throw new Error('sMap: this map has no addArcGisLayer (needs @superrouteca/smap 1.1.0 or later)'); }
+    // The SDK reads the service (tile size, vector tile style, copyright text as the default attribution).
+    const call = { ...(layerOptions || {}), url: withToken(info.url, token) };
+    if (givenAttribution) { call.attribution = givenAttribution; }
+    if (slot) { call.slot = slot; }
+    await map.addArcGisLayer(id, call);
+    return { kind: info.kind, id, attribution: givenAttribution || null };
+  }
+  if (info.layerId === null) { throw new Error('sMap: name one layer of the feature service (…/FeatureServer/0): ' + url); }
+  if (typeof map.addData !== 'function') { throw new Error('sMap: this map has no addData (needs @superrouteca/smap 1.1.0 or later)'); }
+  const fc = await queryFeatures(info.url, { token, ...rest });
+  const attribution = givenAttribution ?? fc.attribution;
+  const opts = { format: 'geojson', ...(layerOptions || {}) };
+  if (slot) { opts.slot = slot; }
+  map.addData(id, { type: 'FeatureCollection', features: fc.features }, opts);
+  return { kind: info.kind, id, attribution: attribution || null, features: fc.features.length };
+}

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 || {});
+}

package/types/index.d.ts

@@ -0,0 +1,108 @@
+// Types of @superrouteca/smap-arcgis.
+import type Basemap from '@arcgis/core/Basemap.js';
+import type VectorTileLayer from '@arcgis/core/layers/VectorTileLayer.js';
+import type WebTileLayer from '@arcgis/core/layers/WebTileLayer.js';
+import type GraphicsLayer from '@arcgis/core/layers/GraphicsLayer.js';
+import type SMapClient from '@superrouteca/smap/client';
+import type { LayerData, PointOptions, LineOptions, PolygonOptions, GeoJSONFeature, BasemapOverrides } from '@superrouteca/smap';
+
+export * from './services.js';
+
+/** A colour scheme, or a saved custom style as `custom:<id>`. */
+export type StyleName = 'light' | 'white' | 'grayscale' | 'dark' | 'black' | `custom:${string}`;
+
+/** How the adapter reaches sMap: the JS client's options, or a client of your own. */
+export interface SessionOptions {
+  /** The public sMap address (default https://tile.srsr.ca). */
+  baseUrl?: string;
+  /** A map key (`smk_…`). */
+  apiKey?: string;
+  token?: string;
+  /** Called at start and again before each token expires. */
+  getToken?: () => string | Promise<string>;
+  nodes?: string[];
+  nearest?: boolean;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  client?: SMapClient;
+}
+
+/** One connection to sMap: nearest node, failover, key and token (through the JS client), and the URLs tools need. */
+export declare class Session {
+  constructor(options?: SessionOptions);
+  readonly client: SMapClient;
+  readonly baseUrl: string;
+  readonly apiKey: string | null;
+  ready(): Promise<this>;
+  node(): string;
+  nodes(): string[];
+  token(): string | null;
+  headers(): Record<string, string>;
+  origins(): string[];
+  nodeOf(url: string): string | null;
+  pathOf(url: string): string | null;
+  rebase(url: string): string;
+  failed(urlOrNode: string): boolean;
+  styleUrl(style?: StyleName, language?: string): string;
+  tileJsonUrl(source?: string): string;
+  rasterTemplate(style?: StyleName, options?: { language?: string; retina?: boolean; placeholders?: { z?: string; x?: string; y?: string } }): string;
+  rasterTileJsonUrl(style?: StyleName, options?: { language?: string }): string;
+  wmtsCapabilitiesUrl(): string;
+  fetch(url: string, init?: RequestInit): Promise<Response>;
+  style(style?: StyleName, language?: string): Promise<Record<string, unknown>>;
+  on(type: 'nodechange' | 'token', fn: (value: string | null) => void): () => void;
+  off(type: 'nodechange' | 'token', fn: (value: string | null) => void): void;
+  close(): void;
+}
+export declare function createSession(options?: SessionOptions | Session): Session;
+export declare const FLAVORS: Array<'light' | 'white' | 'grayscale' | 'dark' | 'black'>;
+export declare const ATTRIBUTION: string;
+export declare const version: string;
+
+export interface InterceptorHandle {
+  interceptor: { urls: RegExp; before(params: any): undefined; error(error: any): void };
+  remove(): void;
+}
+export declare function installInterceptor(session: Session | SessionOptions): InterceptorHandle;
+
+interface LayerCommon extends SessionOptions {
+  session?: Session;
+  style?: StyleName;
+  /** Label language (BCP 47). */
+  language?: string;
+  id?: string;
+  title?: string;
+  /** Other properties of the ArcGIS layer. */
+  layerProps?: Record<string, unknown>;
+}
+export interface SMapLayerInfo {
+  session: Session;
+  readonly style: StyleName;
+  readonly language?: string;
+}
+export interface SMapVectorInfo extends SMapLayerInfo {
+  setStyle(style: StyleName): Promise<VectorTileLayer>;
+  setLanguage(language: string): Promise<VectorTileLayer>;
+  /** Basemap options by class (contract §1), replacing the previous ones; `{}` clears. */
+  setBasemap(overrides: BasemapOverrides): Promise<VectorTileLayer>;
+  basemap(): BasemapOverrides;
+}
+export declare function createVectorTileLayer(options?: LayerCommon & { basemap?: BasemapOverrides }): Promise<VectorTileLayer & { smap: SMapVectorInfo }>;
+export declare function createRasterTileLayer(options?: LayerCommon & { retina?: boolean }): Promise<WebTileLayer & { smap: SMapLayerInfo }>;
+export declare function createSMapBasemap(options?: LayerCommon & { raster?: boolean; retina?: boolean; basemapId?: string; basemap?: BasemapOverrides }): Promise<Basemap & { smap: SMapLayerInfo | SMapVectorInfo }>;
+export declare function addAttribution(view: { ui: { add(el: HTMLElement, position: string): void }; container?: HTMLElement | null }, options?: { document?: Document }): HTMLElement;
+
+export type GraphicsKind = 'points' | 'lines' | 'areas';
+export interface GraphicsExtras {
+  /** Title of the popup (the `popup` option gives its content). */
+  popupTitle?: string;
+  title?: string;
+  layerProps?: Record<string, unknown>;
+}
+export declare function createGraphicsLayer(id: string, kind: 'points', data: LayerData, options?: PointOptions & GraphicsExtras): GraphicsLayer;
+export declare function createGraphicsLayer(id: string, kind: 'lines', data: LayerData, options?: LineOptions & GraphicsExtras): GraphicsLayer;
+export declare function createGraphicsLayer(id: string, kind: 'areas', data: LayerData, options?: PolygonOptions & GraphicsExtras): GraphicsLayer;
+export declare function symbolFor(kind: GraphicsKind, properties: Record<string, unknown>, options?: Record<string, unknown>): Record<string, unknown>;
+export declare function toArcGisGeometries(geometry: { type: string; coordinates?: unknown; geometries?: unknown[] } | null | undefined): Array<Record<string, unknown>>;
+export declare function toFeatures(data: LayerData): GeoJSONFeature[];
+export declare function zoomToScale(zoom: number): number;

package/types/services.d.ts

@@ -0,0 +1,46 @@
+// Types of @superrouteca/smap-arcgis/services (ArcGIS REST services on an sMap map; no @arcgis/core needed).
+import type { Map as SMapMap } from '@superrouteca/smap';
+
+export interface ServiceUrl {
+  kind: 'MapServer' | 'ImageServer' | 'VectorTileServer' | 'FeatureServer' | 'MapServerLayer' | 'FeatureServerLayer' | 'ImageServerLayer' | 'VectorTileServerLayer';
+  base: string;
+  layerId: number | null;
+  url: string;
+}
+export interface RequestOptions {
+  /** An ArcGIS token for secured services. */
+  token?: string;
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+}
+export interface QueryOptions extends RequestOptions {
+  where?: string;
+  outFields?: string;
+  /** Most features read (default 50,000). */
+  maxFeatures?: number;
+  /** Features per request (default 2,000). */
+  pageSize?: number;
+  /** Colour features by the layer's renderer (default true). */
+  renderer?: boolean;
+}
+export interface AddServiceOptions extends QueryOptions {
+  /** Credit shown beside the OpenStreetMap credit (default: the service's copyright text). */
+  attribution?: string;
+  /** Where the layer sits on the basemap; passed only when given. */
+  slot?: 'bottom' | 'roads' | 'labels' | 'top';
+  /** Options for addArcGisLayer (tile services: opacity, minzoom, maxzoom, layers, …) or addData (feature layers: colours, popups, … as for addPoints / addLines / addPolygons). */
+  layerOptions?: Record<string, unknown>;
+}
+export interface FeatureCollectionWithAttribution {
+  type: 'FeatureCollection';
+  features: Array<{ type: 'Feature'; properties: Record<string, unknown> | null; geometry: unknown }>;
+  attribution: string | null;
+}
+
+export declare function parseServiceUrl(url: string): ServiceUrl;
+export declare function withToken(url: string, token?: string): string;
+export declare function serviceInfo(url: string, options?: RequestOptions): Promise<Record<string, any>>;
+export declare function symbolToSimplestyle(symbol: Record<string, any> | null | undefined): Record<string, string | number>;
+export declare function rendererStyle(renderer: Record<string, any> | null | undefined, properties: Record<string, unknown> | null | undefined): Record<string, string | number>;
+export declare function queryFeatures(url: string, options?: QueryOptions): Promise<FeatureCollectionWithAttribution>;
+export declare function addArcGisService(map: SMapMap, id: string, url: string, options?: AddServiceOptions): Promise<{ kind: string; id: string; attribution: string | null; features?: number }>;