@mapvx/web-js 3.5.0-dev.1 → 3.5.0-dev.3

package/dist/cjs/utils/loadGlb.js

@@ -1,35 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_GLB_LOAD_TIMEOUT_MS = void 0;
+exports.createLazyMeshoptDecoder = createLazyMeshoptDecoder;
 exports.loadGlbRoot = loadGlbRoot;
 const draco_1 = require("../config/draco");
 const three_1 = require("./three");
+/**
+ * Builds a stand-in meshopt decoder that defers importing the real module (and instantiating its
+ * WASM) until the first `EXT_meshopt_compression` buffer actually needs decoding. GLBs without the
+ * extension never trigger the import, so the decoder stays off the critical path of the first 3D
+ * frame — it used to be part of the eager three.js import chain, delaying every scene load.
+ *
+ * `supported` mirrors the real module's own gate — it returns a bare `{ supported: false }` when
+ * `typeof WebAssembly !== "object"` — so the answer is reproduced synchronously here without
+ * importing anything. Reporting a flat `true` instead would break the platforms it claims to
+ * support: `GLTFLoader` reads `supported` before deciding to decode, and on `false` with meshopt
+ * merely OPTIONAL it returns `null` and falls back to the GLB's uncompressed buffer
+ * (`GLTFLoader.js` `GLTFMeshoptCompression.loadBufferView`). Claiming support on a WASM-less
+ * platform discards that fallback and fails the whole asset with a `TypeError` from this shim,
+ * since `decodeGltfBufferAsync` does not exist on the real module there.
+ *
+ * @param load Injectable module loader, for tests. Defaults to the cached {@link loadMeshoptDecoder}.
+ * @internal
+ */
+function createLazyMeshoptDecoder(load = three_1.loadMeshoptDecoder) {
+    return {
+        // Same condition the real decoder uses, evaluated without loading it.
+        supported: typeof WebAssembly === "object",
+        decodeGltfBufferAsync: async (count, size, source, mode, filter) => {
+            const decoder = await load();
+            await decoder.ready;
+            return decoder.decodeGltfBufferAsync(count, size, source, mode, filter);
+        },
+    };
+}
 /**
  * Lazily-initialized, cached GLTF loader configured with Draco + KTX2 support.
  *
  * The loaders (and their WebGLRenderer for KTX2 support detection) are heavy and pull in Three.js,
  * so they are created on first use inside the dynamic-import boundary rather than at module load.
+ *
+ * Memoized through {@link memoizeImport} for the same reason the loaders in `three.ts` are: a plain
+ * `cached ??=` also caches a rejection. Fixing the three loaders was not enough, because this is a
+ * SECOND cache wrapped around `loadThree()` — so a transient failure was evicted there and then
+ * replayed from here forever, and `loadGlbRoot` awaits both, meaning every GLB kept failing with
+ * the stale error long after `loadThree()` had recovered. Not only network: the `.then` below
+ * constructs a `WebGLRenderer` for KTX2 support detection, and a failed context creation was
+ * cached just the same.
  */
