@mapvx/web-js 4.0.2 → 4.0.3-dev.2

package/dist/es/map/installMapLibreWorker.d.ts

@@ -84,4 +84,3 @@ export declare function getMapLibreWorkerUrl(): string;
  * @internal
  */
 export declare function resetMapLibreWorkerInstallForTests(): void;
-//# sourceMappingURL=installMapLibreWorker.d.ts.map

package/dist/es/map/installMapLibreWorker.js

@@ -1,134 +1,34 @@
 import { getVersion, getWorkerUrl, setWorkerUrl } from "maplibre-gl";
 import { MAPLIBRE_WORKER_SOURCE, MAPLIBRE_WORKER_VERSION } from "./generated/maplibreWorkerSource";
-/**
- * The blob URL this SDK created, or `null` while nothing has been installed yet. Kept so the
- * install is idempotent and so we can tell our own URL from one a consumer supplied.
- */
 let installedWorkerUrl = null;
-/**
- * Registers a self-contained MapLibre worker carried inside this bundle.
- *
- * MapLibre 6 no longer inlines its worker. It resolves it at runtime with
- * `new URL('./maplibre-gl-worker.mjs', import.meta.url)`, building the filename by concatenation
- * so no bundler can see it statically and none emit the file. Once a consumer bundles this SDK,
- * `import.meta.url` is the consumer's own chunk, the worker is requested from a path where nothing
- * exists — in a single-page app the request falls through to the app shell and the worker dies on
- * a `text/html` MIME error — and the map renders nothing at all. Handing MapLibre a `blob:` URL
- * removes that resolution from the picture entirely, so this holds regardless of the consumer's
- * bundler, base href, or whether the app is served from a subpath.
- *
- * Must run before anything touches MapLibre's global worker pool, which is earlier than it looks.
- * The pool is created by the first `Dispatcher` and the URL is read then, once, and not again
- * while a map is alive — so any MapLibre call that builds a Dispatcher ahead of this one wins
- * permanently. `new Map(...)` is the obvious one, but `prewarm()`, `importScriptInWorkers()` and
- * the now-removed `setRTLTextPlugin()` all do it too. Hence the very top of the map constructor,
- * rather than next to the map.
- *
- * Never called at module load: that would run `new Blob` and `URL.createObjectURL` during import,
- * which fails under SSR and in jsdom, and would hand MapLibre a worker URL for applications that
- * import this package without ever creating a map. It does not save memory — the worker string is
- * resident from the moment this module is imported either way.
- *
- * A consumer that installed its own worker URL is self-hosting on purpose — a strict
- * Content-Security-Policy without `worker-src blob:`, typically — and is left alone.
- *
- * Under such a policy with no URL set, the failure is silent from the application's side, and
- * measured rather than assumed: `createObjectURL` does not throw, `new Worker` does not throw
- * synchronously, and MapLibre fires no `error` event. The only signal is the browser's own
- * console message, *"Creating a worker from 'blob:…' violates the following Content Security
- * Policy directive"*, next to a map that never loads. That string is repeated here so searching
- * for it lands on this explanation and on `setMapLibreWorkerUrl`.
- *
- * @see setMapLibreWorkerUrl for the supported way to opt out.
- * @group Configuration
- */
 export function installMapLibreWorker() {
     if (installedWorkerUrl !== null)
         return;
-    // `WORKER_URL` defaults to "", so a truthy value can only mean a consumer set one.
     if (getWorkerUrl())
         return;
     const runtimeVersion = getVersion();
     if (runtimeVersion !== MAPLIBRE_WORKER_VERSION) {
-        // The bundled worker and the running MapLibre talk an internal, unversioned protocol. A skew
-        // is only possible if the consumer forced a different maplibre-gl than this SDK pinned; it is
-        // still better to install a slightly mismatched worker than to leave the map with none, so
-        // this warns rather than bails.
         console.warn(`[MapVX] MapLibre version mismatch: the bundled worker is ${MAPLIBRE_WORKER_VERSION} but ` +
             `maplibre-gl ${runtimeVersion} is running. Install maplibre-gl@${MAPLIBRE_WORKER_VERSION} ` +
             `or call setMapLibreWorkerUrl() with a self-hosted worker of the matching version.`);
     }
     try {
         const blob = new Blob([MAPLIBRE_WORKER_SOURCE], { type: "text/javascript" });
-        // Deliberately never revoked. MapLibre terminates its worker pool when the last map is
-        // removed and reads this URL again when the next map is created, so revoking would break
-        // every map after the first.
         installedWorkerUrl = URL.createObjectURL(blob);
         setWorkerUrl(installedWorkerUrl);
     }
     catch (error) {
-        // Blob/createObjectURL are absent under SSR and in some test environments. Leaving MapLibre's
-        // own resolution in place is the best remaining option: it works when the SDK is served
-        // unbundled, which is exactly the situation where this path is reachable.
         installedWorkerUrl = null;
         console.warn("[MapVX] Could not install the bundled MapLibre worker:", error);
     }
 }
