ixmaps-gl 0.1.0 → 0.2.1

package/README.md

@@ -181,7 +181,9 @@ script. For brokers that query by view, like flat's bbox data providers, ixmaps-
 `ixmaps.getBoundingBox()`, `ixmaps.refreshTheme(id)` (loads the theme's data again, in place),
 `ixmaps.setTitle(html)`/`setTitleBox(text, color)`, `ixmaps.getThemeObj(id).fVisible` (false for a
 FEATURE theme out of scale) and calls a page's `ixmaps.htmlgui_onZoomAndPan(zoom)` after each zoom
-or pan. Scripts that reach further into flat's internals (`ixmaps.parentApi`, other `htmlgui_*`
+or pan — and also during a zoom, at the pace of the layer refresh (about every 150 ms, zoom changes only),
+so zoom-dependent page state (e.g. a basemap opacity ramp) changes in step with the scale gates
+(`featurelower`, `chartupper`, …) instead of after the gesture has ended. Scripts that reach further into flat's internals (`ixmaps.parentApi`, other `htmlgui_*`
 hooks) aren't supported. `test/project-report.mjs` shows which themes
 of your own project files gl can render.
 
@@ -190,13 +192,21 @@ of your own project files gl can render.
 Load the engine from jsDelivr, pinned to a release tag (or `@main` for the latest commit):
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.1.0/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.1/ixmaps-gl.js"></script>
+```
+
+or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmaps-gl)
+(`https://unpkg.com/ixmaps-gl` for the latest version; `npm install ixmaps-gl` installs the same
+browser script, which defines the global `ixmaps`):
+
+```html
+<script src="https://unpkg.com/ixmaps-gl@0.2.1/ixmaps-gl.js"></script>
 ```
 
 or use a local copy (`<script src="ixmaps-gl.js"></script>`). A minimal page:
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.1.0/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.1/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>

package/ixmaps-gl.js

@@ -78,14 +78,27 @@
   // Same CDN builds every example page already pinned; centralized here
   // so bumping a version is a one-file edit, not a 13-file one.
   // ---------------------------------------------------------------
+  // this engine's release (= package.json "version", checked by
+  // test/unit/version.test.mjs); ixmaps.glVersion, and logged once at start
+  const IXMAPS_GL_VERSION = '0.2.1';
+
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
     // globe projection (map.setProjection({type:'globe'})) needs >=5.0.1
     // (5.0.0 shipped a style-spec regression, reverted in 5.0.1). Requires
     // MapLibre GL JS v4.5.1, v5, or v6 on the deck.gl side (see `deck`
     // below) — v5 satisfies that.
-    maplibreCss: 'https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css',
-    maplibreJs: 'https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.js',
+    // 5.x -> 6.x (2026-09-29): MapLibre 6 is published only as an ES
+    // module (dist/maplibre-gl.mjs, named exports, no UMD bundle and no
+    // window.maplibregl) — loadMaplibre imports it and provides the global.
+    // Its worker (maplibre-gl-worker.mjs, resolved next to the module) is
+    // cross-origin from the CDN; MapLibre wraps it in a same-origin blob URL
+    // itself. Pinned to an exact version: unpkg answers a version range
+    // (@6) with a redirect, and a browser refuses a worker script that
+    // redirects ("Refused to cross-origin redirects of the top-level worker
+    // script" — the map never loaded on a file:// page).
+    maplibreCss: 'https://unpkg.com/maplibre-gl@6.11.2/dist/maplibre-gl.css',
+    maplibreJs: 'https://unpkg.com/maplibre-gl@6.11.2/dist/maplibre-gl.mjs',
     // Bumped 8.9.35 -> 9.4.0 (2026-09-21, globe-reprojection fix): v8's
     // interleaving (MapboxOverlay) always computed flat Web-Mercator
     // screen positions regardless of the map's actual projection —
@@ -117,6 +130,49 @@
       document.head.appendChild(el);
     });
   }