-let gltfLoaderPromise;
-function getGltfLoader() {
-    gltfLoaderPromise !== null && gltfLoaderPromise !== void 0 ? gltfLoaderPromise : (gltfLoaderPromise = (0, three_1.loadThree)().then((mod) => {
-        const dracoLoader = new mod.DRACOLoader();
-        dracoLoader.setDecoderPath(draco_1.DEFAULT_DRACO_DECODER_PATH);
-        const gltfLoader = new mod.GLTFLoader();
-        gltfLoader.setDRACOLoader(dracoLoader);
-        const ktx2Loader = new mod.KTX2Loader();
-        ktx2Loader.setTranscoderPath(draco_1.DEFAULT_KTX2_TRANSCODER_PATH);
-        gltfLoader.setKTX2Loader(ktx2Loader);
-        ktx2Loader.detectSupport(new mod.THREE.WebGLRenderer({ antialias: true }));
-        // Enable EXT_meshopt_compression so meshopt-compressed GLBs decode. The decoder is a WASM
-        // singleton; GLTFLoader awaits its `.ready` promise internally before parsing. Assets that
-        // don't use the extension are unaffected. This lets the offline pipeline pick meshopt (often
-        // smaller than Draco for the scene's meshes) without a runtime change.
-        gltfLoader.setMeshoptDecoder(mod.MeshoptDecoder);
-        return gltfLoader;
-    }));
-    return gltfLoaderPromise;
-}
+const getGltfLoader = (0, three_1.memoizeImport)(() => (0, three_1.loadThree)().then((mod) => {
+    const dracoLoader = new mod.DRACOLoader();
+    dracoLoader.setDecoderPath(draco_1.DEFAULT_DRACO_DECODER_PATH);
+    const gltfLoader = new mod.GLTFLoader();
+    gltfLoader.setDRACOLoader(dracoLoader);
+    const ktx2Loader = new mod.KTX2Loader();
+    ktx2Loader.setTranscoderPath(draco_1.DEFAULT_KTX2_TRANSCODER_PATH);
+    gltfLoader.setKTX2Loader(ktx2Loader);
+    ktx2Loader.detectSupport(new mod.THREE.WebGLRenderer({ antialias: true }));
+    // Enable EXT_meshopt_compression so meshopt-compressed GLBs decode, without paying for the
+    // decoder module up front: the lazy stand-in imports it (and instantiates its WASM) only when
+    // the first meshopt-compressed buffer is actually decoded. Assets that don't use the extension
+    // never load it. The cast is safe — with `decodeGltfBufferAsync` present, GLTFLoader touches
+    // only `supported` and `decodeGltfBufferAsync` (see LazyMeshoptDecoder).
+    gltfLoader.setMeshoptDecoder(createLazyMeshoptDecoder());
+    return gltfLoader;
+}));
 /**
  * Default per-asset timeout for {@link loadGlbRoot}.
  *

package/dist/cjs/utils/loadGlb.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadGlb.js","sourceRoot":"","sources":["../../../src/utils/loadGlb.ts"],"names":[],"mappings":";;;AAwHA,kCA4EC;AAlMD,2CAA0F;AAC1F,mCAAmC;AAEnC;;;;;GAKG;AACH,IAAI,iBAES,CAAA;AAEb,SAAS,aAAa;IACpB,iBAAiB,aAAjB,iBAAiB,cAAjB,iBAAiB,IAAjB,iBAAiB,GAAK,IAAA,iBAAS,GAAE,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QAC7C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,WAAW,EAAE,CAAA;QACzC,WAAW,CAAC,cAAc,CAAC,kCAA0B,CAAC,CAAA;QAEtD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,CAAA;QACvC,UAAU,CAAC,cAAc,CAAC,WAAW,CAAC,CAAA;QAEtC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,CAAA;QACvC,UAAU,CAAC,iBAAiB,CAAC,oCAA4B,CAAC,CAAA;QAC1D,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,CAAA;QACpC,UAAU,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAE1E,0FAA0F;QAC1F,2FAA2F;QAC3F,6FAA6F;QAC7F,uEAAuE;QACvE,UAAU,CAAC,iBAAiB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;QAEhD,OAAO,UAAU,CAAA;IACnB,CAAC,CAAC,EAAA;IACF,OAAO,iBAAiB,CAAA;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,2BAA2B,GAAG,MAAO,CAAA;AAElD;;;;GAIG;AACH,MAAM,SAAS,GAAG,UAAU,CAAA;AAE5B;;;;;;;;;;;;GAYG;AACH,SAAS,uBAAuB,CAAC,MAAmB,EAAE,GAAW;IAC/D,IAAI,MAAM,CAAC,UAAU,GAAG,EAAE;QAAE,OAAM,CAAC,wDAAwD;IAC3F,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;IAC1C,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,SAAS;QAAE,OAAM,CAAC,sCAAsC;IAC1F,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;IAChD,IAAI,cAAc,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,yDAAyD,cAAc,oBAAoB,MAAM,CAAC,UAAU,KAAK,GAAG,EAAE,CACvH,CAAA;IACH,CAAC;AACH,CAAC;AAoBD;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,WAAW,CAC/B,GAAW,EACX,UAA8B,EAAE;IAEhC,MAAM,EAAE,SAAS,GAAG,mCAA2B,EAAE,UAAU,EAAE,GAAG,OAAO,CAAA;IACvE,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,EAAE,IAAA,iBAAS,GAAE,CAAC,CAAC,CAAA;IAExF,+FAA+F;IAC/F,+FAA+F;IAC/F,+FAA+F;IAC/F,6EAA6E;IAC7E,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,MAAM,UAAU,GAAG,IAAI,KAAK,CAAC,UAAU,EAAE,CAAA;IACzC,UAAU,CAAC,eAAe,CAAC,aAAa,CAAC,CAAA;IAEzC,MAAM,IAAI,GAAG,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxD,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE;YACjC,IAAI,OAAO;gBAAE,OAAM;YACnB,MAAM,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACnE,CAAC,CAAA;QAED,UAAU,CAAC,IAAI,CACb,GAAG,EACH,CAAC,IAA0B,EAAE,EAAE;YAC7B,IAAI,OAAO;gBAAE,OAAM;YACnB,MAAM,MAAM,GAAG,IAAmB,CAAA;YAClC,IAAI,CAAC;gBACH,uBAAuB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,GAAG,CAAC,CAAA;gBACZ,OAAM;YACR,CAAC;YACD,UAAU,CAAC,KAAK,CACd,MAAM,EACN,KAAK,CAAC,WAAW,CAAC,cAAc,CAAC,GAAG,CAAC,EACrC,CAAC,IAAU,EAAE,EAAE;gBACb,IAAI,OAAO;oBAAE,OAAM;gBACnB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACrB,CAAC,EACD,OAAO,CACR,CAAA;QACH,CAAC,EACD,CAAC,KAAoB,EAAE,EAAE;YACvB,IAAI,CAAC,OAAO;gBAAE,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAG,KAAK,CAAC,CAAA;QACnC,CAAC,EACD,OAAO,CACR,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAA;QACnB,CAAC;gBAAS,CAAC;YACT,OAAO,GAAG,IAAI,CAAA;QAChB,CAAC;IACH,CAAC;IAED,IAAI,KAAgD,CAAA;IACpD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;QACtD,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,+BAA+B,SAAS,OAAO,GAAG,EAAE,CAAC,CAAC,EAC7E,SAAS,CACV,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAC5C,CAAC;YAAS,CAAC;QACT,OAAO,GAAG,IAAI,CAAA;QACd,YAAY,CAAC,KAAK,CAAC,CAAA;QACnB,4FAA4F;QAC5F,6FAA6F;QAC7F,4FAA4F;QAC5F,4EAA4E;QAC5E,UAAU,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC;AACH,CAAC"}
+{"version":3,"file":"loadGlb.js","sourceRoot":"","sources":["../../../src/utils/loadGlb.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/three.js

@@ -33,45 +33,81 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadThree = loadThree;
-exports.loadDeck = loadDeck;
-let threePromise;
-let deckPromise;
+exports.loadDeck = exports.loadMeshoptDecoder = exports.loadThree = void 0;
+exports.memoizeImport = memoizeImport;
+/**
+ * Memoizes a dynamic-import chain, caching only a FULFILLED result.
+ *
+ * A plain `cached ??= import(...)` also memoizes a *rejection*, so one transient chunk-fetch
+ * failure (a dropped connection, a cache-busted deploy mid-session) permanently disables the
+ * feature for the rest of the page's life: every retry receives the same rejected promise and
+ * fails identically. The 3D scene retries on its own — `reloadScene3DModelsForLod` reloads GLB
+ * templates on every zoom-in past the LOD threshold — so a sticky rejection turns a blip into
+ * models that never come back until the user reloads.
+ *
+ * Concurrent callers still share one in-flight import (that is the point of the cache); only the
+ * rejected promise is evicted, and the error is re-thrown so every current caller still sees it.
+ *
+ * Exported only so the eviction behaviour can be tested directly — the loaders below wrap real
+ * dynamic `import()` calls, which a unit test cannot fail on demand.
+ *
+ * @param load Builds the import promise. Called again on the first retry after a failure.
+ * @returns An accessor that imports at most once per successful load.
+ * @internal
+ */
+function memoizeImport(load) {
+    let cached;
+    return () => {
+        cached !== null && cached !== void 0 ? cached : (cached = load().catch((error) => {
+            // Evict BEFORE re-throwing so the next call starts a fresh import. Safe to assign here:
+            // a promise never settles synchronously, so `cached` is already assigned by now.
+            cached = undefined;
+            throw error;
+        }));
+        return cached;
+    };
+}
 /**
  * Dynamically imports Three.js and the GLTF/DRACO/KTX2 loaders once and caches the result.
  * Subsequent calls return the same promise, so a single Three.js instance is shared.
+ * A failed import is not cached — see {@link memoizeImport}.
  */