-/**
- * Points MapLibre at a worker script you host yourself, instead of the one bundled into this SDK.
- *
- * The bundled worker is delivered as a `blob:` URL, which a Content-Security-Policy without
- * `worker-src blob:` (or `child-src blob:`) will block. Self-hosting is the way out: copy
- * `maplibre-gl-worker.mjs` **and** `maplibre-gl-shared.mjs` from `maplibre-gl/dist` — the worker
- * imports the shared file at runtime, so both must be served from the same directory — and point
- * this at the first one. Use `npm ls maplibre-gl` to see which version this SDK resolved; the
- * files must come from that one.
- *
- * **The URL has to be same-origin.** A cross-origin one does not escape `blob:`: MapLibre wraps
- * any worker URL it considers cross-origin in a generated `blob:` worker that imports it, so a
- * CDN-hosted worker hits exactly the same Content-Security-Policy wall as the bundled one.
- *
- * Call it before creating any map. Once MapLibre's worker pool has spun up it does not re-read the
- * URL until every map has been removed.
- *
- * Exists so opting out does not force a direct `maplibre-gl` dependency on consumers that only
- * use this SDK.
- *
- * @param url - URL of the MapLibre worker script to load.
- * @example
- * ```ts
- * import { setMapLibreWorkerUrl, initializeSDK } from "@mapvx/web-js"
- *
- * setMapLibreWorkerUrl("/assets/maplibre-gl-worker.mjs")
- * const sdk = initializeSDK(token)
- * ```
- * @group Configuration
- */
 export function setMapLibreWorkerUrl(url) {
     setWorkerUrl(url);
-    // Stop claiming ownership: the URL in play is now the consumer's, and ours (if any) must not be
-    // revoked while a worker pool may still be using it.
     installedWorkerUrl = null;
 }
-/**
- * The worker URL MapLibre will use, or `""` when none has been set yet.
- *
- * Returns a `blob:` URL once the bundled worker has been installed, which happens when the first
- * map is created. Useful to assert in tests that the bundled worker is in play.
- *
- * @returns The current MapLibre worker URL.
- * @group Configuration
- */
 export function getMapLibreWorkerUrl() {
     return getWorkerUrl();
 }
-/**
- * Resets the module-level install state. Test seam only — the blob URL is intentionally never
- * revoked in production, so there is nothing to clean up outside tests.
- *
- * @internal
- */
 export function resetMapLibreWorkerInstallForTests() {
     installedWorkerUrl = null;
 }
-//# sourceMappingURL=installMapLibreWorker.js.map

package/dist/es/map/liveMapFitTransform.d.ts

@@ -101,4 +101,3 @@ export declare class LiveMapFitTransform implements FitTransform {
     /** Flush {@link pending} onto the map, but only when a projection actually needs it. */
     private sync;
 }
-//# sourceMappingURL=liveMapFitTransform.d.ts.map

package/dist/es/map/liveMapFitTransform.js

@@ -1,63 +1,8 @@
 const DEG_TO_RAD = Math.PI / 180;