+  // MapLibre 6's ES module → the window.maplibregl the engine and pages use
+  // (a copy of its named exports: a module namespace is read-only)
+  function loadMaplibre(src) {
+    installFileWorkerShim();
+    return import(src).then(mod => {
+      global.maplibregl = Object.assign({}, mod.default || {}, mod);
+    }, err => { throw new Error(`[ixmaps-gl] failed to load ${src}: ${err && err.message}`); });
+  }
+  // MapLibre 6 starts its worker as a module worker; for a worker on the
+  // CDN it wraps it in a blob URL (`import "…maplibre-gl-worker.mjs"`).
+  // On a file:// page Chrome refuses every module worker from a blob URL
+  // ("Refused to cross-origin redirects of the top-level worker script" —
+  // the map never loaded), while a module worker from a data: URL works.
+  // Only there, and only for MapLibre's own wrapper, the Worker is started
+  // from the same import as a data: URL. Other workers are untouched.
+  function installFileWorkerShim() {
+    if (!global.location || global.location.protocol !== 'file:' || !global.Worker || global.Worker.__ixmapsGlFileShim) return;
+    const NativeBlob = global.Blob, NativeWorker = global.Worker;
+    const maplibreWorkerImport = new WeakMap(); // Blob → its import statement
+    const blobUrls = new Map();                 // blob: URL → import statement
+    const isMaplibreImport = t => typeof t === 'string' && /^import "https?:[^"]*\/maplibre-gl-worker(-dev)?\.mjs"$/.test(t);
+    function Blob(parts, opts) {
+      const b = new NativeBlob(parts, opts);
+      if (Array.isArray(parts) && parts.length === 1 && isMaplibreImport(parts[0])) maplibreWorkerImport.set(b, parts[0]);
+      return b;
+    }
+    Blob.prototype = NativeBlob.prototype;
+    global.Blob = Blob;
+    const nativeCreate = global.URL.createObjectURL;
+    global.URL.createObjectURL = function (obj) {
+      const u = nativeCreate.call(this, obj);
+      if (maplibreWorkerImport.has(obj)) blobUrls.set(u, maplibreWorkerImport.get(obj));
+      return u;
+    };
+    function Worker(url, opts) {
+      const imp = blobUrls.get(String(url));
+      if (imp && opts && opts.type === 'module') return new NativeWorker('data:text/javascript,' + encodeURIComponent(imp), opts);
+      return new NativeWorker(url, opts);
+    }
+    Worker.prototype = NativeWorker.prototype;
+    Worker.__ixmapsGlFileShim = true;
+    global.Worker = Worker;
+  }
   function loadStylesheet(href) {
     return new Promise((resolve, reject) => {
       const el = document.createElement('link');
@@ -188,7 +244,7 @@
       }
       if (i === 2) return true;
     }
-    console.warn(`[ixmaps-gl] this page loads maplibre-gl ${v || '(unknown version)'}; deck.gl needs >= ${MAPLIBRE_MIN_VERSION.join('.')} — loading ${LIB_URLS.maplibreJs.match(/maplibre-gl@([\d.]+)/)[1]}.x instead (it replaces window.maplibregl); remove the page's own maplibre-gl <script> tag`);
+    console.warn(`[ixmaps-gl] this page loads maplibre-gl ${v || '(unknown version)'}; deck.gl needs >= ${MAPLIBRE_MIN_VERSION.join('.')} — loading ${LIB_URLS.maplibreJs.match(/maplibre-gl@([\d.]+)/)[1]} instead (it replaces window.maplibregl); remove the page's own maplibre-gl <script> tag`);
     return false;
   }
   // data.js, unless the page has it already: .options({datajs: url}) loads