-function loadThree() {
-    threePromise !== null && threePromise !== void 0 ? threePromise : (threePromise = Promise.all([
-        Promise.resolve().then(() => __importStar(require("three"))),
-        Promise.resolve().then(() => __importStar(require("three/addons/loaders/GLTFLoader.js"))),
-        Promise.resolve().then(() => __importStar(require("three/addons/loaders/DRACOLoader.js"))),
-        Promise.resolve().then(() => __importStar(require("three/addons/loaders/KTX2Loader.js"))),
-        Promise.resolve().then(() => __importStar(require("three/addons/libs/meshopt_decoder.module.js"))),
-    ]).then(([three, gltf, draco, ktx2, meshopt]) => ({
-        THREE: three,
-        GLTFLoader: gltf.GLTFLoader,
-        DRACOLoader: draco.DRACOLoader,
-        KTX2Loader: ktx2.KTX2Loader,
-        MeshoptDecoder: meshopt.MeshoptDecoder,
-    })));
-    return threePromise;
-}
+exports.loadThree = memoizeImport(() => Promise.all([
+    Promise.resolve().then(() => __importStar(require("three"))),
+    Promise.resolve().then(() => __importStar(require("three/addons/loaders/GLTFLoader.js"))),
+    Promise.resolve().then(() => __importStar(require("three/addons/loaders/DRACOLoader.js"))),
+    Promise.resolve().then(() => __importStar(require("three/addons/loaders/KTX2Loader.js"))),
+]).then(([three, gltf, draco, ktx2]) => ({
+    THREE: three,
+    GLTFLoader: gltf.GLTFLoader,
+    DRACOLoader: draco.DRACOLoader,
+    KTX2Loader: ktx2.KTX2Loader,
+})));
+/**
+ * Dynamically imports the singleton meshopt decoder once and caches the result.
+ *
+ * Deliberately NOT part of {@link loadThree}'s import chain: only GLBs compressed with
+ * `EXT_meshopt_compression` need it, so keeping it out of the eager `Promise.all` keeps the
+ * decoder module (and its WASM instantiation) off the critical path of the first 3D frame.
+ * It is fetched on the first meshopt buffer decode instead — see the lazy wrapper in
+ * `loadGlb.ts`. That moves the fetch inside `parse()`, competing with hundreds of MB of GLB
+ * downloads, so not caching a failed import (see {@link memoizeImport}) matters more here than
+ * for the eager loaders.
+ */
+exports.loadMeshoptDecoder = memoizeImport(() => Promise.resolve().then(() => __importStar(require("three/addons/libs/meshopt_decoder.module.js"))).then((meshopt) => meshopt.MeshoptDecoder));
 /**
  * Dynamically imports the deck.gl overlay and layer classes once and caches the result.
+ * A failed import is not cached — see {@link memoizeImport}.
  */