-/**
- * A {@link FitTransform} backed by a live MapLibre map and its public API.
- *
- * ## Why this exists
- *
- * {@link refineCameraForPitch} needs to project points through MapLibre's real perspective
- * projection for camera states the map is not actually in — it tries a candidate camera, measures
- * where the geometry lands, adjusts, and repeats. Until MapLibre v6 that was done on
- * `map.transform.clone()`, a detached copy of the internal transform.
- *
- * v6 removed `map.transform` and exposes no replacement: there is no exported `Camera`,
- * `Transform` or `MercatorTransform`, and the migration guide says only "use `Map`'s public API
- * instead". So the simulation moves onto the map itself.
- *
- * ## How it stays invisible
- *
- * The map is genuinely moved, but never painted mid-simulation: MapLibre renders on
- * `requestAnimationFrame`, and every mutation here happens inside one synchronous block that ends
- * with {@link restore}. No intermediate frame exists to be seen.
- *
- * Camera writes are also batched. Setters only record intent; the map is moved at most once per
- * refinement iteration, lazily, the first time a projection actually needs the new camera.
- *
- * ## What it costs
- *
- * `jumpTo` fires camera events, so listeners observe movement that no user caused. At the only
- * call site this is bounded — the refinement is immediately followed by a real `easeTo`, so the
- * map was going to move regardless, and the `moveend` handler that reports completion is attached
- * *after* refinement and so cannot see the simulation's events.
- *
- * @example
- * ```typescript
- * const transform = new LiveMapFitTransform(map)
- * try {
- *   camera = refineCameraForPitch(transform, coordinates, camera, params)
- * } finally {
- *   transform.restore()
- * }
- * ```
- *
- * @group Map
- */
 export class LiveMapFitTransform {
-    /**
-     * Capture the map's current camera so it can be restored, and seed the simulation with it.
-     *
-     * @param map The live map to simulate on.
-     */
     constructor(map) {
         var _a, _b, _c, _d;
-        /** Whether {@link pending} has diverged from what the map is currently showing. */
         this.dirty = false;
-        /**
-         * Whether the map was ever actually moved.
-         *
-         * Tracked separately from {@link dirty}, which {@link sync} clears the moment it flushes: keying
-         * {@link restore} off `dirty` alone would make it a no-op right after a flush and strand the map
-         * on a candidate camera.
-         */
         this.moved = false;
         this.setCenter = (center) => {
             this.pending.center = center;
@@ -87,27 +32,9 @@ export class LiveMapFitTransform {
             this.sync();
             return this.map.unproject(p);
         };
-        /**
-         * Whether a screen point lies on the visible map surface rather than beyond the horizon.
-         *
-         * MapLibre exposes no public horizon test, so this derives the horizon line from the camera.
-         * With `d` the camera-to-centre distance, the ground plane's vanishing line sits
-         * `d / tan(pitch)` pixels above the centre of the viewport, and `d` itself follows from the
-         * vertical field of view: `d = (height / 2) / tan(fov / 2)`.
-         *
-         * A round-trip through `unproject`/`project` looks like the obvious test and does not work: the
-         * projection matrix is self-consistent on both sides of the horizon, so a sky point round-trips
-         * to within 1e-8 px just as a ground point does. Measured in
-         * `example/build-test/test-v6-render.html`, which also confirms this formula brackets the
-         * horizon where `unproject` actually flips to the far side of the camera.
-         *
-         * @param p Screen point, as returned by {@link locationToScreenPoint}.
-         * @returns `true` when the point is on the map surface.
-         */
         this.isPointOnMapSurface = (p) => {
             this.sync();
             const pitchRad = this.map.getPitch() * DEG_TO_RAD;
-            // Looking straight down there is no horizon: the whole viewport is ground.
             if (pitchRad <= 0) {
                 return true;
             }
@@ -117,18 +44,11 @@ export class LiveMapFitTransform {
             }
             const fovRad = this.map.getVerticalFieldOfView() * DEG_TO_RAD;
             const cameraToCentreDistance = height / 2 / Math.tan(fovRad / 2);
-            // Padding moves the projection centre, and with it the horizon.
             const { top, bottom } = this.pending.padding;
             const centreY = height / 2 + (top - bottom) / 2;
             const horizonY = centreY - cameraToCentreDistance / Math.tan(pitchRad);
             return p.y > horizonY;
         };
-        /**
-         * Put the camera back exactly as it was when this instance was constructed.
-         *
-         * Safe to call more than once, and safe to call when nothing was ever changed. Always call it
-         * from a `finally` block so a throw mid-refinement cannot strand the map on a candidate camera.
-         */
         this.restore = () => {
             if (!this.moved) {
                 return;
@@ -166,7 +86,6 @@ export class LiveMapFitTransform {
     get zoom() {
         return this.pending.zoom;
     }
-    /** Flush {@link pending} onto the map, but only when a projection actually needs it. */
     sync() {
         if (!this.dirty) {
             return;
@@ -182,4 +101,3 @@ export class LiveMapFitTransform {
         this.moved = true;
     }
 }
-//# sourceMappingURL=liveMapFitTransform.js.map

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

@@ -1259,4 +1259,3 @@ export declare class InternalMapVXMap extends Loggeable implements MapVXMap {
     private subscribeToFailedTiles;
     private unsubscribeFromFailedTiles;
 }
-//# sourceMappingURL=map.d.ts.map