@mapvx/web-js 3.1.0 → 3.2.0-dev.2

package/dist/cjs/utils/loadGlb.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GLB_LOAD_TIMEOUT_MS = void 0;
 exports.loadGlbRoot = loadGlbRoot;
 const draco_1 = require("../config/draco");
 const three_1 = require("./three");
@@ -24,22 +25,119 @@ function getGltfLoader() {
     }));
     return gltfLoaderPromise;
 }
+/**
+ * Default per-asset timeout for {@link loadGlbRoot}.
+ *
+ * Guards against loaders that hang instead of throwing — a GLB whose binary chunk is truncated
+ * (see {@link loadGlbRoot}'s completeness check) or otherwise malformed can put Three.js's
+ * `DRACOLoader` into an undefined state: sometimes a decode error, sometimes no callback at all.
+ * Without a timeout, one such asset never settles and blocks every other load queued behind it.
+ *
+ * @group Configuration
+ */
+exports.DEFAULT_GLB_LOAD_TIMEOUT_MS = 30000;
+/**
+ * Magic number ("glTF" read little-endian) at byte offset 0 of every binary glTF (`.glb`)
+ * container. Used only to tell a binary GLB apart from a plain JSON `.gltf` payload — the latter
+ * has no such header and skips the completeness check in {@link assertGlbBufferComplete}.
+ */
+const GLB_MAGIC = 0x46546c67;
+/**
+ * Rejects a GLB download that was cut short before it reaches Three.js's `GLTFLoader`/`DRACOLoader`,
+ * whose behavior on truncated input ranges from a cryptic decode error (e.g. "Unexpected geometry
+ * type") to an outright hang, rather than a clear message pointing at the actual problem.
+ *
+ * The binary glTF container format requires the 12-byte header's declared total length to equal
+ * the file's real byte length (see the {@link https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#binary-header | spec}).
+ * A mismatch means the response body was truncated — a dropped connection, or the object stored at
+ * `url` is itself incomplete — so every buffer-view offset past that point reads garbage. This is
+ * exactly what was found in the field for one "Suelo" asset that both threw a decode error and (in
+ * a larger sibling file) hung: the file's own header declared a ~383 MB binary chunk while only
+ * ~8.7 MB had actually been received.
+ */
+function assertGlbBufferComplete(buffer, url) {
+    if (buffer.byteLength < 12)
+        return; // too short to have a GLB header; let parse() report it
+    const header = new DataView(buffer, 0, 12);
+    if (header.getUint32(0, true) !== GLB_MAGIC)
+        return; // plain JSON .gltf, not a binary .glb
+    const declaredLength = header.getUint32(8, true);
+    if (declaredLength !== buffer.byteLength) {
+        throw new Error(`GLB download is truncated or corrupt: header declares ${declaredLength} bytes, received ${buffer.byteLength}: ${url}`);
+    }
+}
 /**
  * Loads a GLB/GLTF from URL and returns the root scene group.
  * Central entry point so the loader implementation can be swapped later (e.g. Draco, KTX2, custom fetch).
  *
+ * Fetches the raw bytes itself (rather than deferring to `GLTFLoader.load`) so a truncated download
+ * can be caught and rejected clearly — see {@link assertGlbBufferComplete} — before it ever reaches
+ * the Draco/KTX2 decoders.
+ *
  * @param url - GLB URL
  * @returns Root `THREE.Group` from the loaded glTF scene
  * @group Utils
  */