@@ -213,12 +269,16 @@
   function ensureLibrariesLoaded() {
     if (!_librariesPromise) {
       _librariesPromise = Promise.all([
-        pageMaplibreUsable() ? Promise.resolve() : loadScript(LIB_URLS.maplibreJs),
+        pageMaplibreUsable() ? Promise.resolve() : loadMaplibre(LIB_URLS.maplibreJs),
         pageDeckUsable() ? Promise.resolve() : loadScript(LIB_URLS.deck),
         global.Mustache ? Promise.resolve() : loadScript(LIB_URLS.mustache),
         [...document.styleSheets].some(s => s.href === LIB_URLS.maplibreCss) ? Promise.resolve() : loadStylesheet(LIB_URLS.maplibreCss)
       ]).then(() => {
         ({ IconLayer, ScatterplotLayer, GeoJsonLayer, MapLibreOverlay, TextLayer } = global.deck);
+        // which engine and libraries this page really runs (a page may
+        // bring its own MapLibre/deck.gl — the loaded ones are named)
+        const ml = global.maplibregl && typeof global.maplibregl.getVersion === 'function' ? global.maplibregl.getVersion() : '?';
+        console.info(`[ixmaps-gl] ${IXMAPS_GL_VERSION} · MapLibre ${ml} · deck.gl ${global.deck.VERSION || '?'}`);
         // Matches the real engine's own ui/js/tools/tooltip_mustache.js,
         // which overrides Mustache.escape to identity: tooltip HTML (the
         // template itself, and this engine's own chart/data-table
@@ -2668,6 +2728,16 @@
       // broker re-queries its data from it. Read at call time: pages wrap
       // it after loading. flat passes its SVG zoom scale; this passes the
       // flat zoom level, the one value gl has.
+      //
+      // gl also calls it DURING a zoom (notifyZoomAndPanMidGesture, wired
+      // into the throttled refresh below), zoom changes only: the scale
+      // gates (featurelower/chartupper ...) switch on the live zoom while
+      // the gesture runs, so a page that ties something zoom-dependent to
+      // this hook (e.g. a basemap opacity ramp) must be told in the same
+      // tick — from 'moveend' alone it arrived after the gate had already
+      // flipped (FEATURE gone, basemap still at the old, faint opacity: a
+      // blank background until the zoom ended).
+      let notifyZoomAndPanMidGesture = () => {};
       {
         let last = null;
         map.on('moveend', () => {
@@ -2679,6 +2749,14 @@
           if (z === prev.z && Math.abs(p.x - q.x) <= 10 && Math.abs(p.y - q.y) <= 10) return;
           try { hook.call(global.ixmaps, mapLibreToFlatZoom(z)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onZoomAndPan:', e); }
         });
+        notifyZoomAndPanMidGesture = () => {
+          const hook = pageIxmaps() && pageIxmaps().htmlgui_onZoomAndPan;
+          if (typeof hook !== 'function' || !last) return;
+          const z = map.getZoom();
+          if (z === last.z) return; // a pan alone waits for 'moveend' (and its 10 px rule)
+          last = { z, c: map.getCenter() };
+          try { hook.call(global.ixmaps, mapLibreToFlatZoom(z)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onZoomAndPan:', e); }
+        };
         // flat calls it on the first draw too (its old zoom is unset then)
         map.once('load', () => {
           last = { z: map.getZoom(), c: map.getCenter() };
@@ -3818,10 +3896,11 @@
         const elapsed = now - lastRefreshAt;
         if (elapsed >= REFRESH_INTERVAL_MS) {
           lastRefreshAt = now;
+          notifyZoomAndPanMidGesture();
           refreshLayers();
         } else {
           clearTimeout(refreshTimer);
-          refreshTimer = setTimeout(() => { lastRefreshAt = Date.now(); refreshLayers(); }, REFRESH_INTERVAL_MS - elapsed);
+          refreshTimer = setTimeout(() => { lastRefreshAt = Date.now(); notifyZoomAndPanMidGesture(); refreshLayers(); }, REFRESH_INTERVAL_MS - elapsed);
         }
         scheduleNotifyRedraw();
       }
@@ -9887,6 +9966,8 @@
     szResourceBase: ixmapsSzResourceBase, getProjectString, setProjectJSON, loadProject,
     markThemeClass, unmarkThemeClass, getBoundingBox, setTitle, setTitleBox, refreshTheme, formatValue: flatFormatValue,
     map: mapHandle, getZoom,
+    // this engine's version (flat's own ixmaps.version numbers flat)
+    glVersion: IXMAPS_GL_VERSION,
     // flat always has this page hook (its layer legend tool defines it,
     // ui/js/tools/layer_legend.js 702-712): pages wrap it and call the one
     // they replaced — the chain ends here
@@ -9905,6 +9986,7 @@
   // test-only: lets test/unit/*.test.mjs call pure internals directly (the
   // engine runs in a Node vm there); deliberately NOT on the ixmaps object
   global.__ixmapsGlInternals = {
+    IXMAPS_GL_VERSION,
     normalizeTheme, projectThemeToDefinition, LayerBuilder, LayerRuntime, typeStyleNumbers, styleNum,
     resolveScriptUrl, isTrustedScriptUrl, loadProcessingScript, loadBrokerData, applyBrokerThemePatch, makeBrokerTheme,
     equalIntervalBreaks, quantileBreaks, naturalBreaks, evenStrideSample, jenksBreakValues, partsFromBreakValues, resolvePartsClass,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ixmaps-gl",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "MapLibre GL + deck.gl reimplementation of the ixmaps-flat declarative mapping engine",
   "main": "ixmaps-gl.js",
   "browser": "ixmaps-gl.js",