@superrouteca/smap 1.1.6 → 1.1.7

package/dist/smap.mjs

@@ -1,5 +1,5 @@
 /* Generated by js/build.mjs from js/src (see SOURCE.json). Do not edit. */
-/*! sMap Web SDK 1.1.6. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
+/*! sMap Web SDK 1.1.7. Bundles maplibre-gl 6.16.0 (BSD-3-Clause), see vendor-licenses.txt. */
 
 var smapCore = null;
 function smapCreateEngine() {
@@ -28363,6 +28363,24 @@ function smapCreatePlan() {
   // its Origin; a native app also names itself with X-SMap-App (and X-SMap-App-Cert on Android).
 
   var DEFAULT_BASE = 'https://open.superroute.ca';
+  // The sMap service a map key's configuration is read from (GET <smap>/plan/v1/config), unless the editor is told another.
+  var DEFAULT_SMAP = 'https://tile.srsr.ca';
+  // Fast path (OPEN-ROUTE-EDIT E19, §2f.5): a call there not answered within this long is repeated on the standard path.
+  // Per call, in this one place: every call 2 s, except refine (its search runs up to 2 s inside sRoad, and sMap's own
+  // refine budget is 4 s) 5 s.
+  var FAST_PATH_TIMEOUT_MS = 2000;
+  var FAST_PATH_REFINE_TIMEOUT_MS = 5000;
+  /** The fast-path time limit of a call (`path` after /v1/plan), from the defaults or the options that replace them. */
+  function fastPathTimeoutFor(path, o) {
+    var refine = path === '/refine';
+    var given = refine ? o.fastPathRefineTimeout : o.fastPathTimeout;
+    if (typeof given === 'number' && given > 0) { return given; }
+    return refine ? FAST_PATH_REFINE_TIMEOUT_MS : FAST_PATH_TIMEOUT_MS;
+  }
+  // A map key's configuration is kept this long; one that could not be read is asked for again after RETRY.
+  var KEY_CONFIG_TTL_MS = 600000;
+  var KEY_CONFIG_RETRY_MS = 60000;
+  var PLAN_PREFIX = '/v1/plan';
   // A token whose expiry can be read is renewed this many seconds before it ends.
   var RENEW_BEFORE = 30;
   var TOKEN_PREFIX = 'sr_pet_';
@@ -28385,19 +28403,27 @@ function smapCreatePlan() {
   /**
    * What a token provider gave: the token string, or the token answer of POST /v1/plan/token
    * ({ access_token, token_type, expires_in, expires_at, scopes, origins }, or that answer's `{ data }` envelope).
-   * Returns { token, exp } with exp in Unix seconds (0 when it cannot be told).
+   * Returns { token, exp, fastPath } with exp in Unix seconds (0 when it cannot be told) and fastPath the answer's
+   * `fast_path.url` (null without one: every call goes to the standard path).
    */
   function readToken(t) {
     if (t && typeof t === 'object' && t.data && typeof t.data === 'object' && !t.access_token) { t = t.data; }
-    if (typeof t === 'string' && t) { return { token: t, exp: tokenExpiry(t) }; }
+    if (typeof t === 'string' && t) { return { token: t, exp: tokenExpiry(t), fastPath: null }; }
     if (t && typeof t === 'object' && typeof t.access_token === 'string' && t.access_token) {
       var exp = t.expires_at ? Date.parse(t.expires_at) / 1000 : 0;
       if (!exp && typeof t.expires_in === 'number') { exp = Date.now() / 1000 + t.expires_in; }
-      return { token: t.access_token, exp: exp || tokenExpiry(t.access_token) };
+      return { token: t.access_token, exp: exp || tokenExpiry(t.access_token), fastPath: fastPathOf(t) };
     }
     return null;
   }
 
+  /** The fast-path address of a token answer or a map key's configuration (`fast_path.url`), or null. */
+  function fastPathOf(o) {
+    var f = o && typeof o === 'object' ? o.fast_path : null;
+    var url = f && typeof f === 'object' && typeof f.url === 'string' ? f.url.replace(/\/+$/, '') : '';
+    return url ? url : null;
+  }
+
   /** The app headers of a native app: options.app is 'android:<package>' / 'apple:<bundle id>' / 'windows:<id>', or { id, cert }. */
   function appHeaders(app) {
     var h = {};
@@ -28416,6 +28442,7 @@ function smapCreatePlan() {
     if (c && typeof c.token === 'function') {
       var token = null;
       var exp = 0;
+      var fast = null;
       var pending = null;
       var fetchToken = function () {
         if (!pending) {
@@ -28425,6 +28452,7 @@ function smapCreatePlan() {
             if (!read) { throw new Error('sMap plan editor: the token provider gave no token'); }
             token = read.token;
             exp = read.exp;
+            fast = read.fastPath;
             return token;
           }, function (e) { pending = null; throw e; });
         }
@@ -28438,6 +28466,8 @@ function smapCreatePlan() {
         },
         // After a 401 SESSION_EXPIRED: forget the token so the next call asks the provider again. True when a retry may help.
         renew: function () { token = null; exp = 0; return true; },
+        // The fast-path address the latest token answer gave (read after headers()), or null.
+        fastPath: function () { return Promise.resolve(fast); },
       };
     }
     if (c && typeof c.key === 'string' && c.key) {
@@ -28445,6 +28475,7 @@ function smapCreatePlan() {
         kind: 'key',
         headers: function () { return Promise.resolve({ Authorization: 'Bearer ' + c.key }); },
         renew: function () { return false; },
+        fastPath: null, // set by the transport: the key's configuration on sMap
       };
     }
     throw new Error('sMap plan editor: credentials are { token: () => Promise<string | TokenAnswer> } or { key: string }');
@@ -28467,44 +28498,155 @@ function smapCreatePlan() {
   function cancelled() { var e = new Error('cancelled'); e.name = 'AbortError'; e.cancelled = true; return e; }
 
   /**
-   * The transport: send(method, path, body, signal) resolves { status, body, data, matrix } (matrix: the X-Plan-Matrix
-   * header) or rejects with a PlanError. A 401 SESSION_EXPIRED with a token provider asks for a new token and repeats
-   * the call once; every other refusal (SESSION_REVOKED, TOKEN_INVALID, 403 NOT_AUTHORIZED with its reason) is raised.
+   * The transport: send(method, path, body, signal) resolves { status, body, data, matrix, path } (matrix: the
+   * X-Plan-Matrix header; path: 'fast' or 'standard', where the answer came from) or rejects with a PlanError. A 401
+   * SESSION_EXPIRED with a token provider asks for a new token and repeats the call once; every other refusal
+   * (SESSION_REVOKED, TOKEN_INVALID, 403 NOT_AUTHORIZED with its reason) is raised.
+   *
+   * Fast path (OPEN-ROUTE-EDIT E19, §2f.5): when the credential names a fast-path address (the token answer's
+   * `fast_path.url`, or a map key's configuration from GET <smapUrl>/plan/v1/config), each call goes to
+   * <url>/<same path> with the same method, credential, headers and body. A 409 USE_STANDARD_PATH (or the header
+   * X-Plan-Path: standard), any 5xx, a network error or no answer within 2 s (refine: 5 s) repeats the same call once on the standard
+   * path (<baseUrl>/v1/plan/<same path>); the next call tries the fast path again. 402, 429 and every other 4xx are final.
    */
   function createTransport(o) {
     o = o || {};
     var base = String(o.baseUrl || DEFAULT_BASE).replace(/\/$/, '');
+    var smap = String(o.smapUrl || DEFAULT_SMAP).replace(/\/$/, '');
+    var fastOn = o.fastPath !== false;
+    var timeoutMs = fastPathTimeoutFor('', o);
     var creds = credentialsOf(o.credentials);
     var app = appHeaders(o.app);
     var fetchFn = o.fetch || (typeof fetch === 'function' ? function (url, init) { return fetch(url, init); } : null);
     if (!fetchFn) { throw new Error('sMap plan editor: no fetch; pass options.fetch'); }
 
+    function headersWith(h, json) {
+      var headers = { Accept: 'application/json' };
+      Object.keys(app).forEach(function (k) { headers[k] = app[k]; });
+      Object.keys(h).forEach(function (k) { headers[k] = h[k]; });
+      if (json) { headers['Content-Type'] = 'application/json'; }
+      return headers;
+    }
+
+    // One request, read to the end. With `limit` it gives up after that many ms ({ timedOut: true }); a network error
+    // resolves { failed: error } unless the caller's own signal ended it (then it rejects, cancelled).
+    function exchange(url, init, signal, limit) {
+      if (!limit) {
+        return fetchFn(url, init).then(read);
+      }
+      var inner = newController();
+      var timedOut = false;
+      var timer = null;
+      var onAbort = function () { if (inner) { inner.abort(); } };
+      if (signal) {
+        if (signal.aborted) { return Promise.reject(cancelled()); }
+        if (signal.addEventListener) { signal.addEventListener('abort', onAbort); }
+      }
+      var own = {};
+      Object.keys(init).forEach(function (k) { own[k] = init[k]; });
+      if (inner) { own.signal = inner.signal; }
+      var done = function () {
+        if (timer) { clearTimeout(timer); }
+        if (signal && signal.removeEventListener) { signal.removeEventListener('abort', onAbort); }
+      };
+      var timeout = new Promise(function (resolve) {
+        timer = setTimeout(function () { timedOut = true; if (inner) { inner.abort(); } resolve({ timedOut: true }); }, limit);
+      });
+      var answer = Promise.resolve().then(function () { return fetchFn(url, own); }).then(read).then(function (r) { return r; }, function (e) {
+        if (signal && signal.aborted) { throw cancelled(); }
+        if (timedOut) { return { timedOut: true }; }
+        return { failed: e };
+      });
+      return Promise.race([answer, timeout]).then(function (r) {
+        done();
+        if (signal && signal.aborted) { throw cancelled(); }
+        return r;
+      }, function (e) { done(); throw e; });
+    }
+
+    function read(res) {
+      return res.text().then(function (text) {
+        var json = null;
+        try { json = text ? JSON.parse(text) : null; } catch (e) { json = null; }
+        var get = function (k) { return res.headers && typeof res.headers.get === 'function' ? res.headers.get(k) : null; };
+        return { status: res.status, ok: res.ok, json: json, matrix: get('X-Plan-Matrix'), planPath: get('X-Plan-Path') };
+      });
+    }
+
+    // A map key's configuration on sMap: GET <smap>/plan/v1/config -> {"fast_path": {"url"}} or {}.
+    var keyConfig = { url: null, until: 0, pending: null };
+    function keyFastPath(h) {
+      if (Date.now() < keyConfig.until) { return Promise.resolve(keyConfig.url); }
+      if (keyConfig.pending) { return keyConfig.pending; }
+      keyConfig.pending = exchange(smap + '/plan/v1/config', { method: 'GET', headers: headersWith(h, false) }, null, timeoutMs).then(function (r) {
+        if (r.status >= 200 && r.status < 300) {
+          keyConfig.url = fastPathOf(r.json);
+          keyConfig.until = Date.now() + KEY_CONFIG_TTL_MS;
+        } else {
+          // A refusal is an answer (no fast path for this key); a failure is asked again after a minute.
+          keyConfig.url = null;
+          keyConfig.until = Date.now() + (r.status >= 400 && r.status < 500 ? KEY_CONFIG_TTL_MS : KEY_CONFIG_RETRY_MS);
+        }
+        return keyConfig.url;
+      }, function () {
+        keyConfig.url = null;
+        keyConfig.until = Date.now() + KEY_CONFIG_RETRY_MS;
+        return null;
+      }).then(function (url) { keyConfig.pending = null; return url; });
+      return keyConfig.pending;
+    }
+
+    function fastPathFor(h) {
+      if (!fastOn) { return Promise.resolve(null); }
+      return creds.fastPath ? creds.fastPath() : keyFastPath(h);
+    }
+
+    // Repeat on the standard path (§2f.5)?
+    function useStandard(r) {
+      if (r.timedOut || r.failed) { return true; }
+      if (r.status >= 500) { return true; }
+      if (r.status !== 409) { return false; }
+      return !!(r.json && r.json.error && r.json.error.code === 'USE_STANDARD_PATH') || String(r.planPath || '').toLowerCase() === 'standard';
+    }
+
     function send(method, path, body, signal, retried) {
-      return creds.headers().then(function (h) {
-        var headers = { Accept: 'application/json' };
-        Object.keys(app).forEach(function (k) { headers[k] = app[k]; });
-        Object.keys(h).forEach(function (k) { headers[k] = h[k]; });
-        var init = { method: method, headers: headers };
-        if (body !== undefined) { headers['Content-Type'] = 'application/json'; init.body = JSON.stringify(body); }
-        if (signal) { init.signal = signal; }
-        return fetchFn(base + path, init);
-      }).then(function (res) {
-        return res.text().then(function (text) {
-          var json = null;
-          try { json = text ? JSON.parse(text) : null; } catch (e) { json = null; }
-          var matrix = res.headers && typeof res.headers.get === 'function' ? res.headers.get('X-Plan-Matrix') : null;
-          if (!res.ok) {
-            var err = (json && json.error) || {};
-            if (res.status === 401 && err.code === 'SESSION_EXPIRED' && !retried && creds.renew()) { return send(method, path, body, signal, true); }
-            throw PlanError(err.message || ('HTTP ' + res.status), {
-              status: res.status, code: err.code || null, details: err.details || null, reason: err.reason || (json && json.reason) || null, path: path,
-            });
-          }
-          return { status: res.status, body: json, data: json && json.data, matrix: matrix };
+      var h = null;
+      return creds.headers().then(function (got) {
+        h = got;
+        return fastPathFor(h);
+      }).then(function (fast) {
+        if (signal && signal.aborted) { throw cancelled(); }
+        var init = { method: method, headers: headersWith(h, body !== undefined) };
+        if (body !== undefined) { init.body = JSON.stringify(body); }
+        var standard = function () {
+          var s = {};
+          Object.keys(init).forEach(function (k) { s[k] = init[k]; });
+          s.headers = headersWith(h, body !== undefined);
+          if (signal) { s.signal = signal; }
+          return exchange(base + path, s, signal, 0).then(function (r) { r.via = 'standard'; return r; });
+        };
+        if (!fast || path.indexOf(PLAN_PREFIX + '/') !== 0) { return standard(); }
+        var rest = path.slice(PLAN_PREFIX.length);
+        return exchange(fast + rest, init, signal, fastPathTimeoutFor(rest, o)).then(function (r) {
+          if (useStandard(r)) { return standard(); }
+          r.via = 'fast';
+          return r;
         });
+      }).then(function (r) {
+        if (!r.ok) {
+          var json = r.json;
+          var err = (json && json.error) || {};
+          if (r.status === 401 && err.code === 'SESSION_EXPIRED' && !retried && creds.renew()) { return send(method, path, body, signal, true); }
+          var e = PlanError(err.message || ('HTTP ' + r.status), {
+            status: r.status, code: err.code || null, details: err.details || null, reason: err.reason || (json && json.reason) || null, path: path,
+          });
+          e.via = r.via;
+          throw e;
+        }
+        return { status: r.status, body: r.json, data: r.json && r.json.data, matrix: r.matrix, path: r.via };
       });
     }
-    return { send: send, kind: creds.kind, baseUrl: base };
+    return { send: send, kind: creds.kind, baseUrl: base, smapUrl: smap };
   }
 
   // ------------------------------------------------------------------ plans
@@ -28657,7 +28799,12 @@ function smapCreatePlan() {
    * @param {Object} options
    * @param {Object} options.credentials   { token: () => Promise<string | TokenAnswer> } or { key: string }
    * @param {string|Object} [options.app]  a native app's identity: 'android:<package>' / 'apple:<bundle id>' / 'windows:<id>', or { id, cert }
-   * @param {string} [options.baseUrl]     the Open Platform (default https://open.superroute.ca)
+   * @param {string} [options.baseUrl]     the Open Platform (default https://open.superroute.ca): the standard path
+   * @param {string} [options.smapUrl]     the sMap service a map key's configuration is read from (default
+   *                                       https://tile.srsr.ca; map.planEditor passes the map's own sMap address)
+   * @param {boolean} [options.fastPath=true]  use the fast path when the credential names one (false: standard only)
+   * @param {number} [options.fastPathTimeout=2000]  ms a fast-path call may take before it is repeated on the standard path
+   * @param {number} [options.fastPathRefineTimeout=5000]  the same for refine (its search takes longer)
    * @param {Function} [options.fetch]     fetch to use (default the page's)
    * @param {Object} [options.plan]        the starting plan: { vehicles, jobs, routes, region?, profile?, departed_at? }
    * @param {string} [options.region]      used when the plan names none
@@ -28693,6 +28840,7 @@ function smapCreatePlan() {
     this._opening = null;
     this._openingKey = null;
     this._matrixRetryAt = 0;
+    this._path = null;
     this._destroyed = false;
     if (options.plan) { this.setPlan(options.plan).catch(function () {}); }
   }
@@ -28761,7 +28909,7 @@ function smapCreatePlan() {
     return {
       plan: this.getPlan(), result: this.getResult(), busy: this._busy, error: this._error, canUndo: this.canUndo(),
       canRedo: this.canRedo(), choices: clone(this._choices), locked: this.locked(), last: clone(this._last),
-      preview: this._previewResult ? clone(this._previewResult) : null,
+      preview: this._previewResult ? clone(this._previewResult) : null, path: this._path,
     };
   };
 
@@ -28971,7 +29119,7 @@ function smapCreatePlan() {
     var e = this._history[this._at] || {};
     this._emit('change', {
       kind: kind, plan: this.getPlan(), result: this.getResult(), answer: this._last ? clone(this._last.answer) : null,
-      pending: !e.result, canUndo: this.canUndo(), canRedo: this.canRedo(),
+      pending: !e.result, canUndo: this.canUndo(), canRedo: this.canRedo(), path: this._path,
     });
   };
 
@@ -29071,7 +29219,7 @@ function smapCreatePlan() {
       self._error = null;
       self._setBusy(false);
       if (self._history[self._at] === target || kind !== 'recost') { self._changed(kind); }
-      return { kind: kind, plan: self.getPlan(), result: self.getResult(), answer: clone(answer) };
+      return { kind: kind, plan: self.getPlan(), result: self.getResult(), answer: clone(answer), path: self._path };
     }, function (err) {
       var current = self._inflight === ticket;
       if (current) { self._inflight = null; self._setBusy(false); }
@@ -29102,6 +29250,7 @@ function smapCreatePlan() {
       if (matrix) { body.matrix = matrix; } else { delete body.matrix; }
       return self._transport.send('POST', path, body, signal);
     }).then(function (res) {
+      if (!self._destroyed) { self._path = res.path || null; }
       if (body.matrix) { self._snapshotSeen(res.matrix, body.matrix); }
       return res;
     }, function (err) {
@@ -29153,7 +29302,7 @@ function smapCreatePlan() {
       }
       self._matrixRetryAt = 0;
       if (self._openingKey === key) { self._matrix = id; self._matrixKey = key; }
-      self._emit('snapshot', { status: 'opened', matrix: id, expires_at: res.data.expires_at || null, node: res.data.node || null });
+      self._emit('snapshot', { status: 'opened', matrix: id, expires_at: res.data.expires_at || null, node: res.data.node || null, path: res.path || null });
       return id;
     }, function (err) {
       self._matrixRetryAt = Date.now() + SNAPSHOT_RETRY_MS;
@@ -29889,7 +30038,7 @@ function smapCreatePlan() {
    */
   function attach(map, options) {
     options = options || {};
-    var editor = new PlanEditor(Object.assign({}, options, { plan: null }));
+    var editor = new PlanEditor(Object.assign({}, options, { plan: null, smapUrl: options.smapUrl || map._base }));
     var layer = attachToMap(map, editor, options);
     var toolId = null;
     var destroyed = false;
@@ -29975,7 +30124,7 @@ function smapCreateSdk(engine, interop, plan) {
 })(typeof self !== 'undefined' ? self : this, function (engine, interop, plan) {
   'use strict';
 
-  var VERSION = '1.1.6';
+  var VERSION = '1.1.7';
   var FLAVORS = ['light', 'white', 'grayscale', 'dark', 'black'];
   var BASEMAP_SOURCE = 'basemap';
   var BUILDINGS_LAYER = 'smap-buildings-3d';
@@ -32293,7 +32442,7 @@ function SMapMap(options) {
   SMapMap.prototype = core.Map.prototype;
   return new core.Map(options);
 }
-var smapVersion = "1.1.6";
+var smapVersion = "1.1.7";
 var smapStyles = ['light', 'white', 'grayscale', 'dark', 'black'];
 /** The bundled rendering engine, for anything the SDK does not wrap (loaded on the first call). */
 function smapGetEngine() { return smapLoad().engine; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superrouteca/smap",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "sMap for the web: maps from Superroute's sMap service, the Web SDK (map view) and the JS client (tokens, nearest node, styles, tiles).",
   "license": "MIT",
   "author": "Goodneo Solutions",

package/types/smap.d.cts

@@ -640,7 +640,11 @@ export interface PlanTokenAnswer {
   expires_at?: string;
   scopes?: string[];
   origins?: string[] | null;
+  /** Present when the client's plan calls take the fast path (OPEN-ROUTE-EDIT E19): the editor sends its calls there. */
+  fast_path?: { url: string };
 }
+/** Where a plan call was answered: the fast path through sMap, or the Open Platform's standard path. */
+export type PlanPath = 'fast' | 'standard';
 /**
  * How plan calls are authorised, always as `Authorization: Bearer …`: a short-lived plan editor token from your own
  * server (asked again 30 s before its `expires_at` and once after a 401 `SESSION_EXPIRED`), or a map key (`smk_…`)
@@ -750,6 +754,8 @@ export interface PlanChangeEvent {
   pending: boolean;
   canUndo: boolean;
   canRedo: boolean;
+  /** Where the last answered call was answered (null before the first answer). */
+  path?: PlanPath | null;
 }
 export interface PlanEditorError extends Error {
   status: number;
@@ -758,6 +764,8 @@ export interface PlanEditorError extends Error {
   details: unknown;
   /** Why, where the service says (`expired`, `key_revoked`, `entitlements_changed`, `origin_not_allowed`, `plan_editing_off`, …). */
   reason: string | null;
+  /** Where the refusal came from, when it was an answer. */
+  via?: PlanPath;
 }
 export interface PlanSnapshotEvent {
   /** `opened`, `failed` (calls go on without one), or the X-Plan-Matrix of an answer: `used`, `expired`, `unavailable`, `mismatch`. */
@@ -766,10 +774,12 @@ export interface PlanSnapshotEvent {
   expires_at?: string | null;
   node?: string | null;
   error?: unknown;
+  /** With `opened`: the path that opened it (the id is the same on both paths). */
+  path?: PlanPath | null;
 }
 export interface PlanPreview { routes: PlanRoute[]; result: PlanResult }
 /** An edit's outcome; null when a newer edit cancelled it. */
-export interface PlanEditOutcome { kind: string; plan: PlanState; result: PlanResult; answer: unknown }
+export interface PlanEditOutcome { kind: string; plan: PlanState; result: PlanResult; answer: unknown; path?: PlanPath | null }
 export interface PlanEditorState {
   plan: PlanState | null;
   result: PlanResult | null;
@@ -781,6 +791,8 @@ export interface PlanEditorState {
   locked: string[];
   last: { kind: string; answer: unknown } | null;
   preview: PlanPreview | null;
+  /** Where the last answered call was answered (null before the first answer). */
+  path?: PlanPath | null;
 }
 
 export interface PlanEditorOptions {
@@ -792,6 +804,17 @@ export interface PlanEditorOptions {
   app?: string | { id: string; cert?: string };
   /** The Open Platform, `https://open.superroute.ca` by default. */
   baseUrl?: string;
+  /**
+   * The sMap service a map key's configuration is read from (`GET <smapUrl>/plan/v1/config`), `https://tile.srsr.ca`
+   * by default; `map.planEditor` passes the map's own sMap address.
+   */
+  smapUrl?: string;
+  /** Take the fast path when the credential names one (default true; false: the standard path only). */
+  fastPath?: boolean;
+  /** Milliseconds a fast-path call (every call but refine) may take before it is repeated on the standard path (default 2000). */
+  fastPathTimeout?: number;
+  /** The same for refine, whose search takes longer (default 5000). */
+  fastPathRefineTimeout?: number;
   /** The fetch to use (the page's by default). */
   fetch?: typeof fetch;
   /** The starting plan. */

package/types/smap.d.mts

@@ -640,7 +640,11 @@ export interface PlanTokenAnswer {
   expires_at?: string;
   scopes?: string[];
   origins?: string[] | null;
+  /** Present when the client's plan calls take the fast path (OPEN-ROUTE-EDIT E19): the editor sends its calls there. */
+  fast_path?: { url: string };
 }
+/** Where a plan call was answered: the fast path through sMap, or the Open Platform's standard path. */
+export type PlanPath = 'fast' | 'standard';
 /**
  * How plan calls are authorised, always as `Authorization: Bearer …`: a short-lived plan editor token from your own
  * server (asked again 30 s before its `expires_at` and once after a 401 `SESSION_EXPIRED`), or a map key (`smk_…`)
@@ -750,6 +754,8 @@ export interface PlanChangeEvent {
   pending: boolean;
   canUndo: boolean;
   canRedo: boolean;
+  /** Where the last answered call was answered (null before the first answer). */
+  path?: PlanPath | null;
 }
 export interface PlanEditorError extends Error {
   status: number;
@@ -758,6 +764,8 @@ export interface PlanEditorError extends Error {
   details: unknown;
   /** Why, where the service says (`expired`, `key_revoked`, `entitlements_changed`, `origin_not_allowed`, `plan_editing_off`, …). */
   reason: string | null;
+  /** Where the refusal came from, when it was an answer. */
+  via?: PlanPath;
 }
 export interface PlanSnapshotEvent {
   /** `opened`, `failed` (calls go on without one), or the X-Plan-Matrix of an answer: `used`, `expired`, `unavailable`, `mismatch`. */
@@ -766,10 +774,12 @@ export interface PlanSnapshotEvent {
   expires_at?: string | null;
   node?: string | null;
   error?: unknown;
+  /** With `opened`: the path that opened it (the id is the same on both paths). */
+  path?: PlanPath | null;
 }
 export interface PlanPreview { routes: PlanRoute[]; result: PlanResult }
 /** An edit's outcome; null when a newer edit cancelled it. */
-export interface PlanEditOutcome { kind: string; plan: PlanState; result: PlanResult; answer: unknown }
+export interface PlanEditOutcome { kind: string; plan: PlanState; result: PlanResult; answer: unknown; path?: PlanPath | null }
 export interface PlanEditorState {
   plan: PlanState | null;
   result: PlanResult | null;
@@ -781,6 +791,8 @@ export interface PlanEditorState {
   locked: string[];
   last: { kind: string; answer: unknown } | null;
   preview: PlanPreview | null;
+  /** Where the last answered call was answered (null before the first answer). */
+  path?: PlanPath | null;
 }
 
 export interface PlanEditorOptions {
@@ -792,6 +804,17 @@ export interface PlanEditorOptions {
   app?: string | { id: string; cert?: string };
   /** The Open Platform, `https://open.superroute.ca` by default. */
   baseUrl?: string;
+  /**
+   * The sMap service a map key's configuration is read from (`GET <smapUrl>/plan/v1/config`), `https://tile.srsr.ca`
+   * by default; `map.planEditor` passes the map's own sMap address.
+   */
+  smapUrl?: string;
+  /** Take the fast path when the credential names one (default true; false: the standard path only). */
+  fastPath?: boolean;
+  /** Milliseconds a fast-path call (every call but refine) may take before it is repeated on the standard path (default 2000). */
+  fastPathTimeout?: number;
+  /** The same for refine, whose search takes longer (default 5000). */
+  fastPathRefineTimeout?: number;
   /** The fetch to use (the page's by default). */
   fetch?: typeof fetch;
   /** The starting plan. */