-function loadDeck() {
-    deckPromise !== null && deckPromise !== void 0 ? deckPromise : (deckPromise = Promise.all([
-        Promise.resolve().then(() => __importStar(require("@deck.gl/mapbox"))),
-        Promise.resolve().then(() => __importStar(require("@deck.gl/geo-layers"))),
-        Promise.resolve().then(() => __importStar(require("@deck.gl/layers"))),
-    ]).then(([mapbox, geoLayers, layers]) => ({
-        MapboxOverlay: mapbox.MapboxOverlay,
-        MVTLayer: geoLayers.MVTLayer,
-        IconLayer: layers.IconLayer,
-        PathLayer: layers.PathLayer,
-        TextLayer: layers.TextLayer,
-    })));
-    return deckPromise;
-}
+exports.loadDeck = memoizeImport(() => Promise.all([
+    Promise.resolve().then(() => __importStar(require("@deck.gl/mapbox"))),
+    Promise.resolve().then(() => __importStar(require("@deck.gl/geo-layers"))),
+    Promise.resolve().then(() => __importStar(require("@deck.gl/layers"))),
+]).then(([mapbox, geoLayers, layers]) => ({
+    MapboxOverlay: mapbox.MapboxOverlay,
+    MVTLayer: geoLayers.MVTLayer,
+    IconLayer: layers.IconLayer,
+    PathLayer: layers.PathLayer,
+    TextLayer: layers.TextLayer,
+})));
 //# sourceMappingURL=three.js.map

package/dist/cjs/utils/three.js.map