-async function loadGlbRoot(url) {
-    const gltfLoader = await getGltfLoader();
-    return new Promise((resolve, reject) => {
-        gltfLoader.load(url, (gltf) => {
-            resolve(gltf.scene);
-        }, undefined, (error) => {
+async function loadGlbRoot(url, options = {}) {
+    const { timeoutMs = exports.DEFAULT_GLB_LOAD_TIMEOUT_MS, onProgress } = options;
+    const [gltfLoader, { THREE: three }] = await Promise.all([getGltfLoader(), (0, three_1.loadThree)()]);
+    // Set once the caller has stopped waiting (success, failure, or timeout) so any callback three
+    // fires afterwards — e.g. a timed-out fetch/decode that keeps running in the background — is a
+    // no-op instead of resolving/rejecting an already-settled promise or emitting a stray progress
+    // event after the batch this asset belongs to already reported `done: true`.
+    let settled = false;
+    const fileLoader = new three.FileLoader();
+    fileLoader.setResponseType("arraybuffer");
+    const load = new Promise((resolve, reject) => {
+        const onError = (error) => {
+            if (settled)
+                return;
             reject(error instanceof Error ? error : new Error(String(error)));
-        });
+        };
+        fileLoader.load(url, (data) => {
+            if (settled)
+                return;
+            const buffer = data;
+            try {
+                assertGlbBufferComplete(buffer, url);
+            }
+            catch (err) {
+                onError(err);
+                return;
+            }
+            gltfLoader.parse(buffer, three.LoaderUtils.extractUrlBase(url), (gltf) => {
+                if (settled)
+                    return;
+                resolve(gltf.scene);
+            }, onError);
+        }, (event) => {
+            if (!settled)
+                onProgress === null || onProgress === void 0 ? void 0 : onProgress(event);
+        }, onError);
+    });
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        try {
+            return await load;
+        }
+        finally {
+            settled = true;
+        }
+    }
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`Timed out loading GLB after ${timeoutMs}ms: ${url}`)), timeoutMs);
     });
+    try {
+        return await Promise.race([load, timeout]);
+    }
+    finally {
+        settled = true;
+        clearTimeout(timer);
+        // Cancels the underlying fetch (and, by never delivering its buffer, the Draco/KTX2 decode)
+        // so a timed-out asset actually frees its network/CPU usage instead of running to completion
+        // unattended — otherwise GLB_LOAD_CONCURRENCY only bounds how many loads the caller awaits,
+        // not how many are truly in flight. A no-op if `load` already won the race.
+        fileLoader.abort();
+    }
 }
 //# sourceMappingURL=loadGlb.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"loadGlb.js","sourceRoot":"","sources":["../../../src/utils/loadGlb.ts"],"names":[],"mappings":";;AAyCA,kCAcC;AArDD,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,OAAO,UAAU,CAAA;IACnB,CAAC,CAAC,EAAA;IACF,OAAO,iBAAiB,CAAA;AAC1B,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,UAAU,GAAG,MAAM,aAAa,EAAE,CAAA;IACxC,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAClD,UAAU,CAAC,IAAI,CACb,GAAG,EACH,CAAC,IAAU,EAAE,EAAE;YACb,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrB,CAAC,EACD,SAAS,EACT,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACnE,CAAC,CACF,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"loadGlb.js","sourceRoot":"","sources":["../../../src/utils/loadGlb.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/mapvxHostname.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMapVxRequestHostname = isMapVxRequestHostname;
 /**
  * Returns whether a URL hostname is part of the MapVX API domain tree.
- * Matches `mapvx.com` and any subdomain (`api.mapvx.com`, `public-api.mapvx.com`,
- * `integration.mapvx.com`, etc.). Does not match lookalike domains (e.g. `notmapvx.com`).
+ * Matches `mapvx.com` and `mapvx.dev` plus any subdomain (`api.mapvx.com`,
+ * `public-api.mapvx.com`, `api.mapvx.dev`, `portal.mapvx.dev`, etc.).
+ * Does not match lookalike domains (e.g. `notmapvx.com`).
  *
  * @param hostname - Value from `URL.hostname` (no port)
  * @returns True if context headers should be attached for this host
@@ -15,6 +16,6 @@ function isMapVxRequestHostname(hostname) {
     if (!h) {
         return false;
     }
-    return /^(?:[a-z0-9-]+\.)*mapvx\.com$/.test(h);
+    return /^(?:[a-z0-9-]+\.)*mapvx\.(?:com|dev)$/.test(h);
 }
 //# sourceMappingURL=mapvxHostname.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"mapvxHostname.js","sourceRoot":"","sources":["../../../src/utils/mapvxHostname.ts"],"names":[],"mappings":";;AASA,wDAMC;AAfD;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CAAC,QAAgB;IACrD,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACvC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,+BAA+B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAChD,CAAC"}
+{"version":3,"file":"mapvxHostname.js","sourceRoot":"","sources":["../../../src/utils/mapvxHostname.ts"],"names":[],"mappings":";;AAUA,wDAMC;AAhBD;;;;;;;;;GASG;AACH,SAAgB,sBAAsB,CAAC,QAAgB;IACrD,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACvC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,uCAAuC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACxD,CAAC"}

package/dist/es/config/sdkConfig.d.ts

@@ -94,7 +94,7 @@ export interface SDKConfig {
     /**
      * The base API URL for the SDK requests.
      * Can be used to point to different environments or custom servers.
-     * For example: 'https://public-api.mapvx.com' for production, 'https://integration.mapvx.com' for staging.
+     * For example: 'https://public-api.mapvx.com' for production, 'https://api.mapvx.dev' for staging.
      * @defaultValue `https://public-api.mapvx.com`
      */
     apiUrl?: string;

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

@@ -0,0 +1,148 @@
+import { type PositionAnchor } from "maplibre-gl";
+import { type MarkerLayoutConfig } from "../domain/models/mapConfig";
+import { type MarkerAttribute, TextPosition } from "../domain/models/marker";
+import { type InternalMapVXMap } from "../map/map";
+/** Axis-aligned box in screen (CSS pixel) space. */
+export interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Fraction of the icon's own box, along each axis, that MapLibre's Marker
+ * anchor math (`translate(-x%, -y%)`) aligns to the geodetic point. Mirrors
+ * MapLibre's own `anchorTranslate` table so the collision math agrees with
+ * what's actually on screen.
+ */
+export declare const ANCHOR_FRACTIONS: Record<PositionAnchor, {
+    fx: number;
+    fy: number;
+}>;
+/** Candidate order tried when a marker's preferred side is unavailable. */
+export declare const FALLBACK_ORDER: TextPosition[];
+/** Builds the icon's on-screen rect from its projected point, size and anchor. */
+export declare function computeIconRect(screen: {
+    x: number;
+    y: number;
+}, iconSize: {
+    width: number;
+    height: number;
+}, anchor: PositionAnchor): Rect;
+/**
+ * Builds a candidate label rect for one side of an icon. Mirrors the CSS in
+ * `styles.css` (`.text-container.right/left/top/bottom`) exactly, so a
+ * position the algorithm picks as collision-free renders collision-free.
+ */
+export declare function computeCandidateRect(iconRect: Rect, labelSize: {
+    width: number;
+    height: number;
+}, position: TextPosition, gapPx: number, verticalGapPx: number): Rect;
+/** Expands a rect by `padding` on every side. */
+export declare function expandRect(rect: Rect, padding: number): Rect;
+/** Standard AABB intersection test. */
+export declare function rectsIntersect(a: Rect, b: Rect): boolean;
+/**
+ * Automatic collision avoidance for marker text labels: keeps a marker's
+ * icon fixed while moving (or hiding) its label to avoid overlapping
+ * neighboring markers' icons/labels, similar to Google Maps' label
+ * placement. Below `minZoomForLabels` it withholds every label instead, so
+ * a zoomed-out map shows pins only. See {@link MarkerLayoutConfig}.
+ *
+ * Not part of the public SDK surface — owned and driven entirely by
+ * {@link InternalMapVXMap}, mirroring `RouteController`.
+ */
+export declare class MarkerLayoutController {
+    private readonly mapvxMap;
+    private readonly config;
+    private labelSizeCache;
+    private iconSizeCache;
+    private readonly lastAppliedState;
+    private readonly boundOnMove;
+    private rafHandle;
+    private attached;
+    constructor(map: InternalMapVXMap, config: Required<MarkerLayoutConfig>);
+    private get map();
+    /**
+     * Starts listening for camera movement. Safe to call once the underlying
+     * MapLibre `Map` instance exists; a single `"move"` listener covers pan,
+     * zoom, rotate, pitch and `resize()`.
+     */
+    attach(): void;
+    /**
+     * Publishes the configured gaps and label width cap as CSS custom
+     * properties, which `styles.css` reads to offset labels from their icon.
+     * Without this the stylesheet would keep its hardcoded defaults while the
+     * collision math used the configured values, so any custom `gapPx` /
+     * `verticalGapPx` would produce placements this controller believes are
+     * collision-free but that visibly overlap on screen.
+     *
+     * Called with the map's own container, so every marker MapLibre mounts
+     * inside it inherits the values.
+     */
+    applyLayoutVariables(container: HTMLElement): void;
+    /**
+     * A label measured before its web font finishes loading is measured in the
+     * fallback font, and that wrong footprint would otherwise be cached for
+     * the marker's lifetime. Drop every measurement once fonts settle.
+     */
+    private remeasureWhenFontsLoad;
+    /** Stops listening and cancels any pending layout pass. */
+    destroy(): void;
+    /**
+     * Drops everything cached for a marker, e.g. after its text/content
+     * changed.
+     *
+     * The last applied decision has to go too: rebuilding a marker's DOM
+     * replaces its `.text-container` with a fresh one carrying the preferred
+     * side and no `visibility`, so a decision remembered from the old element
+     * would make {@link applyDecisions} short-circuit and leave the new label
+     * on the wrong side — or visible when it should be hidden.
+     */
+    invalidateMarker(marker: MarkerAttribute): void;
+    /** Coalesces repeated calls into a single layout pass per animation frame. */
+    scheduleRelayout(): void;
+    private performLayout;
+    /** Read phase: project + measure, no writes. Culls markers fully outside the viewport. */
+    private readMarkers;
+    private resolveLabelSize;
+    /**
+     * The icon's box. Markers built from a caller-supplied `element` with no
+     * declared `iconProperties` are measured from the DOM, since their real
+     * size is whatever that element renders at; everyone else's box is exactly
+     * what `MarkerUtils.createMarkerElement` pinned it to.
+     */
+    private resolveIconSize;
+    /**
+     * Measures an element once and remembers it. A zero measurement is
+     * returned but never cached: it means the element isn't laid out yet (a
+     * `display: none` ancestor, a first pass before the web font loads), and
+     * caching it would freeze that marker's footprint at nothing for the rest
+     * of its life.
+     */
+    private measureCached;
+    /**
+     * Compute phase: pure, no DOM access. Icons always block; labels negotiate
+     * a side or hide.
+     *
+     * Below `minZoomForLabels` every label is hidden and none is placed, so no
+     * label ever becomes an obstacle for a neighbor at that zoom — a label the
+     * threshold withheld must not displace anything on its way out.
+     */
+    private decidePlacements;
+    /**
+     * Whether a candidate label rect clashes with any other marker's icon or
+     * with a label already placed this pass.
+     *
+     * A label's own icon is deliberately excluded: `gapPx`/`verticalGapPx`
+     * already define the spacing to it, and `paddingPx` is breathing room
+     * against *neighbors*. Counting the own icon here would make top/bottom
+     * impossible for every marker as soon as `paddingPx` exceeded
+     * `verticalGapPx` (4 vs 4 by default) — and at `paddingPx: 10` would hide
+     * every label on the map.
+     */
+    private collides;
+    /** Write phase: only touches the DOM for markers whose decision actually changed. */
+    private applyDecisions;
+}
+//# sourceMappingURL=markerLayoutController.d.ts.map

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

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