@@ -1 +1 @@
-{"version":3,"file":"three.js","sourceRoot":"","sources":["../../../src/utils/three.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,8BAeC;AAKD,4BAaC;AAxCD,IAAI,YAA8C,CAAA;AAClD,IAAI,WAA4C,CAAA;AAEhD;;;GAGG;AACH,SAAgB,SAAS;IACvB,YAAY,aAAZ,YAAY,cAAZ,YAAY,IAAZ,YAAY,GAAK,OAAO,CAAC,GAAG,CAAC;0DACpB,OAAO;0DACP,oCAAoC;0DACpC,qCAAqC;0DACrC,oCAAoC;0DACpC,6CAA6C;KACrD,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAChD,KAAK,EAAE,KAAK;QACZ,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CAAC,EAAA;IACH,OAAO,YAAY,CAAA;AACrB,CAAC;AAED;;GAEG;AACH,SAAgB,QAAQ;IACtB,WAAW,aAAX,WAAW,cAAX,WAAW,IAAX,WAAW,GAAK,OAAO,CAAC,GAAG,CAAC;0DACnB,iBAAiB;0DACjB,qBAAqB;0DACrB,iBAAiB;KACzB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QACxC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC,EAAA;IACH,OAAO,WAAW,CAAA;AACpB,CAAC"}
+{"version":3,"file":"three.js","sourceRoot":"","sources":["../../../src/utils/three.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,sCAWC;AA/BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,aAAa,CAAI,IAAsB;IACrD,IAAI,MAA8B,CAAA;IAClC,OAAO,GAAG,EAAE;QACV,MAAM,aAAN,MAAM,cAAN,MAAM,IAAN,MAAM,GAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACzC,wFAAwF;YACxF,iFAAiF;YACjF,MAAM,GAAG,SAAS,CAAA;YAClB,MAAM,KAAK,CAAA;QACb,CAAC,CAAC,EAAA;QACF,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;AACH,CAAC;AAED;;;;GAIG;AACU,QAAA,SAAS,GAA+B,aAAa,CAAC,GAAG,EAAE,CACtE,OAAO,CAAC,GAAG,CAAC;sDACH,OAAO;sDACP,oCAAoC;sDACpC,qCAAqC;sDACrC,oCAAoC;CAC5C,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IACvC,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,IAAI,CAAC,UAAU;IAC3B,WAAW,EAAE,KAAK,CAAC,WAAW;IAC9B,UAAU,EAAE,IAAI,CAAC,UAAU;CAC5B,CAAC,CAAC,CACJ,CAAA;AAED;;;;;;;;;;GAUG;AACU,QAAA,kBAAkB,GAAyC,aAAa,CAAC,GAAG,EAAE,CACzF,kDAAO,6CAA6C,IAAE,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,CAChG,CAAA;AAED;;;GAGG;AACU,QAAA,QAAQ,GAA8B,aAAa,CAAC,GAAG,EAAE,CACpE,OAAO,CAAC,GAAG,CAAC;sDACH,iBAAiB;sDACjB,qBAAqB;sDACrB,iBAAiB;CACzB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;IACxC,aAAa,EAAE,MAAM,CAAC,aAAa;IACnC,QAAQ,EAAE,SAAS,CAAC,QAAQ;IAC5B,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;CAC5B,CAAC,CAAC,CACJ,CAAA"}

package/dist/es/controllers/routeController.d.ts

@@ -22,6 +22,11 @@ export declare class RouteController {
     private resolveInstance;
     /**
      * Add MapLibre sources and layers for a single route instance.
+     *
+     * All three sources set `lineMetrics`: maplibre computes `line-progress` only
+     * when a source asks it to, and `preparePaintForLayer` emits a
+     * `line-progress` gradient for a GradientStyle. Without it, a consumer
+     * setting a gradient route style silently got no gradient at all.
      */
     private addSourcesAndLayersForRoute;
     /**
@@ -168,6 +173,15 @@ export declare class RouteController {
     centerOnCurrentStep(routeId?: string): void;
     private prepareForNextStep;
     private animateStep;
+    /**
+     * Pushes the in-progress segment's geometry to its map source.
+     *
+     * Called once per frame rather than once per vertex crossed: `setData`
+     * rebuilds the whole geojson-vt index and reloads every in-view tile, so its
+     * cost is a large fixed one per call and is worth paying only once, with the
+     * frame's final geometry.
+     */
+    private flushCurrentSourceData;
     private setMarkerLngLat;
     private setMarkerRotation;
     setMarkerFloor(floorId?: string, routeId?: string): void;

package/dist/es/controllers/routeController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routeController.d.ts","sourceRoot":"","sources":["../../../src/controllers/routeController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routeController.d.ts","sourceRoot":"","sources":["../../../src/controllers/routeController.ts"],"names":[],"mappings":"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"}