ixmaps-gl 0.2.8 → 0.2.10

package/ixmaps-gl.js

@@ -20,8 +20,9 @@
 // from the same bound value by default, or from .binding({alpha,
 // alpha100}) when set (alpha100:"$density$" divides by the polygon's
 // own geodesic area — see _prepareAlphaField/_resolveDopacityAlpha).
-// CATEGORICAL choropleths aren't implemented, see
-// _buildChoroplethLayers), and the CHART|SYMBOL|
+// AGGREGATE CATEGORICAL on one field paints each polygon in its records'
+// dominant category; a plain CATEGORICAL choropleth is not implemented,
+// see _buildChoroplethLayers), and the CHART|SYMBOL|
 // GLOW|CATEGORICAL|AGGREGATE|COUNT|RELOCATE|VALUES pipeline (categorical
 // clustering + sizing + glow + multi-bubble grouping + on-bubble value
 // labels, generalized to however many distinct category values the DATA
@@ -81,7 +82,7 @@
   // ---------------------------------------------------------------
   // 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.8';
+  const IXMAPS_GL_VERSION = '0.2.10';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -307,7 +308,7 @@
   // crafted link must not be able to load arbitrary code into the page.
   // ---------------------------------------------------------------
   // v0.1.6: knows this engine's aliases, lookupfield rule, meta↔style, builder methods, project loading
-  const VALIDATOR_URL_DEFAULT = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-grammar@v0.1.23/dist/validate.mjs';
+  const VALIDATOR_URL_DEFAULT = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-grammar@v0.1.24/dist/validate.mjs';
   // a page may set ixmaps.validate BEFORE loading this script — the
   // `global.ixmaps = {...}` export below would otherwise overwrite it
   const _preloadValidate = global.ixmaps && global.ixmaps.validate;
@@ -1464,8 +1465,53 @@
   function featureAreaKm2(f) {
     return f._flatAreaKm2 !== undefined ? f._flatAreaKm2 : geodesicPolygonAreaKm2(f.geometry);
   }
+  // .type("CHOROPLETH|CATEGORICAL|AGGREGATE") on ONE value field (e.g.
+  // DOMINANT over the categories of "missione"): flat aggregates every
+  // record of a polygon into a part per category — the sum of the size
+  // field (else the record count, resolveAggregateValue) — and paints the
+  // dominant part's class (maptheme.js 13520-13565)
+  const AGGREGATED_ROWS = Symbol('ixmaps-gl aggregated rows');
+  function isAggregatedCategoricalChoropleth(spec) {
+    const flags = spec.flags;
+    return !!(flags && flags.has('CHOROPLETH') && flags.has('CATEGORICAL') && flags.has('AGGREGATE')
+      && spec.binding && spec.binding.value && !String(spec.binding.value).includes('|'));
+  }
+  // a polygon's parts (sum per category) and its dominant one: the biggest
+  // part above 0, the first of equal ones; null without any
+  function aggregatedCategoricalClass(rows, binding, flags, indexByLabel, nCats) {
+    const parts = new Array(nCats).fill(0);
+    for (const row of rows) {
+      const i = indexByLabel.get(String(row[binding.value]));
+      if (i == null) continue;
+      parts[i] += resolveAggregateValue(binding, flags, row);
+    }
+    let index = -1;
+    parts.forEach((v, i) => { if (v > 0 && (index < 0 || v > parts[index])) index = i; });
+    return index < 0 ? null : { parts, index, value: parts[index] };
+  }
+  // flat's DOMINANT opacity (maptheme.js 13567-13628): from the dominant
+  // part v and the biggest part of that class over all polygons, max —
+  // DOPACITYMAX dopacityscale · (v / max)^(1/dopacitypow), DOPACITYLOGMAX
+  // log v / log max, plain DOPACITY log(dopacityscale · v) / log max;
+  // below 0.0001 → 0, at most 0.9
+  function dominantDopacityAlpha(style, flags, v, max) {
+    const scale = styleNum(style.dopacityscale) || 1;
+    const pow = 1 / (styleNum(style.dopacitypow) || 1);
+    let o;
+    if (flags.has('DOPACITYLOGMAX')) o = Math.log(v) / Math.log(max);
+    else if (flags.has('DOPACITYMAX') || flags.has('DOPACITYPOWMAX')) o = scale * Math.pow(v, pow) / Math.pow(max, pow);
+    else o = Math.log(scale * v) / Math.log(max);
+    if (!(o >= 0.0001)) o = 0;
+    return Math.min(0.9, o);
+  }
+
   function joinChoroplethFeatures(spec, table, runtimes) {
-    const geomRt = runtimes.find(r => r.name === spec.name && (r.flags.has('FEATURE') || r.flags.has('FEATURES')));
+    // a page can define several FEATURE layers of one name — e.g. the
+    // comuni as polygons and as center points (for chart positions); flat
+    // paints every shape of the layer with a matching id, so the polygons
+    // are the ones that show: prefer a base with polygon geometry
+    const bases = runtimes.filter(r => r.name === spec.name && (r.flags.has('FEATURE') || r.flags.has('FEATURES')));
+    const geomRt = bases.find(r => (r.features || []).some(f => f.geometry && /Polygon/.test(f.geometry.type))) || bases[0];
     if (!geomRt) {
       throw new Error(`[ixmaps-gl] CHOROPLETH layer "${spec.name}" needs a FEATURE base layer with the same name, .layer()'d earlier on the map`);
     }
@@ -1488,6 +1534,27 @@
     if (!idField || !lookupField) {
       throw new Error(`[ixmaps-gl] CHOROPLETH layer "${spec.name}" needs .binding({lookup}), and its FEATURE base needs .binding({id})`);
     }
+    // an AGGREGATE CATEGORICAL choropleth sums ALL the rows of a polygon
+    // per category (aggregatedCategoricalClass) — every row is kept, under
+    // AGGREGATED_ROWS (not enumerable: the first row stays the polygon's
+    // properties for the tooltip and filters)
+    if (isAggregatedCategoricalChoropleth(spec)) {
+      const groups = new Map();
+      for (const row of table.rows) {
+        const key = String(row[lookupField]);
+        if (!groups.has(key)) groups.set(key, []);
+        groups.get(key).push(row);
+      }
+      return {
+        type: 'FeatureCollection',
+        features: geomRt.features.map(f => {
+          const rows = groups.get(String(f.properties[idField]));
+          const properties = rows ? Object.assign({}, rows[0]) : {};
+          if (rows) Object.defineProperty(properties, AGGREGATED_ROWS, { value: rows });
+          return { type: 'Feature', geometry: f.geometry, properties, _flatAreaKm2: flatShapeAreaKm2(geomRt, f) };
+        })
+      };
+    }
     const rowsByKey = new Map(table.rows.map(row => [String(row[lookupField]), row]));
     // Unmatched polygons (no CSV row for that id) keep their geometry with
     // empty properties — real-world data: not every comune necessarily has
@@ -1905,91 +1972,6 @@
     }
   }
 
-  // flat's page hook ixmaps.htmlgui_onNewTheme(szId), called when a theme
-  // is created (maptheme.js 927) — with the theme's id (its name)
-  function themeIdOf(rt) {
-    return (rt.style && rt.style.name) || (rt.meta && rt.meta.name) || rt.name;
-  }
-  function notifyNewTheme(rt) {
-    const hook = pageIxmaps() && pageIxmaps().htmlgui_onNewTheme;
-    if (typeof hook !== 'function') return;
-    try { hook.call(global.ixmaps, themeIdOf(rt)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onNewTheme:', e); }
-  }
-
-  // flat's ixmaps.map() — the running map's handle (htmlgui.js 173ff,
-  // htmlgui_flat.js). Its methods act on the last built map; called while
-  // the map is still building, they run once it is ready.
-  const MAP_HANDLE_METHODS = ['replace', 'add', 'remove', 'removeTheme', 'replaceTheme', 'changeThemeStyle', 'setThemeStyle',
-    'refreshTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible'];
-  const _mapHandle = {};
-  for (const m of MAP_HANDLE_METHODS) {
-    _mapHandle[m] = (...args) => {
-      if (_lastMapApi) { const r = _lastMapApi[m](...args); return r === _lastMapApi ? _mapHandle : r; }
-      _mapReady.then(api => api[m](...args));
-      return _mapHandle;
-    };
-  }
-  _mapHandle.getZoom = () => (_lastMapApi ? _lastMapApi.getZoom() : undefined);
-  _mapHandle.getThemeObj = id => getThemeObj(id);
-  function mapHandle() { return _mapHandle; }
-
-  // flat's ixmaps.formatValue(value, precision, flag) (ui/js/tools/format.js),
-  // which user chart scripts call: thousands separated by "." (BLANK: a
-  // space), the decimals after "," (BLANK: "."), CEIL / FLOOR rounding
-  function flatFormatPart(nPart, szLeading) {
-    szLeading = szLeading || '';
-    let szPart = '';
-    if (nPart < 100) szPart += szLeading;
-    if (nPart < 10) szPart += szLeading;
-    if (nPart === 0) szPart += szLeading;
-    else szPart += String(nPart);
-    return szPart;
-  }
-  function flatFormatValue(nValue, nPrecision, szFlag) {
-    nValue = Number(nValue);
-    if (!isFinite(nValue) || !isFinite(nPrecision)) return String(nValue);
-    if (nValue === 0) return String(nValue);
-    if (nValue > 1000000000000 || nValue < -1000000000000) return String(nValue);
-    nPrecision = Math.max(0, nPrecision || 0);
-    if (nValue > 0.0000001 && nPrecision > 0) {
-      while (Number(nValue.toFixed(nPrecision - 1)) === 0) nPrecision++;
-    }
-    let v = Number(nValue.toFixed(nPrecision + 1));
-    const clip = Math.pow(10, nPrecision);
-    if (szFlag && /CEIL/.test(szFlag)) v = Math.ceil(v * clip) / clip;
-    else if (szFlag && /FLOOR/.test(szFlag)) v = Math.floor(v * clip) / clip;
-    else v = Math.round(v * clip) / clip;
-    let szDecimals = String(v);
-    if (/\./.test(szDecimals)) {
-      szDecimals = szDecimals.split('.')[1];
-      while (szDecimals.length < nPrecision) szDecimals += '0';
-    } else szDecimals = '';
-    let szReturn = v < 0 ? '-' : '';
-    let szLeading = '';
-    let n = Math.floor(Math.abs(v));
-    if (!szFlag || !/NOBREAKS/.test(szFlag)) {
-      let nClip = 1000;
-      while (n > nClip) nClip *= 1000;
-      nClip /= 1000;
-      let szBreak = ' ';
-      while (nClip >= 1000) {
-        const nPart = Math.floor(n / nClip);
-        szReturn += flatFormatPart(nPart, szLeading);
-        n = n % nClip;
-        nClip /= 1000;
-        if (nPart) {
-          szLeading = '0';
-          szBreak = szFlag && /SPACE/.test(szFlag) ? '<span style="font-size:0.5em;">&nbsp;</span>' : szFlag && /BLANK/.test(szFlag) ? '&nbsp;' : '.';
-        }
-        szReturn += szBreak;
-      }
-    }
-    szReturn += flatFormatPart(n, szLeading);
-    if (!szReturn.length || szReturn === '-') szReturn += '0';
-    if (szDecimals.length && szDecimals !== '00') szReturn += (szFlag && /BLANK/.test(szFlag) ? '.' : ',') + szDecimals;
-    return szReturn;
-  }
-
   // ---- USER charts: a page's own chart function (style.userdraw) ----
   // flat calls ixmaps.<userdraw>_init(SVGDocument, {target, theme}) once
   // per realize (maptheme.js 17000-17050) and ixmaps.<userdraw>(SVGDocument,
@@ -2034,57 +2016,6 @@
   // packs them into one texture (1024 px wide), which must stay well below
   // the GPU's texture size limit — see _userChartIcon
   const USER_CHART_ATLAS_AREA = 1024 * 8192;
-  function getZoom() { return _lastMapApi ? _lastMapApi.getZoom() : undefined; }
-
-  // flat's ixmaps.getBoundingBox() (htmlgui_sync_Leaflet_VT.js
-  // htmlMap_getBounds): [{lat, lng} south-west, {lat, lng} north-east] of
-  // the view, latitude clamped to ±85.05, longitude not capped. Set by the
-  // last build(): a broker (data.type "ext") is called while its map is
-  // still building, so until the MapLibre map exists the bounds come from
-  // the requested view and the container size (MapLibre's 512 px tiles).
-  let _boundsSource = null;
-  function viewBounds(lat, lng, mlZoom, width, height) {
-    const world = 512 * Math.pow(2, mlZoom);
-    const x = (lng + 180) / 360 * world;
-    const s = Math.sin(Math.max(-85.05, Math.min(85.05, lat)) * Math.PI / 180);
-    const y = (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * world;
-    const lngAt = px => px / world * 360 - 180;
-    const latAt = py => Math.atan(Math.sinh(Math.PI * (1 - 2 * py / world))) * 180 / Math.PI;
-    return [{ lat: latAt(y + height / 2), lng: lngAt(x - width / 2) }, { lat: latAt(y - height / 2), lng: lngAt(x + width / 2) }];
-  }
-  function getBoundingBox() {
-    const b = _boundsSource ? _boundsSource() : null;
-    if (!b) return null;
-    return [{ lat: Math.max(b[0].lat, -85.05), lng: b[0].lng }, { lat: Math.min(b[1].lat, 85.05), lng: b[1].lng }];
-  }
-
-  // flat's ixmaps.setTitle(html) / setTitleBox(text, color) (htmlgui.js
-  // 1311-1331): a message line over the last built map, same markup as
-  // flat's default (legend not aligned left); '' clears it.
-  let _titleHost = null;
-  function setTitle(szTitle) {
-    if (!_titleHost) return;
-    let box = _titleHost.querySelector(':scope > .ixmaps-gl-title');
-    if (!box) {
-      box = document.createElement('div');
-      box.className = 'ixmaps-gl-title';
-      box.style.cssText = 'position:absolute;top:11px;left:0;z-index:3;pointer-events:none;';
-      _titleHost.appendChild(box);
-    }
-    box.innerHTML = szTitle
-      ? "<div style='position:relative;left:100px;top:2px;font-style:arial,helvetica;font-size:22px'>" + szTitle + '</div>'
-      : '';
-  }
-  function setTitleBox(szTitle, szColor) {
-    setTitle("<span style='display:inline-flex;align-items:center;height:38px;box-sizing:border-box;padding:0 12px;border:1px solid #46494c;border-radius:8px;font-size:14px;font-family:courier new,Raleway,arial,helvetica;background:" + (szColor || 'rgba(255,255,255,0.95)') + ';color:' + (szColor ? '#fff' : '#222') + "'>" + szTitle + '</span>');
-  }
-  // flat's ixmaps.refreshTheme(szId): reloads the theme's data on the last
-  // built map (a broker is called again) — see engineApi.refreshTheme
-  function refreshTheme(szId) {
-    if (!_lastMapApi || !_lastMapApi.refreshTheme) return;
-    _lastMapApi.refreshTheme(szId).catch(err => console.error('[ixmaps-gl] refreshTheme:', err));
-  }
-
   class LayerBuilder {
     constructor(name) {
       this.name = name;
@@ -2194,7 +2125,7 @@
   // edit it by hand; `npm run unit` fails when it drifts.
   // ---------------------------------------------------------------
   // <grammar:binding-aliases>
-  // generated from ixmaps-grammar 0.1.23 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
+  // generated from ixmaps-grammar 0.1.24 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
   const FLAT_BINDING_ALIASES = {
     "aggregation": "style.aggregationfield",
     "aggregationfield": "style.aggregationfield",
@@ -2256,7 +2187,7 @@
   // both — so .style({tooltip}) is a tooltip and .meta({fillopacity}) a style
   // property. GENERATED by test/sync-grammar.mjs — do not edit.
   // <grammar:meta-keys>
-  // generated from ixmaps-grammar 0.1.23 — 5 meta keys
+  // generated from ixmaps-grammar 0.1.24 — 5 meta keys
   const FLAT_META_KEYS = ["description","name","snippet","title","tooltip"];
   // </grammar:meta-keys>
 
@@ -2712,6 +2643,916 @@
     };
   }
 
+  // ---------------------------------------------------------------
+  // Hover tooltips and the click-to-pin tooltip of a map, built once per map
+  // by MapBuilder.build(). ctx: the builder (its map options, for the
+  // tooltip look), the MapLibre map, its container element and
+  // findRuntimeForLayerId (the theme of a drawn deck.gl layer). Returns the
+  // overlay's getTooltip / onClick handlers and mount(), which adds the
+  // pinned tooltip to the page and keeps it on its place while the map moves.
+  // ---------------------------------------------------------------
+  function createTooltips(ctx) {
+    const { builder, map, el, findRuntimeForLayerId } = ctx;
+    // Click-to-pin tooltip: matches the real ixmaps engine's own
+    // click-pins-the-tooltip convention in pan mode (a hover tooltip is
+    // transient; a click keeps one visible until dismissed). This is a
+    // separate DOM element from deck.gl's own hover tooltip (so hovering
+    // a DIFFERENT bubble still shows a normal transient tooltip even
+    // while one is pinned) — its content is a snapshot of buildTooltipHtml
+    // at click time (not live-updating), but its screen POSITION is kept
+    // in sync with the map on every pan/zoom via map.project().
+    let pinned = null; // { runtime, object, lngLat }
+    // Tooltip look, like the legend's (flatLegendLook): flat's light
+    // tooltip (tooltip_mustache.js: white 0.95, #444 text, thin black
+    // border, 5px radius) on light basemaps, this engine's dark tooltip
+    // on dark ones. Read when shown, so options set later (a
+    // myMap.then(...).options({basemapopacity})) count.
+    const tooltipLook = () => {
+      const o = parseFloat(builder._engineOptions.basemapopacity);
+      const look = flatLegendLook(builder.mapOptions.mapType, isNaN(o) ? 1 : o, builder.mapOptions.legendBackground || builder.mapOptions.legendbackground);
+      return look.dark
+        ? { background: 'rgb(41,50,60)', color: 'rgb(200,205,214)', border: 'none', borderRadius: '4px', boxShadow: '0 2px 8px rgba(0,0,0,0.3)' }
+        : { background: 'rgba(255,255,255,0.95)', color: '#444', border: '0.5px solid black', borderRadius: '5px',
+            boxShadow: 'rgba(0,0,0,0.2) 0px 2px 4px 0px, rgba(0,0,0,0.19) 0px 3px 10px 0px' };
+    };
+    const pinnedTooltipEl = document.createElement('div');
+    pinnedTooltipEl.style.cssText = 'position:absolute;top:0;left:0;z-index:6;display:none;' +
+      'pointer-events:auto;max-width:320px;max-height:320px;overflow:auto;' +
+      'padding:0.6em 1.6em 0.6em 0.7em;font-size:0.85em;';
+
+    function updatePinnedTooltipPosition() {
+      if (!pinned) return;
+      const pt = map.project(pinned.lngLat);
+      pinnedTooltipEl.style.transform = `translate(${pt.x + 10}px, ${pt.y - 10}px)`;
+    }
+
+    // A stable per-geometry anchor coordinate for the identity check
+    // below — only a Point's OWN coordinates are an [lng,lat] pair;
+    // Polygon/MultiPolygon nest rings of them, so the first ring's
+    // first vertex stands in instead (stable across rebuilds for the
+    // same underlying feature, same as the Point case: this.features'
+    // geometry references don't change shape between
+    // _buildChoroplethLayers calls, only the wrapping properties do).
+    function anchorCoordOf(geometry) {
+      if (!geometry) return null;
+      if (geometry.type === 'Point') return geometry.coordinates;
+      if (geometry.type === 'Polygon') return geometry.coordinates[0] && geometry.coordinates[0][0];
+      if (geometry.type === 'MultiPolygon') return geometry.coordinates[0] && geometry.coordinates[0][0] && geometry.coordinates[0][0][0];
+      return null;
+    }
+
+    // Identity check for "is this hovered object the same one that's
+    // pinned" — object references are rebuilt from scratch on every
+    // redraw (new individual/group arrays each buildDeckLayers call), so
+    // reference equality never works here. Same layer + same geometry
+    // position is a reasonable proxy: individual points and aggregated
+    // groups alike are keyed by position within a layer, matching how
+    // clustering itself already treats "same position" as "same thing".
+    function isSameAsPinned(layerId, object) {
+      if (pinned.layerId !== layerId) return false;
+      const a = anchorCoordOf(object.geometry);
+      const b = anchorCoordOf(pinned.object.geometry);
+      if (!a || !b) return false;
+      return Math.abs(a[0] - b[0]) < 1e-9 && Math.abs(a[1] - b[1]) < 1e-9;
+    }
+
+    // content lives in its own child so re-rendering (innerHTML) never
+    // wipes out the unpin button below (a sibling, not a descendant of it)
+    const pinnedContentEl = document.createElement('div');
+    pinnedTooltipEl.appendChild(pinnedContentEl);
+
+    function renderPinnedTooltip() {
+      if (!pinned) { pinnedTooltipEl.style.display = 'none'; return; }
+      const html = pinned.runtime.buildTooltipHtml(pinned.object);
+      if (!html) { pinned = null; pinnedTooltipEl.style.display = 'none'; return; }
+      pinnedContentEl.innerHTML = html;
+      Object.assign(pinnedTooltipEl.style, tooltipLook());
+      pinnedTooltipEl.style.display = 'block';
+      updatePinnedTooltipPosition();
+    }
+
+    const unpinBtn = document.createElement('button');
+    unpinBtn.type = 'button';
+    unpinBtn.setAttribute('aria-label', 'chiudi');
+    unpinBtn.title = 'chiudi';
+    unpinBtn.textContent = '×';
+    unpinBtn.style.cssText = 'position:absolute;top:5px;right:5px;width:1.5em;height:1.5em;padding:0;' +
+      'display:flex;align-items:center;justify-content:center;border:none;border-radius:50%;' +
+      'background:rgba(255,255,255,0.18);color:inherit;font-size:1em;line-height:1;font-weight:bold;cursor:pointer';
+    unpinBtn.addEventListener('mouseenter', () => { unpinBtn.style.background = 'rgba(255,255,255,0.35)'; });
+    unpinBtn.addEventListener('mouseleave', () => { unpinBtn.style.background = 'rgba(255,255,255,0.18)'; });
+    unpinBtn.addEventListener('click', () => { pinned = null; pinnedTooltipEl.style.display = 'none'; });
+    pinnedTooltipEl.style.position = 'absolute';
+    pinnedTooltipEl.appendChild(unpinBtn);
+
+    // deck.gl's own default hover tooltip is only recomputed on pointer-
+    // move events, not on click — so right after a click, it's still
+    // showing whatever it rendered from the hover that was already
+    // active (the same item we just pinned), and won't hide itself just
+    // because getTooltip would now return null for it. Nothing re-asks
+    // it until the next real mousemove. Force it closed here instead —
+    // deferred one frame so it wins even if deck.gl's own click handling
+    // touches the tooltip DOM in the same tick.
+    function hideDefaultHoverTooltip() {
+      requestAnimationFrame(() => {
+        const defaultTooltipEl = el.parentElement && el.parentElement.querySelector('.deck-tooltip');
+        if (defaultTooltipEl) defaultTooltipEl.style.display = 'none';
+      });
+    }
+
+    let tooltipErrorLogged = false;
+    // a USER chart's picked item is {d, icon} (see _buildUserChartLayers):
+    // the feature is its d
+    function pickedFeature(o) { return o && o.icon && o.d ? o.d : o; }
+    function tooltipFor({ object: picked, layer }) {
+        const object = pickedFeature(picked);
+        if (!object || !layer) return null;
+        // suppress the hover tooltip ONLY for the specific item that's
+        // pinned (showing both would just duplicate the same content) —
+        // every OTHER item still gets its normal hover preview even
+        // while something else stays pinned
+        if (pinned && isSameAsPinned(layer.id, object)) return null;
+        const rt = findRuntimeForLayerId(layer.id);
+        if (!rt) return null;
+        const html = rt.buildTooltipHtml(object);
+        return html ? { html, style: Object.assign({ fontSize: '0.85em', padding: '0.5em 0.7em', maxWidth: '320px' }, tooltipLook()) } : null;
+    }
+    function clickFor(picked) {
+        const info = picked && Object.assign({}, picked, { object: pickedFeature(picked.object) });
+        if (info && info.object && info.layer) {
+          const rt = findRuntimeForLayerId(info.layer.id);
+          if (rt) {
+            // Only a Point geometry's own coordinates ARE an
+            // [lng,lat] pair (every point/bubble/dot/chart-cluster
+            // layer) — a CHOROPLETH polygon's geometry.coordinates is
+            // a nested array of RINGS, which map.project() below
+            // can't accept (confirmed live: threw MapLibre's own
+            // "LngLatLike argument must be..." error). The `||
+            // info.coordinate` fallback this used to lean on never
+            // actually ran for a polygon — a nested array is truthy,
+            // so the left side always "won" — which is the real bug
+            // this fixes: the pinned tooltip stuck at its default
+            // top:0/left:0 (never got a real position because
+            // updatePinnedTooltipPosition's map.project() threw
+            // before setting one), AND that same uncaught exception,
+            // thrown from inside deck.gl's own click-dispatch
+            // callback, left deck.gl's pointer-interaction state
+            // corrupted enough to block all further pan/zoom —
+            // confirmed live, both symptoms disappear together once
+            // this stops throwing. info.coordinate (the actual
+            // clicked map location, provided regardless of feature
+            // geometry type) anchors every non-Point case correctly.
+            const lngLat = (info.object.geometry && info.object.geometry.type === 'Point')
+              ? info.object.geometry.coordinates
+              : info.coordinate;
+            pinned = { runtime: rt, object: info.object, lngLat, layerId: info.layer.id };
+            renderPinnedTooltip();
+            hideDefaultHoverTooltip();
+            return true;
+          }
+        }
+        // clicked empty map space (or a non-tooltippable layer) -> unpin
+        pinned = null;
+        pinnedTooltipEl.style.display = 'none';
+        return false;
+    }
+    // An exception thrown from these callbacks runs inside deck.gl's
+    // own render frame / event dispatch and leaves its frame and
+    // interaction state broken — the map stopped showing new layers
+    // after zooms and pans (a USER chart's hover threw on every frame
+    // the mouse was over an arrow, see pickedFeature). Both are guarded.
+    function getTooltip(info) {
+      try { return tooltipFor(info); } catch (err) {
+        if (!tooltipErrorLogged) { tooltipErrorLogged = true; console.error('[ixmaps-gl] tooltip failed:', err); }
+        return null;
+      }
+    }
+    function onClick(info) {
+      try { return clickFor(info); } catch (err) {
+        console.error('[ixmaps-gl] click failed:', err);
+        return false;
+      }
+    }
+    function mount() {
+      map.on('move', updatePinnedTooltipPosition);
+      if (el.parentElement) {
+        el.parentElement.style.position = el.parentElement.style.position || 'relative';
+        el.parentElement.appendChild(pinnedTooltipEl);
+      }
+    }
+    return { getTooltip, onClick, mount };
+  }
+
+  // ---------------------------------------------------------------
+  // The map's native interactive legend, built once per map by
+  // MapBuilder.build(). ctx: the builder (its map options), the MapLibre
+  // map, its container element, the deck.gl overlay, the runtimes, the
+  // engine API and its refresh hooks. Returns the four hooks the map
+  // calls: addLegendPanel(rt), setLegendOption(value), updateSubTheme(rt),
+  // layoutLegends().
+  // ---------------------------------------------------------------
+  function createLegend(ctx) {
+    const { builder, map, el, overlay, runtimes, engineApi, built, refresh, scheduleRefresh, notifyRedraw } = ctx;
+    let addLegendPanel = () => {};
+    let setLegendOption = () => {};
+    let updateSubTheme = () => {};
+    let layoutLegends = () => {};
+
+    // NATIVE INTERACTIVE LEGEND — real ixmaps-flat's legend.js
+    // (makeColorLegendHTMLLong) builds, per CATEGORICAL-ish theme: a
+    // title/snippet header, one row per category (color swatch + a bar
+    // proportional to that category's own total + right-aligned
+    // formatted value), a description/source footer, and a per-theme
+    // "Chart size" 25-200% slider — all read directly off source
+    // (ui/js/tools/legend.js:594-1037/3196-3393, ui/js/htmlgui.js:2196/
+    // 2208 for markThemeClass/unmarkThemeClass, ui/css/legend.css for
+    // the selected-row highlight) rather than guessed from the
+    // screenshot alone. Gated on `legend:"open"` — the one real map
+    // option this engine's own createMap already threads through as
+    // builder.mapOptions (see mapOptions.legend below) — since there's no
+    // toolbar toggle button here to open/close it later the way the
+    // real engine's own chrome does.
+    //
+    // Deliberate divergences from the real implementation, both
+    // reasoned rather than accidental:
+    //   - Real legend.js does a full innerHTML rebuild on every single
+    //     theme redraw (even a bare click-toggle). renderRows() below
+    //     only rebuilds the ROWS (swatch/bar/value/highlight) — cheap,
+    //     and the only part that can actually change post-load (marks,
+    //     or an AGGREGATE theme's dataset-wide totals, which this port
+    //     doesn't yet let change post-load anyway) — rather than
+    //     tearing down and rebuilding title/snippet/description/slider
+    //     too, which never change. Same visible result, less DOM churn.
+    //   - Real "isolate_gray" mode dims non-marked SVG paths via a CSS
+    //     class; this engine dims via IconLayer's own getColor alpha
+    //     (see LayerRuntime#_iconAlpha) since these are deck.gl raster
+    //     icons, not DOM/SVG nodes a CSS rule could reach.
+    // Legend on/off and fold state as real ixmaps-flat reads the map
+    // option (htmlgui_flat.js:748-794): on whenever `legend` is given and
+    // isn't false/"false" ("true", "open", "", 1, …), folded for
+    // "closed", off when not given at all.
+    const legendOpt = builder.mapOptions.legend;
+    // let, not const: map.setLegend(value) switches them at runtime (see setLegendOption)
+    let legendOn = legendIsOn(legendOpt);
+    let legendFolded = legendOpt === 'closed';
+    {
+      // Map-level `align` option positions the legend panel — a map-
+      // wide placement choice, not per-theme (unlike legendtheme/
+      // legendfilter above), so read once from builder.mapOptions rather
+      // than per-runtime. Real ixmaps-flat ALSO has an `align` map
+      // option (ui/js/htmlgui_flat.js) controlling legend position, but
+      // its value shape is a free-form regex-matched left/right/center/
+      // top/bottom/pixel-prefixed string tied to a static in-page DOM
+      // panel — a different layout model from this panel's own
+      // position:absolute floating-overlay-over-the-map-canvas
+      // approach. This port reuses the real OPTION NAME but adapts the
+      // VALUE SHAPE to plain four-corner tokens matching how this panel
+      // is actually positioned — a deliberate divergence, same
+      // reasoning already applied to style.legendfilter's own name/
+      // shape choice earlier this session. Default "top-right" per
+      // explicit request (real engine's own fallback is right-anchored
+      // too, just without an opinion on vertical placement).
+      const ALIGN_CSS = {
+        'top-left': 'left:10px;top:10px;',
+        'top-right': 'right:10px;top:10px;',
+        'bottom-left': 'left:10px;bottom:10px;',
+        'bottom-right': 'right:10px;bottom:10px;'
+      };
+      // gl's four corners, else flat's own values (htmlgui_flat.js
+      // 421-470): "…left" → left (the part before "left", else 55px), 12px
+      // from the top; "…right" → right (else 25px); "center" / "top" → top
+      // center
+      const flatAlignCss = align => {
+        const a = String(align || '');
+        if (/left/.test(a)) return 'left:' + (a.split('left')[0] || '55px') + ';top:12px;';
+        if (/right/.test(a)) return 'right:' + (a.split('right')[0] || '25px') + ';top:10px;';
+        if (a === 'center' || a === 'top') return 'left:50%;transform:translateX(-50%);top:10px;';
+        return null;
+      };
+      const legendAlignCss = ALIGN_CSS[builder.mapOptions.align] || flatAlignCss(builder.mapOptions.align) || ALIGN_CSS['top-right'];
+      // Real ixmaps-flat's SUB-THEME (MapTheme.createSubTheme,
+      // maptheme.js 14284-14292 / 15010-15160; map.Themes.enableSubThemes
+      // defaults to true): marking fields of a multi-field choropleth
+      // (DOMINANT/COMPOSECOLOR, not CHART) paints a new theme over the
+      // original — one field: CHOROPLETH|LOG|DOPACITY on that field, white
+      // → the field's color in 7 steps, dopacityscale 2, dopacitypow 1,
+      // keeping DOPACITY(→DOPACITYMAX)/AGGREGATE/GROUP/SUM/ZEROISVALUE/
+      // VALUES; several fields: the original type on just those fields
+      // and colors. It reuses the original's joined polygons, has no
+      // legend and stays out of the theme registry (its name
+      // "<layer>::subtheme" also keeps its deck.gl layer id apart), so
+      // markThemeClass/removeTheme still address the original.
+      const subThemeCapable = rt => rt.flags.has('CHOROPLETH') && !rt.flags.has('CHART') && (rt.flags.has('DOMINANT') || rt.flags.has('COMPOSECOLOR'));
+      const toHex = c => Array.isArray(c) ? '#' + c.slice(0, 3).map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('') : c;
+      updateSubTheme = (rt) => {
+        if (rt._subTheme) {
+          const i = runtimes.indexOf(rt._subTheme);
+          if (i >= 0) runtimes.splice(i, 1);
+          rt._subTheme = null;
+        }
+        const fields = String(rt.binding.value || '').split('|');
+        const marks = [...rt._markedClasses].filter(i => i >= 0 && i < fields.length).sort((a, b) => a - b);
+        if (marks.length) {
+          const colors = (rt.categoryColorsRgb || []).map(toHex);
+          const labels = rt.categoryDisplayLabels || rt.categoryLabels || fields;
+          const kept = ['DOPACITY', 'AGGREGATE', 'GROUP', 'SUM', 'ZEROISVALUE', 'VALUES']
+            .filter(f => [...rt.flags].some(x => x.startsWith(f) && (f !== 'DOPACITY' || /^DOPACITY/.test(x))))
+            .map(f => (f === 'DOPACITY' ? 'DOPACITYMAX' : f));
+          let def;
+          if (marks.length > 1) {
+            def = {
+              layer: rt.name + '::subtheme',
+              binding: (b => { delete b.field100; delete b.value100; return b; })(Object.assign({}, rt.binding, { value: marks.map(i => fields[i]).join('|') })),
+              style: Object.assign({}, rt.style, { type: [...rt.flags].concat(['SUBTHEME', 'NOLEGEND']).join('|'),
+                colorscheme: marks.map(i => colors[i]), values: marks.map(i => labels[i]) }),
+              meta: { title: 'actual selection' }
+            };
+          } else {
+            const i = marks[0];
+            const binding = Object.assign({}, rt.binding, { value: fields[i] });
+            delete binding.alpha; delete binding.alpha100;
+            // rt.features already carry the field100 result — drop it and
+            // every alias of it, or normalizeTheme would apply it again
+            delete binding.field100; delete binding.value100;
+            def = {
+              layer: rt.name + '::subtheme',
+              binding,
+              style: { type: ['CHOROPLETH', 'LOG', 'DOPACITY', 'NOLEGEND', 'SUBTHEME'].concat(kept).join('|'),
+                colorscheme: ['7', 'white', colors[i]], dopacityscale: 2, dopacitypow: 1,
+                units: rt.style.units, linecolor: rt.style.linecolor, linewidth: rt.style.linewidth },
+              meta: { title: 'actual selection' }
+            };
+          }
+          const sub = new LayerRuntime(normalizeTheme(def), { type: 'FeatureCollection', features: rt.features }, builder._engineOptions);
+          sub._isSubTheme = true;
+          runtimes.splice(runtimes.indexOf(rt) + 1, 0, sub);
+          rt._subTheme = sub;
+        }
+        refresh();
+        notifyRedraw();
+      };
+      // the stack of the theme panels — flat shows one theme's legend
+      // after the other in #map-legend, separated by a line, and leaves
+      // out a theme hidden, out of scale or not yet drawn
+      let legendStack = null;
+      const legendStackEl = shadow => {
+        if (legendStack && legendStack.parentNode) return legendStack;
+        legendStack = document.createElement('div');
+        legendStack.className = 'ix-legend-stack';
+        legendStack.style.cssText = 'position:absolute;' + legendAlignCss + 'z-index:6;width:280px;'
+          + 'display:flex;flex-direction:column;max-height:calc(100% - 24px);overflow-y:auto;'
+          + 'border-radius:6px;box-shadow:' + shadow + ';pointer-events:auto;';
+        if (!document.getElementById('ix-legend-stack-css')) {
+          const css = document.createElement('style');
+          css.id = 'ix-legend-stack-css';
+          css.textContent = '.ix-legend-stack>.ix-native-legend:not([data-ixoff])~.ix-native-legend:not([data-ixoff]){border-top:1px solid rgba(128,128,128,.35)}';
+          document.head.appendChild(css);
+        }
+        el.parentElement.appendChild(legendStack);
+        return legendStack;
+      };
+      // map.setLegend(value): the `legend` map option at runtime, same values as
+      // ixmaps.Map(id, {legend}) — on ("true", "open", …), folded ("closed"), off
+      // (false/"false"/0/undefined). Panels are made for themes that lack one,
+      // removed when off, folded/unfolded otherwise.
+      setLegendOption = (opt) => {
+        builder.mapOptions.legend = opt;
+        legendFolded = opt === 'closed';
+        legendOn = legendIsOn(opt);
+        runtimes.forEach(rt => {
+          if (!legendOn) {
+            if (rt._legendPanel && rt._legendPanel.parentNode) rt._legendPanel.parentNode.removeChild(rt._legendPanel);
+            rt._legendPanel = null;
+          } else if (!rt._legendPanel) addLegendPanel(rt);
+          else if (rt._setLegendCollapsed) rt._setLegendCollapsed(legendFolded);
+        });
+        layoutLegends();
+      };
+      layoutLegends = () => {
+        if (!legendStack) return;
+        const z = map.getZoom();
+        let shown = 0;
+        [...legendStack.children].forEach(panel => {
+          const rt = panel._ixRuntime;
+          const off = !rt || rt._hidden || themeHiddenByScale(rt.flags, rt.style, z);
+          if (off) { panel.setAttribute('data-ixoff', ''); panel.style.display = 'none'; }
+          else { panel.removeAttribute('data-ixoff'); panel.style.display = 'flex'; shown++; }
+        });
+        legendStack.style.display = shown ? 'flex' : 'none';
+      };
+      const legendApplies = rt => rt.categoryLabels && rt.categoryLabels.length && !rt.flags.has('FEATURE') && !rt.flags.has('FEATURES') && !rt.flags.has('NOLEGEND');
+      // One theme's panel — at build time for every theme, and again for a
+      // theme defined later (map.layer(...) in a myMap.then(...) chain,
+      // defineLayer, loadProject); removeTheme removes it with the theme.
+      addLegendPanel = (rt) => {
+        // marking a class (legend row, or ixmaps.markThemeClass from a
+        // page) redraws — for every theme, legend panel or not
+        rt._triggerRedraw = () => { refresh(); };
+        if (subThemeCapable(rt)) rt._onMarksChanged = () => updateSubTheme(rt);
+        if (!legendOn || !el.parentElement || !legendApplies(rt)) return;
+        el.parentElement.style.position = el.parentElement.style.position || 'relative';
+        {
+        // .type("...|NOLEGEND") — the fourth real legend-related type()
+        // token: opts a theme OUT of the legend entirely (real engine's
+        // own per-layer "skip this one" flag, distinct from the map-
+        // level legend:"open"/"closed" option gating the whole panel).
+        // Same free-parsing story as SIMPLELEGEND/COMPACTLEGEND above —
+        // just one more flag to exclude on, no new plumbing.
+          const panel = document.createElement('div');
+          rt._legendPanel = panel;
+          panel.className = 'ix-native-legend';
+          // Opt-in via .style({legendtheme:"light"}) — a NEW, ixmaps-gl-
+          // only convention (same naming pattern as the sibling
+          // legendfilter/legendunits keys added earlier this session):
+          // real ixmaps-flat's legend.js has no such switch, this panel
+          // is entirely this port's own construction. Default ("dark")
+          // preserves the original always-dark panel exactly; "light" is
+          // for pages using a light basemap (e.g. CARTO Positron) where
+          // a dark semi-transparent panel reads as a mismatched dark
+          // patch rather than legend chrome. Every other hardcoded panel
+          // color below (rows, bar track, filter <select>) is expressed
+          // in terms of this one palette so the two variants stay in
+          // sync — no separate light/dark branch anywhere else.
+          // flat's look (flatLegendLook) unless the page picks one with
+          // this engine's own legendtheme
+          const opacityOpt = parseFloat(builder._engineOptions.basemapopacity);
+          const flatLook = flatLegendLook(builder.mapOptions.mapType, isNaN(opacityOpt) ? 1 : opacityOpt, builder.mapOptions.legendBackground || builder.mapOptions.legendbackground);
+          const isLightLegend = rt.style.legendtheme === 'light' || (rt.style.legendtheme !== 'dark' && !flatLook.dark);
+          const legendColors = isLightLegend
+            ? { bg: 'rgba(255,255,255,0.92)', fg: '#1a1a1a', shadow: '0 2px 10px rgba(0,0,0,0.18)',
+                rowMarked: 'rgba(0,0,0,0.08)', track: 'rgba(0,0,0,0.08)',
+                selectBg: 'rgba(0,0,0,0.04)', selectBorder: 'rgba(0,0,0,0.2)' }
+            : { bg: 'rgba(28,30,34,0.92)', fg: '#eee', shadow: '0 2px 10px rgba(0,0,0,0.45)',
+                rowMarked: 'rgba(255,255,255,0.14)', track: 'rgba(255,255,255,0.08)',
+                selectBg: 'rgba(255,255,255,0.08)', selectBorder: 'rgba(255,255,255,0.25)' };
+          if (!rt.style.legendtheme) legendColors.bg = flatLook.bg;
+          // max-height:66% resolves against el.parentElement's own
+          // height (the map container, which always has a definite
+          // height for the map itself to render into) since this panel
+          // is absolutely positioned inside it — a plain percentage on
+          // an absolutely-positioned element's height IS legal CSS as
+          // long as its containing block has a definite height, which
+          // this one does. display:flex column + min-height:0 on the
+          // ROWS wrapper below (not this outer panel) is what makes
+          // only the row list scroll while the header/description/
+          // slider stay fixed in place — a flex child won't actually
+          // shrink to fit and scroll internally without min-height:0,
+          // it just overflows its flex parent instead.
+          // one box for every theme, as flat's #map-legend (legend.js
+          // 2200-2460): the panels stack in the legend stack in theme
+          // order, a line between them (see layoutLegends)
+          panel.style.cssText = 'position:relative;flex:0 0 auto;'
+            + 'display:flex;flex-direction:column;'
+            + 'background:' + legendColors.bg + ';color:' + legendColors.fg + ';font:12px/1.4 -apple-system,Arial,sans-serif;'
+            + 'padding:10px 12px 12px;pointer-events:auto;';
+          const stack = legendStackEl(legendColors.shadow);
+          const at = runtimes.indexOf(rt);
+          const next = [...stack.children].find(c => runtimes.indexOf(c._ixRuntime) > at);
+          panel._ixRuntime = rt;
+          stack.insertBefore(panel, next || null);
+
+          // SUM+valuefield mirrors the real engine's own "SUM style
+          // aggregation" reading (style.valuefield, falling back to
+          // the bound size field); anything else (plain CATEGORICAL,
+          // no SUM) falls back to a per-category record COUNT.
+          const useSum = flatFlag(rt.flags, 'SUM') && rt.style.valuefield;
+          const valueField = rt.style.valuefield || rt.binding.size;
+          // legendunits wins over the theme's general-purpose units
+          // (used elsewhere for tooltips, e.g. _renderItemChartHtml) —
+          // a page may want a different/no unit string specifically on
+          // the legend's own value column. Appended as-is (no extra
+          // space injected), matching how style.units/legendunits are
+          // themselves authored with their own leading space (e.g.
+          // " MW") in real pages.
+          const legendUnit = rt.style.legendunits || rt.style.units || '';
+          // row labels go into innerHTML: the page's own .style({label})
+          // stays HTML, as in flat; categories read from the data are
+          // escaped (a value could carry markup)
+          const labels = legendRowLabels(rt);
+          // .type("...|TEXTLEGEND") — the FIFTH real legend-related
+          // type() token: title/snippet/description text only, no
+          // category rows at all (swatches, bars, chips — none of it),
+          // per explicit correction. Everything below that builds the
+          // rows/totals/onRedraw-recompute wiring is skipped outright
+          // rather than built-then-hidden — there is nothing for any of
+          // it to feed once no rows ever render. The country-filter
+          // dropdown and Chart-size slider stay: neither is a
+          // "categorical item" or "colorscheme swatch", both are
+          // independent controls unrelated to the row list.
+          const isTextOnly = rt.flags.has('TEXTLEGEND');
+
+          // Map-view-aware per explicit request: totals reflect only
+          // what's CURRENTLY on screen (the map's own bounds, plus the
+          // same far-hemisphere exclusion _buildChartLayers itself
+          // applies under globe projection — see isOnVisibleHemisphere)
+          // rather than the whole dataset — recomputed on every redraw
+          // (engineApi.onRedraw, below) so panning/zooming/rotating
+          // updates the bars and values live, the same way the actual
+          // rendered bubbles change. Same simple rectangular bbox
+          // membership test _computeAggregatedItems's own non-AGGREGATE
+          // branch uses (no antimeridian wraparound handling — matches
+          // that existing convention, not a new gap this introduces).
+          let totals, maxTotal, order, rowsScroll;
+          // No-op default: TEXTLEGEND never reassigns this (see below),
+          // so the LATER unconditional-looking `renderRows()` call
+          // safely does nothing rather than needing its own isTextOnly
+          // guard at every call site.
+          let renderRows = () => {};
+          if (!isTextOnly) {
+          function computeTotals() {
+            const bounds = map.getBounds();
+            const bbox = [bounds.getWest(), bounds.getSouth(), bounds.getEast(), bounds.getNorth()];
+            const proj = (typeof map.getProjection === 'function' && map.getProjection()) || { type: 'mercator' };
+            const globeCenter = proj.type === 'globe' ? map.getCenter() : null;
+            totals = new Array(rt.categoryLabels.length).fill(0);
+            if (rt._rangeClassed) { totals = rangeClassLegendTotals(rt, bbox, globeCenter); maxTotal = Math.max(0, ...totals); order = totals.map((v, i) => i).sort((a, b) => totals[b] - totals[a]); return; }
+            // _activeFeatures (set by setFacetFilter/clearFacetFilter,
+            // e.g. the country-select dropdown below) is the facet-
+            // filtered subset when a filter is active, null otherwise —
+            // reading it here keeps the legend's own numbers consistent
+            // with whatever the country filter is currently narrowing
+            // the map down to, not just with the viewport/hemisphere.
+            (rt._activeFeatures || rt.features).forEach(f => {
+              const idx = rt.categoryIndexByLabel ? rt.categoryIndexByLabel.get(f.properties[rt.binding.value]) : null;
+              if (idx == null) return;
+              const [lng, lat] = f.geometry.coordinates;
+              if (lng < bbox[0] || lng > bbox[2] || lat < bbox[1] || lat > bbox[3]) return;
+              if (globeCenter && !isOnVisibleHemisphere(lng, lat, globeCenter)) return;
+              totals[idx] += useSum ? (parseFloat(f.properties[valueField]) || 0) : 1;
+            });
+            maxTotal = Math.max(0, ...totals);
+            order = totals.map((v, i) => i).sort((a, b) => totals[b] - totals[a]);
+          }
+          computeTotals();
+
+          // Only THIS wrapper scrolls (flex:1 1 auto + min-height:0 lets
+          // it shrink to whatever's left of the panel's own 66%-height
+          // cap once the fixed header/description/slider take their
+          // share, then overflow-y:auto scrolls just the row list) —
+          // the header above and description/slider below stay put.
+          rowsScroll = document.createElement('div');
+          rowsScroll.style.cssText = 'flex:1 1 auto;min-height:0;overflow-y:auto;';
+          const rowsEl = document.createElement('div');
+          rowsEl.className = 'ix-legend-rows';
+          // .type("...|SIMPLELEGEND") — real ixmaps-flat's OTHER legend
+          // variant (confirmed against a real-engine screenshot, per
+          // explicit correction): swatch + label chips only, no bar, no
+          // value column. SIMPLELEGEND is just another pipe-delimited
+          // type() token — MapBuilder#type() already puts every token
+          // into this.flags regardless of whether anything reads it, so
+          // no new parsing was needed, only this render-mode branch.
+          // flex-wrap here (vs. the bar mode's block rows) — chips wrap
+          // to the panel's own width the same loose way the real
+          // engine's screenshot shows (an uneven number of chips per
+          // row, driven by each label's own text length, not a fixed
+          // column grid).
+          // .type("...|COMPACTLEGEND") — the THIRD real legend variant
+          // (again confirmed against a real-engine screenshot, per
+          // explicit correction): the bar-mode's own two-line label/bar/
+          // value row, but wrapped into a multi-column flex-wrap grid
+          // instead of one full-width row per category — each item's
+          // own width follows its content (a bigger value's longer bar
+          // makes its own item wider, so fewer fit per line; Coal alone
+          // filled its own row in the reference screenshot while the
+          // smaller categories packed 3-4 per row) rather than a fixed
+          // column count.
+          if (rt.flags.has('SIMPLELEGEND') || rt.flags.has('COMPACTLEGEND')) {
+            rowsEl.style.cssText = 'display:flex;flex-wrap:wrap;gap:4px;';
+          }
+          rowsScroll.appendChild(rowsEl);
+
+          // Two lines per row — label on its own full-width line, then
+          // swatch+bar+value below — per explicit correction: a single
+          // shared line left too little room for the bar to read as
+          // proportional (it was squeezed between the label text and a
+          // fixed-width value column). The bar itself lives inside a
+          // flex:1 "track" div sized to whatever's left after the fixed
+          // swatch/value columns, and is a PERCENTAGE of that track's
+          // own width (not a pixel value) — real formula's per-unit-
+          // factor/cap (legend.js:980-984/946-950) collapses to a plain
+          // linear percentage-of-max once the bar's available width
+          // isn't a fixed constant this code has to guess at.
+          const isSimple = rt.flags.has('SIMPLELEGEND');
+          const isCompact = rt.flags.has('COMPACTLEGEND');
+          // Compact mode's bar can't use the full-width mode's
+          // percentage-of-flex-track trick (there's no full-width track
+          // to be a percentage OF once the row itself is content-sized,
+          // not stretched) — a plain pixel width, proportional to value
+          // and capped, same shape as the full-width formula just
+          // expressed in absolute px instead of a % of an elastic track.
+          const COMPACT_MAX_BAR_PX = 70;
+          // flat's compact legend (legend.js makeColorLegendHTML, the
+          // "compact" mode the theme legends use, 1212-1257): a range
+          // theme of 5 classes or more without labels is one line of
+          // color patches with the value range below; DOPACITY with an
+          // alpha field adds two paler lines (opacity 1/2, 1/3) and the
+          // alpha max, "↓" and min to their right (1062-1205). The
+          // legend's own __formatValue (legend.js 451-553) has no SPACE
+          // form: SPACE there is flat's plain "." thousands.
+          const flatCompactLegend = rt._rangeClassed && !flatFlag(rt.flags, 'CATEGORICAL') && !flatFlag(rt.flags, 'PLOT')
+            && (rt.partsA || []).length >= 5 && !(Array.isArray(rt.style.label) && rt.style.label.length);
+          // flat's single-color legend (legend.js 765-769, 1039-1046): a range
+          // theme of at most 2 classes without label/ranges, not
+          // CATEGORICAL, is one row — the swatch and "min ... max unit",
+          // or, when every value is 1 (a "$item$" count), its label or
+          // value field
+          const flatSingleRowLegend = rt._rangeClassed && !flatFlag(rt.flags, 'CATEGORICAL') && !flatFlag(rt.flags, 'PLOT')
+            && (rt.partsA || []).length <= 2 && !(Array.isArray(rt.style.label) && rt.style.label.length)
+            && !(Array.isArray(rt.style.ranges) && rt.style.ranges.length);
+          if (flatSingleRowLegend) {
+            renderRows = function() {
+              const rgb = rt.categoryColorsRgb[0] || [128, 128, 128];
+              const unit = String(rt.style.legendunits || rt.style.units || '').replace(/ /g, '&nbsp;');
+              const vMin = styleNum(rt.style.minvalue) || rt._valueMin, vMax = styleNum(rt.style.maxvalue) || rt._valueMax;
+              const label = rt.style.label != null && !Array.isArray(rt.style.label) ? String(rt.style.label) : String(rt.binding.value || '');
+              const text = vMin !== 1 || vMax !== 1
+                ? flatFormatValue(vMin, 2, 'BLANK') + ' &nbsp;... ' + flatFormatValue(vMax, 2, 'BLANK') + ' ' + unit
+                : label;
+              const marked = rt._markedClasses.has(0);
+              rowsEl.innerHTML = '<div class="ix-legend-row" data-idx="0" style="display:flex;align-items:center;gap:5px;padding:4px 3px;cursor:pointer;border-radius:4px;'
+                + 'background:' + (marked ? legendColors.rowMarked : 'transparent') + ';">'
+                + '<span style="flex:0 0 auto;width:1.6em;height:0.8em;background:rgb(' + rgb[0] + ',' + rgb[1] + ',' + rgb[2] + ');"></span>'
+                + '<span>' + text + '</span></div>';
+              rowsEl.querySelectorAll('.ix-legend-row').forEach(row => {
+                row.addEventListener('click', () => {
+                  if (rt._markedClasses.has(0)) unmarkRuntimeClass(rt, 0);
+                  else markRuntimeClass(rt, 0);
+                });
+              });
+            };
+          } else
+          if (flatCompactLegend) {
+            renderRows = function() {
+              const n = rt.categoryColorsRgb.length;
+              const withAlpha = flatFlag(rt.flags, 'DOPACITY') && rt.binding.alpha && rt._alphaMax;
+              const nLines = withAlpha ? 3 : 1;
+              const dec = rt.style.decimals != null ? parseInt(rt.style.decimals, 10) : 2;
+              const unit = rt.style.legendunits || rt.style.units || '';
+              const ranges = Array.isArray(rt.style.ranges) && rt.style.ranges.length ? rt.style.ranges.map(Number) : null;
+              const vMin = ranges ? ranges[0] : rt._valueMin, vMax = ranges ? ranges[ranges.length - 1] : rt._valueMax;
+              let html = '<div style="display:grid;grid-template-columns:repeat(' + n + ',1fr)' + (withAlpha ? ' auto' : '') + ';gap:1px;align-items:center;">';
+              for (let line = 0; line < nLines; line++) {
+                for (let c = 0; c < n; c++) {
+                  const ix = flatFlag(rt.flags, 'INVERT') ? n - c - 1 : c;
+                  const rgb = rt.categoryColorsRgb[ix];
+                  const part = rt.partsA[ix];
+                  const title = part ? flatFormatValue(part.min, dec, '') + unit + ' ... ' + flatFormatValue(part.max, dec, '') + unit : '';
+                  const marked = rt._markedClasses.has(ix);
+                  html += '<span class="ix-legend-row" data-idx="' + ix + '" title="' + title + '" style="cursor:pointer;height:14px;'
+                    + 'background:rgb(' + rgb[0] + ',' + rgb[1] + ',' + rgb[2] + ');opacity:' + (1 / (line + 1)) + ';'
+                    + (marked ? 'outline:2px solid ' + legendColors.fg + ';outline-offset:-2px;' : '') + '"></span>';
+                }
+                if (withAlpha) {
+                  const txt = line === 0 ? flatFormatValue(rt._alphaMax, 0, 'BLANK')
+                    : line === 1 ? '&#8595; ' + (rt.style.alphavalueunits || '') : flatFormatValue(rt._alphaMin || 0, 0, 'BLANK');
+                  html += '<span style="padding-left:0.5em;white-space:nowrap;">' + txt + '</span>';
+                }
+              }
+              html += '</div><div style="display:flex;justify-content:space-between;margin-top:3px;' + (withAlpha ? 'margin-right:4em;' : '') + '">'
+                + '<span>' + flatFormatValue(vMin, dec, '') + (unit ? ' ' + unit : '') + '</span>'
+                + '<span>' + flatFormatValue(vMax, dec, '') + (unit && unit.length <= 3 ? ' ' + unit : '') + '</span></div>';
+              rowsEl.innerHTML = html;
+              rowsEl.querySelectorAll('.ix-legend-row').forEach(cell => {
+                cell.addEventListener('click', () => {
+                  const idx = parseInt(cell.dataset.idx, 10);
+                  if (rt._markedClasses.has(idx)) unmarkRuntimeClass(rt, idx);
+                  else markRuntimeClass(rt, idx);
+                });
+              });
+            };
+          } else
+          renderRows = function() {
+            // flat drops the rows without a count once any row has one
+            // (legend.js 754-760, 787-789: fCountBars && !count)
+            rowsEl.innerHTML = order.filter(i => !(maxTotal > 0) || totals[i]).map(i => {
+              const rgb = rt.categoryColorsRgb[i];
+              const color = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`;
+              const marked = rt._markedClasses.has(i);
+              const dimmed = rt._markedClasses.size > 0 && !marked;
+              const rowStyle = 'padding:4px 3px;border-radius:4px;cursor:pointer;opacity:' + (dimmed ? 0.4 : 1) + ';'
+                + 'background:' + (marked ? legendColors.rowMarked : 'transparent') + ';';
+              if (isSimple) {
+                // Swatch + label only, no bar/value — see rowsEl's own
+                // comment above for why (SIMPLELEGEND).
+                return '<div class="ix-legend-row" data-idx="' + i + '" style="' + rowStyle
+                  + 'display:inline-flex;align-items:center;gap:5px;padding:4px 8px;">'
+                  + '<span style="flex:0 0 8px;width:8px;height:8px;border-radius:50%;background:' + color + ';"></span>'
+                  + '<span>' + labels[i] + '</span>'
+                  + '</div>';
+              }
+              const pct = maxTotal ? Math.max(0, Math.min(100, (totals[i] / maxTotal) * 100)) : 0;
+              if (isCompact) {
+                // Same two-line label/bar/value shape as full-width bar
+                // mode below, just content-sized (flex:0 0 auto, no
+                // min-width:0 flex-1 track) so multiple items pack onto
+                // one line inside rowsEl's own flex-wrap — see
+                // COMPACTLEGEND's own comment on rowsEl above.
+                const barPx = Math.max(2, (pct / 100) * COMPACT_MAX_BAR_PX);
+                return '<div class="ix-legend-row" data-idx="' + i + '" style="' + rowStyle + 'flex:0 0 auto;">'
+                  + '<div style="margin-bottom:3px;white-space:nowrap;">' + labels[i] + '</div>'
+                  + '<div style="display:flex;align-items:center;gap:6px;">'
+                  + '<span style="flex:0 0 8px;width:8px;height:8px;border-radius:50%;background:' + color + ';"></span>'
+                  + '<span style="flex:0 0 auto;width:' + barPx + 'px;height:6px;background:' + color + ';border-radius:3px;"></span>'
+                  + '<span style="flex:0 0 auto;white-space:nowrap;">' + rt._formatTooltipValue(totals[i]) + legendUnit + '</span>'
+                  + '</div>'
+                  + '</div>';
+              }
+              return '<div class="ix-legend-row" data-idx="' + i + '" style="' + rowStyle + '">'
+                + '<div style="margin-bottom:3px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">' + labels[i] + '</div>'
+                + '<div style="display:flex;align-items:center;gap:6px;">'
+                + '<span style="flex:0 0 8px;width:8px;height:8px;border-radius:50%;background:' + color + ';"></span>'
+                + '<span style="flex:1 1 auto;min-width:0;height:6px;background:' + legendColors.track + ';border-radius:3px;overflow:hidden;">'
+                + '<span style="display:block;height:100%;width:' + pct + '%;background:' + color + ';border-radius:3px;"></span>'
+                + '</span>'
+                + '<span style="flex:0 0 auto;text-align:right;min-width:60px;">' + rt._formatTooltipValue(totals[i]) + legendUnit + '</span>'
+                + '</div>'
+                + '</div>';
+            }).join('');
+            // GL-PORT COMPAT: real ixmaps-flat's row markup wires its
+            // click handler inline (onclick="ixmaps.markThemeClass(...)"
+            // — legend.js:817), toggle decided by the caller. Same
+            // split here: the toggle check lives in this click
+            // handler, the actual add/remove-and-redraw primitive is
+            // markRuntimeClass/unmarkRuntimeClass, which the globals
+            // ixmaps.markThemeClass/unmarkThemeClass also use — so a
+            // page's OWN custom UI drives this exact legend too. The
+            // rows pass their runtime itself: its .layer() name may be
+            // shared with other themes of the page.
+            rowsEl.querySelectorAll('.ix-legend-row').forEach(rowEl => {
+              rowEl.addEventListener('click', () => {
+                const idx = parseInt(rowEl.dataset.idx, 10);
+                if (rt._markedClasses.has(idx)) unmarkRuntimeClass(rt, idx);
+                else markRuntimeClass(rt, idx);
+              });
+            });
+          };
+
+          // Recompute+re-render on EVERY redraw, not just mark toggles —
+          // this is what makes the legend map-view-aware: a plain pan/
+          // zoom/rotate fires this too (via the map's own 'move'
+          // listener -> scheduleRefresh -> notifyRedraw, debounced the
+          // same 400ms as the facets sidebar's own onRedraw use), same
+          // signal already used elsewhere in this file for "the visible
+          // data just changed, recompute".
+          engineApi.onRedraw(() => { computeTotals(); renderRows(); });
+          }
+
+          // rt._triggerRedraw: see its own doc comment on LayerRuntime
+          // (set here rather than at construction time since refresh()
+          // doesn't exist yet when the runtime is built). Kept
+          // unconditional (even for TEXTLEGEND, which never registers
+          // the onRedraw recompute above) — a page can still call
+          // ixmaps.markThemeClass/unmarkThemeClass directly with no
+          // visual row list to click, and that should still redraw the
+          // MAP's own dim/isolate effect even without a legend UI for
+          // it, matching real-engine global-API availability regardless
+          // of legend style.
+          rt._triggerRedraw = () => { refresh(); };
+
+          // Header row (title/snippet + collapse toggle) always stays
+          // visible; everything else lives in `bodyEl`, hidden/shown as
+          // a single unit by the toggle below — collapsing shows just
+          // the title bar, matching the real engine's own fold/unfold
+          // behavior (ixmaps.legendState + the "legend-folded" CSS
+          // class, ui/js/tools/legend.js) even though this port toggles
+          // via a plain display swap on one wrapper div rather than a
+          // shared stylesheet class (this panel has no external CSS at
+          // all — everything here is inline-styled, unlike the real
+          // engine's DOM/CSS-class-driven legend).
+          const header = document.createElement('div');
+          header.style.cssText = 'display:flex;align-items:flex-start;justify-content:space-between;gap:6px;';
+          const headerText = document.createElement('div');
+          headerText.style.cssText = 'min-width:0;flex:1 1 auto;';
+          let headerHtml = '';
+          if (rt.meta.title) headerHtml += '<div style="font-weight:600;font-size:13px;margin-bottom:2px;">' + rt.meta.title + '</div>';
+          if (rt.meta.snippet) headerHtml += '<div style="opacity:0.75;">' + rt.meta.snippet + '</div>';
+          headerText.innerHTML = headerHtml;
+          header.appendChild(headerText);
+          const collapseBtn = document.createElement('button');
+          collapseBtn.type = 'button';
+          collapseBtn.style.cssText = 'flex:0 0 auto;background:transparent;border:none;color:inherit;'
+            + 'font-size:14px;line-height:1;cursor:pointer;padding:2px 4px;opacity:0.7;';
+          header.appendChild(collapseBtn);
+          panel.appendChild(header);
+
+          const bodyEl = document.createElement('div');
+          bodyEl.style.cssText = 'display:flex;flex-direction:column;min-height:0;flex:1 1 auto;margin-top:8px;';
+          panel.appendChild(bodyEl);
+
+          // Collapsed by default under the real engine's own narrow-
+          // screen legend threshold (ui/js/tools/legend.js: `if
+          // (window.innerWidth < 500) ixmaps.legend.hide()`) — reusing
+          // that concrete precedent rather than picking an arbitrary
+          // "mobile" breakpoint of this port's own invention. Checked
+          // once at panel-build time, not on resize — matching the real
+          // engine's own one-shot-at-redraw-time check, not a live
+          // matchMedia listener.
+          const MOBILE_LEGEND_BREAKPOINT = 500;
+          let collapsed = legendFolded || window.innerWidth < MOBILE_LEGEND_BREAKPOINT;
+          function applyCollapsed() {
+            bodyEl.style.display = collapsed ? 'none' : 'flex';
+            collapseBtn.textContent = collapsed ? '▸' : '▾';
+            collapseBtn.title = collapsed ? 'Expand legend' : 'Collapse legend';
+          }
+          collapseBtn.addEventListener('click', () => { collapsed = !collapsed; applyCollapsed(); });
+          applyCollapsed();
+          rt._setLegendCollapsed = c => { collapsed = !!c; applyCollapsed(); }; // setLegendOption
+
+          // Selection/filter by field — opt-in via .style({legendfilter:
+          // "<field>"}), e.g. "country_long" on the power-plants sample.
+          // A NEW, ixmaps-gl-only convention: real ixmaps-flat's own
+          // style.filterfield names the DEFAULT field an unqualified
+          // .filter("text") search term matches against (maptheme.js:
+          // 1275-1276/7359-7362) — a different concept entirely, so this
+          // deliberately uses its own name rather than overloading that
+          // one. Options come from the FULL dataset (a world-spanning
+          // bbox, not the current viewport) and stay fixed regardless of
+          // pan/zoom — unlike the map-view-aware category totals below,
+          // a picker whose own choices kept shrinking as you panned
+          // would make it impossible to select a country not currently
+          // in view. Selecting a value reuses the engine's own existing
+          // facet-filter primitive (engineApi.setFacetFilter/
+          // clearFacetFilter — already propagates to sibling runtimes
+          // sharing the same data source and calls refresh()), so this
+          // is UI wiring only, no new filtering logic.
+          const filterField = rt.style.legendfilter;
+          if (filterField) {
+            const facet = engineApi.getFacets(rt.name, [filterField], { bbox: [-180, -85, 180, 85] })[0];
+            const values = (facet && facet.type === 'textual')
+              ? facet.values.slice().sort((a, b) => String(a).localeCompare(String(b)))
+              : [];
+            const filterEl = document.createElement('select');
+            filterEl.style.cssText = 'width:100%;margin-bottom:8px;background:' + legendColors.selectBg + ';'
+              + 'color:' + legendColors.fg + ';border:1px solid ' + legendColors.selectBorder + ';border-radius:4px;padding:4px 6px;font:inherit;';
+            filterEl.innerHTML = '<option value="">All (' + values.length + ')</option>'
+              + values.map(v => '<option value="' + escapeHtml(v) + '">' + escapeHtml(v) + '</option>').join('');
+            filterEl.addEventListener('change', () => {
+              if (filterEl.value) engineApi.setFacetFilter(rt.name, filterField, filterEl.value);
+              else engineApi.clearFacetFilter(rt.name, filterField);
+            });
+            bodyEl.appendChild(filterEl);
+          }
+
+          if (!isTextOnly) { bodyEl.appendChild(rowsScroll); renderRows(); }
+
+          if (rt.meta.description) {
+            const desc = document.createElement('div');
+            desc.style.cssText = 'margin-top:8px;font-size:11px;opacity:0.8;';
+            // Raw HTML, matching the real engine's own description
+            // rendering and this engine's existing .legend(html)/
+            // tooltip conventions (e.g. _buildTooltipContext) — real
+            // pages already embed their own source-citation markup
+            // inside meta.description (see the power-plants sample).
+            desc.innerHTML = rt.meta.description;
+            bodyEl.appendChild(desc);
+          }
+
+          // Chart-size slider — real engine's own range (legend.js:
+          // 3196-3202), 100% == scale:1, wired to changeThemeStyle(
+          // themeId,"scale:"+pct/100,"set")+redrawTheme there; this
+          // engine's equivalent is rt.setStyle({scale}) + refresh(),
+          // the same primitive engineApi.setThemeStyle uses above.
+          // CHOROPLETH themes get an OPACITY slider instead, as in flat
+          // (legend.js ~3190: 0-100%, fillopacity·100, default 90;
+          // changeThemeStyle("fillopacity:"+pct/100,"set") + redraw).
+          // (flat labels a VECTOR theme's size slider "Line width" — gl has
+          // no VECTOR themes.)
+          // Flat tests the words (legend.js 2533-2535): a "CHOROPLETHE"
+          // theme has neither slider.
+          const typeWords = rt.flags.typeString != null ? rt.flags.typeString : [...rt.flags].join('|');
+          const isOpacitySlider = /\bCHOROPLETH\b/.test(typeWords);
+          const hasSlider = isOpacitySlider || /\bCHART\b|\bBUBBLE\b|\bDOT\b/.test(typeWords);
+          if (hasSlider) {
+          const sliderRow = document.createElement('div');
+          sliderRow.style.cssText = 'margin-top:10px;font-size:11px;opacity:0.8;';
+          const fillPct = Math.round(styleNum(rt.style.fillopacity) * 100);
+          const initialPct = isOpacitySlider
+            ? (Number.isFinite(fillPct) ? Math.max(0, Math.min(100, fillPct)) : 90)
+            : Math.round((styleNum(rt.style.scale) || 1) * 100);
+          const sliderLabel = isOpacitySlider ? 'Opacity' : 'Chart size';
+          sliderRow.innerHTML = sliderLabel + ': <span class="ix-legend-scale-val">' + initialPct + '</span>%';
+          bodyEl.appendChild(sliderRow);
+          const slider = document.createElement('input');
+          slider.type = 'range';
+          slider.min = isOpacitySlider ? '0' : '25';
+          slider.max = isOpacitySlider ? '100' : '200';
+          slider.value = String(initialPct);
+          slider.style.cssText = 'width:100%;margin-top:2px;';
+          slider.addEventListener('input', () => {
+            const pct = parseInt(slider.value, 10);
+            sliderRow.querySelector('.ix-legend-scale-val').textContent = pct;
+            rt.setStyle(isOpacitySlider ? { fillopacity: pct / 100 } : { scale: pct / 100 });
+            refresh();
+          });
+          bodyEl.appendChild(slider);
+          }
+        }
+      };
+      runtimes.forEach(rt => addLegendPanel(rt));
+    }
+    return { addLegendPanel, setLegendOption, updateSubTheme, layoutLegends };
+  }
+
   class MapBuilder {
     constructor(containerId, options) {
       this.containerId = containerId;
@@ -2923,6 +3764,9 @@
         // theme addressed only by its meta.name, same bug different
         // resolution path.
         if (rt.meta && rt.meta.name && rt.meta.name !== rt.name) _globalThemeRegistry.set(rt.meta.name, rt);
+        // flat's theme id is style.name (maptheme szId) — several themes
+        // can share one .layer() name (a page's features + charts + texts)
+        if (themeIdOf(rt) !== rt.name) _globalThemeRegistry.set(themeIdOf(rt), rt);
         if (named) namedLoads.push(rt);
        } catch (err) {
         console.error(`[ixmaps-gl] theme "${lb.name}" skipped:`, err);
@@ -3052,112 +3896,8 @@
         });
       }
 
-      // Click-to-pin tooltip: matches the real ixmaps engine's own
-      // click-pins-the-tooltip convention in pan mode (a hover tooltip is
-      // transient; a click keeps one visible until dismissed). This is a
-      // separate DOM element from deck.gl's own hover tooltip (so hovering
-      // a DIFFERENT bubble still shows a normal transient tooltip even
-      // while one is pinned) — its content is a snapshot of buildTooltipHtml
-      // at click time (not live-updating), but its screen POSITION is kept
-      // in sync with the map on every pan/zoom via map.project().
-      let pinned = null; // { runtime, object, lngLat }
-      // Tooltip look, like the legend's (flatLegendLook): flat's light
-      // tooltip (tooltip_mustache.js: white 0.95, #444 text, thin black
-      // border, 5px radius) on light basemaps, this engine's dark tooltip
-      // on dark ones. Read when shown, so options set later (a
-      // myMap.then(...).options({basemapopacity})) count.
-      const tooltipLook = () => {
-        const o = parseFloat(this._engineOptions.basemapopacity);
-        const look = flatLegendLook(this.mapOptions.mapType, isNaN(o) ? 1 : o, this.mapOptions.legendBackground || this.mapOptions.legendbackground);
-        return look.dark
-          ? { background: 'rgb(41,50,60)', color: 'rgb(200,205,214)', border: 'none', borderRadius: '4px', boxShadow: '0 2px 8px rgba(0,0,0,0.3)' }
-          : { background: 'rgba(255,255,255,0.95)', color: '#444', border: '0.5px solid black', borderRadius: '5px',
-              boxShadow: 'rgba(0,0,0,0.2) 0px 2px 4px 0px, rgba(0,0,0,0.19) 0px 3px 10px 0px' };
-      };
-      const pinnedTooltipEl = document.createElement('div');
-      pinnedTooltipEl.style.cssText = 'position:absolute;top:0;left:0;z-index:6;display:none;' +
-        'pointer-events:auto;max-width:320px;max-height:320px;overflow:auto;' +
-        'padding:0.6em 1.6em 0.6em 0.7em;font-size:0.85em;';
-
-      function updatePinnedTooltipPosition() {
-        if (!pinned) return;
-        const pt = map.project(pinned.lngLat);
-        pinnedTooltipEl.style.transform = `translate(${pt.x + 10}px, ${pt.y - 10}px)`;
-      }
-
-      // A stable per-geometry anchor coordinate for the identity check
-      // below — only a Point's OWN coordinates are an [lng,lat] pair;
-      // Polygon/MultiPolygon nest rings of them, so the first ring's
-      // first vertex stands in instead (stable across rebuilds for the
-      // same underlying feature, same as the Point case: this.features'
-      // geometry references don't change shape between
-      // _buildChoroplethLayers calls, only the wrapping properties do).
-      function anchorCoordOf(geometry) {
-        if (!geometry) return null;
-        if (geometry.type === 'Point') return geometry.coordinates;
-        if (geometry.type === 'Polygon') return geometry.coordinates[0] && geometry.coordinates[0][0];
-        if (geometry.type === 'MultiPolygon') return geometry.coordinates[0] && geometry.coordinates[0][0] && geometry.coordinates[0][0][0];
-        return null;
-      }
-
-      // Identity check for "is this hovered object the same one that's
-      // pinned" — object references are rebuilt from scratch on every
-      // redraw (new individual/group arrays each buildDeckLayers call), so
-      // reference equality never works here. Same layer + same geometry
-      // position is a reasonable proxy: individual points and aggregated
-      // groups alike are keyed by position within a layer, matching how
-      // clustering itself already treats "same position" as "same thing".
-      function isSameAsPinned(layerId, object) {
-        if (pinned.layerId !== layerId) return false;
-        const a = anchorCoordOf(object.geometry);
-        const b = anchorCoordOf(pinned.object.geometry);
-        if (!a || !b) return false;
-        return Math.abs(a[0] - b[0]) < 1e-9 && Math.abs(a[1] - b[1]) < 1e-9;
-      }
-
-      // content lives in its own child so re-rendering (innerHTML) never
-      // wipes out the unpin button below (a sibling, not a descendant of it)
-      const pinnedContentEl = document.createElement('div');
-      pinnedTooltipEl.appendChild(pinnedContentEl);
-
-      function renderPinnedTooltip() {
-        if (!pinned) { pinnedTooltipEl.style.display = 'none'; return; }
-        const html = pinned.runtime.buildTooltipHtml(pinned.object);
-        if (!html) { pinned = null; pinnedTooltipEl.style.display = 'none'; return; }
-        pinnedContentEl.innerHTML = html;
-        Object.assign(pinnedTooltipEl.style, tooltipLook());
-        pinnedTooltipEl.style.display = 'block';
-        updatePinnedTooltipPosition();
-      }
-
-      const unpinBtn = document.createElement('button');
-      unpinBtn.type = 'button';
-      unpinBtn.setAttribute('aria-label', 'chiudi');
-      unpinBtn.title = 'chiudi';
-      unpinBtn.textContent = '×';
-      unpinBtn.style.cssText = 'position:absolute;top:5px;right:5px;width:1.5em;height:1.5em;padding:0;' +
-        'display:flex;align-items:center;justify-content:center;border:none;border-radius:50%;' +
-        'background:rgba(255,255,255,0.18);color:inherit;font-size:1em;line-height:1;font-weight:bold;cursor:pointer';
-      unpinBtn.addEventListener('mouseenter', () => { unpinBtn.style.background = 'rgba(255,255,255,0.35)'; });
-      unpinBtn.addEventListener('mouseleave', () => { unpinBtn.style.background = 'rgba(255,255,255,0.18)'; });
-      unpinBtn.addEventListener('click', () => { pinned = null; pinnedTooltipEl.style.display = 'none'; });
-      pinnedTooltipEl.style.position = 'absolute';
-      pinnedTooltipEl.appendChild(unpinBtn);
-
-      // deck.gl's own default hover tooltip is only recomputed on pointer-
-      // move events, not on click — so right after a click, it's still
-      // showing whatever it rendered from the hover that was already
-      // active (the same item we just pinned), and won't hide itself just
-      // because getTooltip would now return null for it. Nothing re-asks
-      // it until the next real mousemove. Force it closed here instead —
-      // deferred one frame so it wins even if deck.gl's own click handling
-      // touches the tooltip DOM in the same tick.
-      function hideDefaultHoverTooltip() {
-        requestAnimationFrame(() => {
-          const defaultTooltipEl = el.parentElement && el.parentElement.querySelector('.deck-tooltip');
-          if (defaultTooltipEl) defaultTooltipEl.style.display = 'none';
-        });
-      }
+      // hover / click-to-pin tooltips: createTooltips
+      const tooltips = createTooltips({ builder: this, map, el, findRuntimeForLayerId });
 
       const overlay = new MapLibreOverlay({
         interleaved: true,
@@ -3165,88 +3905,13 @@
         // pointer becomes a hand over anything pickable (bubbles/points),
         // so hovering something clickable actually looks clickable
         getCursor: ({ isDragging, isHovering }) => (isDragging ? 'grabbing' : (isHovering ? 'pointer' : 'grab')),
-        // An exception thrown from these callbacks runs inside deck.gl's
-        // own render frame / event dispatch and leaves its frame and
-        // interaction state broken — the map stopped showing new layers
-        // after zooms and pans (a USER chart's hover threw on every frame
-        // the mouse was over an arrow, see pickedFeature). Both are guarded.
-        getTooltip: (info) => {
-          try { return tooltipFor(info); } catch (err) {
-            if (!tooltipErrorLogged) { tooltipErrorLogged = true; console.error('[ixmaps-gl] tooltip failed:', err); }
-            return null;
-          }
-        },
-        onClick: (info) => {
-          try { return clickFor(info); } catch (err) {
-            console.error('[ixmaps-gl] click failed:', err);
-            return false;
-          }
-        }
+        // (guarded: see createTooltips)
+        getTooltip: tooltips.getTooltip,
+        onClick: tooltips.onClick
       });
-      let tooltipErrorLogged = false;
-      // a USER chart's picked item is {d, icon} (see _buildUserChartLayers):
-      // the feature is its d
-      function pickedFeature(o) { return o && o.icon && o.d ? o.d : o; }
-      function tooltipFor({ object: picked, layer }) {
-          const object = pickedFeature(picked);
-          if (!object || !layer) return null;
-          // suppress the hover tooltip ONLY for the specific item that's
-          // pinned (showing both would just duplicate the same content) —
-          // every OTHER item still gets its normal hover preview even
-          // while something else stays pinned
-          if (pinned && isSameAsPinned(layer.id, object)) return null;
-          const rt = findRuntimeForLayerId(layer.id);
-          if (!rt) return null;
-          const html = rt.buildTooltipHtml(object);
-          return html ? { html, style: Object.assign({ fontSize: '0.85em', padding: '0.5em 0.7em', maxWidth: '320px' }, tooltipLook()) } : null;
-      }
-      function clickFor(picked) {
-          const info = picked && Object.assign({}, picked, { object: pickedFeature(picked.object) });
-          if (info && info.object && info.layer) {
-            const rt = findRuntimeForLayerId(info.layer.id);
-            if (rt) {
-              // Only a Point geometry's own coordinates ARE an
-              // [lng,lat] pair (every point/bubble/dot/chart-cluster
-              // layer) — a CHOROPLETH polygon's geometry.coordinates is
-              // a nested array of RINGS, which map.project() below
-              // can't accept (confirmed live: threw MapLibre's own
-              // "LngLatLike argument must be..." error). The `||
-              // info.coordinate` fallback this used to lean on never
-              // actually ran for a polygon — a nested array is truthy,
-              // so the left side always "won" — which is the real bug
-              // this fixes: the pinned tooltip stuck at its default
-              // top:0/left:0 (never got a real position because
-              // updatePinnedTooltipPosition's map.project() threw
-              // before setting one), AND that same uncaught exception,
-              // thrown from inside deck.gl's own click-dispatch
-              // callback, left deck.gl's pointer-interaction state
-              // corrupted enough to block all further pan/zoom —
-              // confirmed live, both symptoms disappear together once
-              // this stops throwing. info.coordinate (the actual
-              // clicked map location, provided regardless of feature
-              // geometry type) anchors every non-Point case correctly.
-              const lngLat = (info.object.geometry && info.object.geometry.type === 'Point')
-                ? info.object.geometry.coordinates
-                : info.coordinate;
-              pinned = { runtime: rt, object: info.object, lngLat, layerId: info.layer.id };
-              renderPinnedTooltip();
-              hideDefaultHoverTooltip();
-              return true;
-            }
-          }
-          // clicked empty map space (or a non-tooltippable layer) -> unpin
-          pinned = null;
-          pinnedTooltipEl.style.display = 'none';
-          return false;
-      }
       map.addControl(overlay);
       map.addControl(new maplibregl.NavigationControl(), 'top-left');
-      map.on('move', updatePinnedTooltipPosition);
-
-      if (el.parentElement) {
-        el.parentElement.style.position = el.parentElement.style.position || 'relative';
-        el.parentElement.appendChild(pinnedTooltipEl);
-      }
+      tooltips.mount();
 
       if (this._legendHtml && el.parentElement) {
         const legendEl = document.createElement('div');
@@ -3416,6 +4081,8 @@
         },
         setMapTypeId: (id) => engineApi.setMapType(id),
         mapType: (id) => engineApi.setMapType(id),
+        // flat's getMapTypeId(): the basemap type name in use
+        getMapTypeId: () => String(builder.mapOptions.mapType || ''),
         setBasemapOpacity: (delta, mode) => {
           _basemapOpacity = mode === 'relative'
             ? Math.max(0, Math.min(1, _basemapOpacity + (parseFloat(delta) || 0)))
@@ -3857,6 +4524,7 @@
         runtimes.push(rt);
         _globalThemeRegistry.set(rt.name, rt);
         if (rt.meta && rt.meta.name && rt.meta.name !== rt.name) _globalThemeRegistry.set(rt.meta.name, rt);
+        if (themeIdOf(rt) !== rt.name) _globalThemeRegistry.set(themeIdOf(rt), rt);
         addLegendPanel(rt);
         notifyNewTheme(rt);
         refresh();
@@ -4139,8 +4807,25 @@
         refresh();
       });
 
+      // flat's page hook ixmaps.htmlgui_onDrawTheme(szId), called when a
+      // theme has been drawn: here once per settled redraw, for every
+      // shown theme, with its id. Not re-entered when the hook itself
+      // changes a theme (changeThemeStyle → refresh → here again).
+      let inDrawThemeHook = false;
+      function callDrawThemeHooks() {
+        const hook = pageIxmaps() && pageIxmaps().htmlgui_onDrawTheme;
+        if (typeof hook !== 'function' || inDrawThemeHook) return;
+        inDrawThemeHook = true;
+        try {
+          for (const rt of runtimes.slice()) {
+            if (rt._hidden) continue;
+            try { hook.call(global.ixmaps, themeIdOf(rt)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onDrawTheme:', e); }
+          }
+        } finally { inDrawThemeHook = false; }
+      }
       function notifyRedraw() {
         redrawListeners.forEach(cb => { try { cb(); } catch (err) { console.error('[ixmaps-gl] onRedraw callback failed:', err); } });
+        callDrawThemeHooks();
       }
 
       // For explicit, discrete API calls (setFacetFilter, setSizeField,
@@ -4201,741 +4886,57 @@
       }
 
       // onRedraw listeners (facets sidebar) are notified on their OWN,
-      // longer debounce, separate from the map's own 150ms layer throttle
-      // above — measured cost: getFacets() over every configured field
-      // plus the sidebar DOM rebuild can run ~55-70ms at a zoomed-out
-      // viewport (tens of thousands of in-view points), vs ~5ms for
-      // refreshLayers() itself. Running that on every throttled pan/zoom
-      // tick visibly competed with the map's own frame budget; recomputing
-      // it only once movement settles (this fires once, NOTIFY_REDRAW_MS
-      // after the last 'move' event) keeps panning smooth and matches the
-      // real ixmaps engine's own shape — htmlgui_onDrawTheme (facets) fires
-      // once per completed theme redraw, not per intermediate pan frame.
-      const NOTIFY_REDRAW_MS = 400;
-      let notifyRedrawTimer = null;
-      function scheduleNotifyRedraw() {
-        clearTimeout(notifyRedrawTimer);
-        notifyRedrawTimer = setTimeout(notifyRedraw, NOTIFY_REDRAW_MS);
-      }
-
-      map.on('move', scheduleRefresh);
-      window.addEventListener('resize', () => map.resize());
-
-      // GL-PORT COMPAT: real ixmaps-flat's map.on("layerdraw", cb) fires
-      // once per THEME as it finishes drawing, handing the callback an
-      // event object carrying that theme's own id (e.constructor.id).
-      // This engine has no equivalent per-theme draw event — onRedraw
-      // fires once per REFRESH of the whole map (see its own comment,
-      // above) — so "layerdraw" is approximated by firing the registered
-      // callback once per CURRENT runtime, synthesizing {id: rt.name},
-      // every time onRedraw fires. A page reacting to "layerdraw" by
-      // reading THAT theme's own state (e.g. recomputing a stats sidebar
-      // via getThemeObj/getFacets — see the global compat shims, below)
-      // gets the same practical effect: fresh numbers after every redraw,
-      // for every theme, without needing the page rewritten around a
-      // finer-grained event this engine doesn't produce.
-      const layerdrawCbs = (this._pendingEvents || [])
-        .filter(([event]) => event === 'layerdraw')
-        .map(([, cb]) => cb);
-      if (layerdrawCbs.length) {
-        engineApi.onRedraw(() => {
-          runtimes.forEach(rt => {
-            layerdrawCbs.forEach(cb => {
-              try { cb({ id: rt.name }); } catch (err) { console.error('[ixmaps-gl] "layerdraw" callback failed:', err); }
-            });
-          });
-        });
-      }
-
-      // NATIVE INTERACTIVE LEGEND — real ixmaps-flat's legend.js
-      // (makeColorLegendHTMLLong) builds, per CATEGORICAL-ish theme: a
-      // title/snippet header, one row per category (color swatch + a bar
-      // proportional to that category's own total + right-aligned
-      // formatted value), a description/source footer, and a per-theme
-      // "Chart size" 25-200% slider — all read directly off source
-      // (ui/js/tools/legend.js:594-1037/3196-3393, ui/js/htmlgui.js:2196/
-      // 2208 for markThemeClass/unmarkThemeClass, ui/css/legend.css for
-      // the selected-row highlight) rather than guessed from the
-      // screenshot alone. Gated on `legend:"open"` — the one real map
-      // option this engine's own createMap already threads through as
-      // this.mapOptions (see mapOptions.legend below) — since there's no
-      // toolbar toggle button here to open/close it later the way the
-      // real engine's own chrome does.
-      //
-      // Deliberate divergences from the real implementation, both
-      // reasoned rather than accidental:
-      //   - Real legend.js does a full innerHTML rebuild on every single
-      //     theme redraw (even a bare click-toggle). renderRows() below
-      //     only rebuilds the ROWS (swatch/bar/value/highlight) — cheap,
-      //     and the only part that can actually change post-load (marks,
-      //     or an AGGREGATE theme's dataset-wide totals, which this port
-      //     doesn't yet let change post-load anyway) — rather than
-      //     tearing down and rebuilding title/snippet/description/slider
-      //     too, which never change. Same visible result, less DOM churn.
-      //   - Real "isolate_gray" mode dims non-marked SVG paths via a CSS
-      //     class; this engine dims via IconLayer's own getColor alpha
-      //     (see LayerRuntime#_iconAlpha) since these are deck.gl raster
-      //     icons, not DOM/SVG nodes a CSS rule could reach.
-      // Legend on/off and fold state as real ixmaps-flat reads the map
-      // option (htmlgui_flat.js:748-794): on whenever `legend` is given and
-      // isn't false/"false" ("true", "open", "", 1, …), folded for
-      // "closed", off when not given at all.
-      const legendOpt = this.mapOptions.legend;
-      // let, not const: map.setLegend(value) switches them at runtime (see setLegendOption)
-      let legendOn = legendIsOn(legendOpt);
-      let legendFolded = legendOpt === 'closed';
-      {
-        // Map-level `align` option positions the legend panel — a map-
-        // wide placement choice, not per-theme (unlike legendtheme/
-        // legendfilter above), so read once from this.mapOptions rather
-        // than per-runtime. Real ixmaps-flat ALSO has an `align` map
-        // option (ui/js/htmlgui_flat.js) controlling legend position, but
-        // its value shape is a free-form regex-matched left/right/center/
-        // top/bottom/pixel-prefixed string tied to a static in-page DOM
-        // panel — a different layout model from this panel's own
-        // position:absolute floating-overlay-over-the-map-canvas
-        // approach. This port reuses the real OPTION NAME but adapts the
-        // VALUE SHAPE to plain four-corner tokens matching how this panel
-        // is actually positioned — a deliberate divergence, same
-        // reasoning already applied to style.legendfilter's own name/
-        // shape choice earlier this session. Default "top-right" per
-        // explicit request (real engine's own fallback is right-anchored
-        // too, just without an opinion on vertical placement).
-        const ALIGN_CSS = {
-          'top-left': 'left:10px;top:10px;',
-          'top-right': 'right:10px;top:10px;',
-          'bottom-left': 'left:10px;bottom:10px;',
-          'bottom-right': 'right:10px;bottom:10px;'
-        };
-        // gl's four corners, else flat's own values (htmlgui_flat.js
-        // 421-470): "…left" → left (the part before "left", else 55px), 12px
-        // from the top; "…right" → right (else 25px); "center" / "top" → top
-        // center
-        const flatAlignCss = align => {
-          const a = String(align || '');
-          if (/left/.test(a)) return 'left:' + (a.split('left')[0] || '55px') + ';top:12px;';
-          if (/right/.test(a)) return 'right:' + (a.split('right')[0] || '25px') + ';top:10px;';
-          if (a === 'center' || a === 'top') return 'left:50%;transform:translateX(-50%);top:10px;';
-          return null;
-        };
-        const legendAlignCss = ALIGN_CSS[this.mapOptions.align] || flatAlignCss(this.mapOptions.align) || ALIGN_CSS['top-right'];
-        // Real ixmaps-flat's SUB-THEME (MapTheme.createSubTheme,
-        // maptheme.js 14284-14292 / 15010-15160; map.Themes.enableSubThemes
-        // defaults to true): marking fields of a multi-field choropleth
-        // (DOMINANT/COMPOSECOLOR, not CHART) paints a new theme over the
-        // original — one field: CHOROPLETH|LOG|DOPACITY on that field, white
-        // → the field's color in 7 steps, dopacityscale 2, dopacitypow 1,
-        // keeping DOPACITY(→DOPACITYMAX)/AGGREGATE/GROUP/SUM/ZEROISVALUE/
-        // VALUES; several fields: the original type on just those fields
-        // and colors. It reuses the original's joined polygons, has no
-        // legend and stays out of the theme registry (its name
-        // "<layer>::subtheme" also keeps its deck.gl layer id apart), so
-        // markThemeClass/removeTheme still address the original.
-        const subThemeCapable = rt => rt.flags.has('CHOROPLETH') && !rt.flags.has('CHART') && (rt.flags.has('DOMINANT') || rt.flags.has('COMPOSECOLOR'));
-        const toHex = c => Array.isArray(c) ? '#' + c.slice(0, 3).map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('') : c;
-        updateSubTheme = (rt) => {
-          if (rt._subTheme) {
-            const i = runtimes.indexOf(rt._subTheme);
-            if (i >= 0) runtimes.splice(i, 1);
-            rt._subTheme = null;
-          }
-          const fields = String(rt.binding.value || '').split('|');
-          const marks = [...rt._markedClasses].filter(i => i >= 0 && i < fields.length).sort((a, b) => a - b);
-          if (marks.length) {
-            const colors = (rt.categoryColorsRgb || []).map(toHex);
-            const labels = rt.categoryDisplayLabels || rt.categoryLabels || fields;
-            const kept = ['DOPACITY', 'AGGREGATE', 'GROUP', 'SUM', 'ZEROISVALUE', 'VALUES']
-              .filter(f => [...rt.flags].some(x => x.startsWith(f) && (f !== 'DOPACITY' || /^DOPACITY/.test(x))))
-              .map(f => (f === 'DOPACITY' ? 'DOPACITYMAX' : f));
-            let def;
-            if (marks.length > 1) {
-              def = {
-                layer: rt.name + '::subtheme',
-                binding: (b => { delete b.field100; delete b.value100; return b; })(Object.assign({}, rt.binding, { value: marks.map(i => fields[i]).join('|') })),
-                style: Object.assign({}, rt.style, { type: [...rt.flags].concat(['SUBTHEME', 'NOLEGEND']).join('|'),
-                  colorscheme: marks.map(i => colors[i]), values: marks.map(i => labels[i]) }),
-                meta: { title: 'actual selection' }
-              };
-            } else {
-              const i = marks[0];
-              const binding = Object.assign({}, rt.binding, { value: fields[i] });
-              delete binding.alpha; delete binding.alpha100;
-              // rt.features already carry the field100 result — drop it and
-              // every alias of it, or normalizeTheme would apply it again
-              delete binding.field100; delete binding.value100;
-              def = {
-                layer: rt.name + '::subtheme',
-                binding,
-                style: { type: ['CHOROPLETH', 'LOG', 'DOPACITY', 'NOLEGEND', 'SUBTHEME'].concat(kept).join('|'),
-                  colorscheme: ['7', 'white', colors[i]], dopacityscale: 2, dopacitypow: 1,
-                  units: rt.style.units, linecolor: rt.style.linecolor, linewidth: rt.style.linewidth },
-                meta: { title: 'actual selection' }
-              };
-            }
-            const sub = new LayerRuntime(normalizeTheme(def), { type: 'FeatureCollection', features: rt.features }, builder._engineOptions);
-            sub._isSubTheme = true;
-            runtimes.splice(runtimes.indexOf(rt) + 1, 0, sub);
-            rt._subTheme = sub;
-          }
-          refresh();
-          notifyRedraw();
-        };
-        // the stack of the theme panels — flat shows one theme's legend
-        // after the other in #map-legend, separated by a line, and leaves
-        // out a theme hidden, out of scale or not yet drawn
-        let legendStack = null;
-        const legendStackEl = shadow => {
-          if (legendStack && legendStack.parentNode) return legendStack;
-          legendStack = document.createElement('div');
-          legendStack.className = 'ix-legend-stack';
-          legendStack.style.cssText = 'position:absolute;' + legendAlignCss + 'z-index:6;width:280px;'
-            + 'display:flex;flex-direction:column;max-height:calc(100% - 24px);overflow-y:auto;'
-            + 'border-radius:6px;box-shadow:' + shadow + ';pointer-events:auto;';
-          if (!document.getElementById('ix-legend-stack-css')) {
-            const css = document.createElement('style');
-            css.id = 'ix-legend-stack-css';
-            css.textContent = '.ix-legend-stack>.ix-native-legend:not([data-ixoff])~.ix-native-legend:not([data-ixoff]){border-top:1px solid rgba(128,128,128,.35)}';
-            document.head.appendChild(css);
-          }
-          el.parentElement.appendChild(legendStack);
-          return legendStack;
-        };
-        // map.setLegend(value): the `legend` map option at runtime, same values as
-        // ixmaps.Map(id, {legend}) — on ("true", "open", …), folded ("closed"), off
-        // (false/"false"/0/undefined). Panels are made for themes that lack one,
-        // removed when off, folded/unfolded otherwise.
-        setLegendOption = (opt) => {
-          builder.mapOptions.legend = opt;
-          legendFolded = opt === 'closed';
-          legendOn = legendIsOn(opt);
-          runtimes.forEach(rt => {
-            if (!legendOn) {
-              if (rt._legendPanel && rt._legendPanel.parentNode) rt._legendPanel.parentNode.removeChild(rt._legendPanel);
-              rt._legendPanel = null;
-            } else if (!rt._legendPanel) addLegendPanel(rt);
-            else if (rt._setLegendCollapsed) rt._setLegendCollapsed(legendFolded);
-          });
-          layoutLegends();
-        };
-        layoutLegends = () => {
-          if (!legendStack) return;
-          const z = map.getZoom();
-          let shown = 0;
-          [...legendStack.children].forEach(panel => {
-            const rt = panel._ixRuntime;
-            const off = !rt || rt._hidden || themeHiddenByScale(rt.flags, rt.style, z);
-            if (off) { panel.setAttribute('data-ixoff', ''); panel.style.display = 'none'; }
-            else { panel.removeAttribute('data-ixoff'); panel.style.display = 'flex'; shown++; }
-          });
-          legendStack.style.display = shown ? 'flex' : 'none';
-        };
-        const legendApplies = rt => rt.categoryLabels && rt.categoryLabels.length && !rt.flags.has('FEATURE') && !rt.flags.has('FEATURES') && !rt.flags.has('NOLEGEND');
-        // One theme's panel — at build time for every theme, and again for a
-        // theme defined later (map.layer(...) in a myMap.then(...) chain,
-        // defineLayer, loadProject); removeTheme removes it with the theme.
-        addLegendPanel = (rt) => {
-          // marking a class (legend row, or ixmaps.markThemeClass from a
-          // page) redraws — for every theme, legend panel or not
-          rt._triggerRedraw = () => { refresh(); };
-          if (subThemeCapable(rt)) rt._onMarksChanged = () => updateSubTheme(rt);
-          if (!legendOn || !el.parentElement || !legendApplies(rt)) return;
-          el.parentElement.style.position = el.parentElement.style.position || 'relative';
-          {
-          // .type("...|NOLEGEND") — the fourth real legend-related type()
-          // token: opts a theme OUT of the legend entirely (real engine's
-          // own per-layer "skip this one" flag, distinct from the map-
-          // level legend:"open"/"closed" option gating the whole panel).
-          // Same free-parsing story as SIMPLELEGEND/COMPACTLEGEND above —
-          // just one more flag to exclude on, no new plumbing.
-            const panel = document.createElement('div');
-            rt._legendPanel = panel;
-            panel.className = 'ix-native-legend';
-            // Opt-in via .style({legendtheme:"light"}) — a NEW, ixmaps-gl-
-            // only convention (same naming pattern as the sibling
-            // legendfilter/legendunits keys added earlier this session):
-            // real ixmaps-flat's legend.js has no such switch, this panel
-            // is entirely this port's own construction. Default ("dark")
-            // preserves the original always-dark panel exactly; "light" is
-            // for pages using a light basemap (e.g. CARTO Positron) where
-            // a dark semi-transparent panel reads as a mismatched dark
-            // patch rather than legend chrome. Every other hardcoded panel
-            // color below (rows, bar track, filter <select>) is expressed
-            // in terms of this one palette so the two variants stay in
-            // sync — no separate light/dark branch anywhere else.
-            // flat's look (flatLegendLook) unless the page picks one with
-            // this engine's own legendtheme
-            const opacityOpt = parseFloat(this._engineOptions.basemapopacity);
-            const flatLook = flatLegendLook(this.mapOptions.mapType, isNaN(opacityOpt) ? 1 : opacityOpt, this.mapOptions.legendBackground || this.mapOptions.legendbackground);
-            const isLightLegend = rt.style.legendtheme === 'light' || (rt.style.legendtheme !== 'dark' && !flatLook.dark);
-            const legendColors = isLightLegend
-              ? { bg: 'rgba(255,255,255,0.92)', fg: '#1a1a1a', shadow: '0 2px 10px rgba(0,0,0,0.18)',
-                  rowMarked: 'rgba(0,0,0,0.08)', track: 'rgba(0,0,0,0.08)',
-                  selectBg: 'rgba(0,0,0,0.04)', selectBorder: 'rgba(0,0,0,0.2)' }
-              : { bg: 'rgba(28,30,34,0.92)', fg: '#eee', shadow: '0 2px 10px rgba(0,0,0,0.45)',
-                  rowMarked: 'rgba(255,255,255,0.14)', track: 'rgba(255,255,255,0.08)',
-                  selectBg: 'rgba(255,255,255,0.08)', selectBorder: 'rgba(255,255,255,0.25)' };
-            if (!rt.style.legendtheme) legendColors.bg = flatLook.bg;
-            // max-height:66% resolves against el.parentElement's own
-            // height (the map container, which always has a definite
-            // height for the map itself to render into) since this panel
-            // is absolutely positioned inside it — a plain percentage on
-            // an absolutely-positioned element's height IS legal CSS as
-            // long as its containing block has a definite height, which
-            // this one does. display:flex column + min-height:0 on the
-            // ROWS wrapper below (not this outer panel) is what makes
-            // only the row list scroll while the header/description/
-            // slider stay fixed in place — a flex child won't actually
-            // shrink to fit and scroll internally without min-height:0,
-            // it just overflows its flex parent instead.
-            // one box for every theme, as flat's #map-legend (legend.js
-            // 2200-2460): the panels stack in the legend stack in theme
-            // order, a line between them (see layoutLegends)
-            panel.style.cssText = 'position:relative;flex:0 0 auto;'
-              + 'display:flex;flex-direction:column;'
-              + 'background:' + legendColors.bg + ';color:' + legendColors.fg + ';font:12px/1.4 -apple-system,Arial,sans-serif;'
-              + 'padding:10px 12px 12px;pointer-events:auto;';
-            const stack = legendStackEl(legendColors.shadow);
-            const at = runtimes.indexOf(rt);
-            const next = [...stack.children].find(c => runtimes.indexOf(c._ixRuntime) > at);
-            panel._ixRuntime = rt;
-            stack.insertBefore(panel, next || null);
-
-            // SUM+valuefield mirrors the real engine's own "SUM style
-            // aggregation" reading (style.valuefield, falling back to
-            // the bound size field); anything else (plain CATEGORICAL,
-            // no SUM) falls back to a per-category record COUNT.
-            const useSum = flatFlag(rt.flags, 'SUM') && rt.style.valuefield;
-            const valueField = rt.style.valuefield || rt.binding.size;
-            // legendunits wins over the theme's general-purpose units
-            // (used elsewhere for tooltips, e.g. _renderItemChartHtml) —
-            // a page may want a different/no unit string specifically on
-            // the legend's own value column. Appended as-is (no extra
-            // space injected), matching how style.units/legendunits are
-            // themselves authored with their own leading space (e.g.
-            // " MW") in real pages.
-            const legendUnit = rt.style.legendunits || rt.style.units || '';
-            const labels = rt.categoryDisplayLabels || rt.categoryLabels;
-            // .type("...|TEXTLEGEND") — the FIFTH real legend-related
-            // type() token: title/snippet/description text only, no
-            // category rows at all (swatches, bars, chips — none of it),
-            // per explicit correction. Everything below that builds the
-            // rows/totals/onRedraw-recompute wiring is skipped outright
-            // rather than built-then-hidden — there is nothing for any of
-            // it to feed once no rows ever render. The country-filter
-            // dropdown and Chart-size slider stay: neither is a
-            // "categorical item" or "colorscheme swatch", both are
-            // independent controls unrelated to the row list.
-            const isTextOnly = rt.flags.has('TEXTLEGEND');
-
-            // Map-view-aware per explicit request: totals reflect only
-            // what's CURRENTLY on screen (the map's own bounds, plus the
-            // same far-hemisphere exclusion _buildChartLayers itself
-            // applies under globe projection — see isOnVisibleHemisphere)
-            // rather than the whole dataset — recomputed on every redraw
-            // (engineApi.onRedraw, below) so panning/zooming/rotating
-            // updates the bars and values live, the same way the actual
-            // rendered bubbles change. Same simple rectangular bbox
-            // membership test _computeAggregatedItems's own non-AGGREGATE
-            // branch uses (no antimeridian wraparound handling — matches
-            // that existing convention, not a new gap this introduces).
-            let totals, maxTotal, order, rowsScroll;
-            // No-op default: TEXTLEGEND never reassigns this (see below),
-            // so the LATER unconditional-looking `renderRows()` call
-            // safely does nothing rather than needing its own isTextOnly
-            // guard at every call site.
-            let renderRows = () => {};
-            if (!isTextOnly) {
-            function computeTotals() {
-              const bounds = map.getBounds();
-              const bbox = [bounds.getWest(), bounds.getSouth(), bounds.getEast(), bounds.getNorth()];
-              const proj = (typeof map.getProjection === 'function' && map.getProjection()) || { type: 'mercator' };
-              const globeCenter = proj.type === 'globe' ? map.getCenter() : null;
-              totals = new Array(rt.categoryLabels.length).fill(0);
-              if (rt._rangeClassed) { totals = rangeClassLegendTotals(rt, bbox, globeCenter); maxTotal = Math.max(0, ...totals); order = totals.map((v, i) => i).sort((a, b) => totals[b] - totals[a]); return; }
-              // _activeFeatures (set by setFacetFilter/clearFacetFilter,
-              // e.g. the country-select dropdown below) is the facet-
-              // filtered subset when a filter is active, null otherwise —
-              // reading it here keeps the legend's own numbers consistent
-              // with whatever the country filter is currently narrowing
-              // the map down to, not just with the viewport/hemisphere.
-              (rt._activeFeatures || rt.features).forEach(f => {
-                const idx = rt.categoryIndexByLabel ? rt.categoryIndexByLabel.get(f.properties[rt.binding.value]) : null;
-                if (idx == null) return;
-                const [lng, lat] = f.geometry.coordinates;
-                if (lng < bbox[0] || lng > bbox[2] || lat < bbox[1] || lat > bbox[3]) return;
-                if (globeCenter && !isOnVisibleHemisphere(lng, lat, globeCenter)) return;
-                totals[idx] += useSum ? (parseFloat(f.properties[valueField]) || 0) : 1;
-              });
-              maxTotal = Math.max(0, ...totals);
-              order = totals.map((v, i) => i).sort((a, b) => totals[b] - totals[a]);
-            }
-            computeTotals();
-
-            // Only THIS wrapper scrolls (flex:1 1 auto + min-height:0 lets
-            // it shrink to whatever's left of the panel's own 66%-height
-            // cap once the fixed header/description/slider take their
-            // share, then overflow-y:auto scrolls just the row list) —
-            // the header above and description/slider below stay put.
-            rowsScroll = document.createElement('div');
-            rowsScroll.style.cssText = 'flex:1 1 auto;min-height:0;overflow-y:auto;';
-            const rowsEl = document.createElement('div');
-            rowsEl.className = 'ix-legend-rows';
-            // .type("...|SIMPLELEGEND") — real ixmaps-flat's OTHER legend
-            // variant (confirmed against a real-engine screenshot, per
-            // explicit correction): swatch + label chips only, no bar, no
-            // value column. SIMPLELEGEND is just another pipe-delimited
-            // type() token — MapBuilder#type() already puts every token
-            // into this.flags regardless of whether anything reads it, so
-            // no new parsing was needed, only this render-mode branch.
-            // flex-wrap here (vs. the bar mode's block rows) — chips wrap
-            // to the panel's own width the same loose way the real
-            // engine's screenshot shows (an uneven number of chips per
-            // row, driven by each label's own text length, not a fixed
-            // column grid).
-            // .type("...|COMPACTLEGEND") — the THIRD real legend variant
-            // (again confirmed against a real-engine screenshot, per
-            // explicit correction): the bar-mode's own two-line label/bar/
-            // value row, but wrapped into a multi-column flex-wrap grid
-            // instead of one full-width row per category — each item's
-            // own width follows its content (a bigger value's longer bar
-            // makes its own item wider, so fewer fit per line; Coal alone
-            // filled its own row in the reference screenshot while the
-            // smaller categories packed 3-4 per row) rather than a fixed
-            // column count.
-            if (rt.flags.has('SIMPLELEGEND') || rt.flags.has('COMPACTLEGEND')) {
-              rowsEl.style.cssText = 'display:flex;flex-wrap:wrap;gap:4px;';
-            }
-            rowsScroll.appendChild(rowsEl);
-
-            // Two lines per row — label on its own full-width line, then
-            // swatch+bar+value below — per explicit correction: a single
-            // shared line left too little room for the bar to read as
-            // proportional (it was squeezed between the label text and a
-            // fixed-width value column). The bar itself lives inside a
-            // flex:1 "track" div sized to whatever's left after the fixed
-            // swatch/value columns, and is a PERCENTAGE of that track's
-            // own width (not a pixel value) — real formula's per-unit-
-            // factor/cap (legend.js:980-984/946-950) collapses to a plain
-            // linear percentage-of-max once the bar's available width
-            // isn't a fixed constant this code has to guess at.
-            const isSimple = rt.flags.has('SIMPLELEGEND');
-            const isCompact = rt.flags.has('COMPACTLEGEND');
-            // Compact mode's bar can't use the full-width mode's
-            // percentage-of-flex-track trick (there's no full-width track
-            // to be a percentage OF once the row itself is content-sized,
-            // not stretched) — a plain pixel width, proportional to value
-            // and capped, same shape as the full-width formula just
-            // expressed in absolute px instead of a % of an elastic track.
-            const COMPACT_MAX_BAR_PX = 70;
-            // flat's compact legend (legend.js makeColorLegendHTML, the
-            // "compact" mode the theme legends use, 1212-1257): a range
-            // theme of 5 classes or more without labels is one line of
-            // color patches with the value range below; DOPACITY with an
-            // alpha field adds two paler lines (opacity 1/2, 1/3) and the
-            // alpha max, "↓" and min to their right (1062-1205). The
-            // legend's own __formatValue (legend.js 451-553) has no SPACE
-            // form: SPACE there is flat's plain "." thousands.
-            const flatCompactLegend = rt._rangeClassed && !flatFlag(rt.flags, 'CATEGORICAL') && !flatFlag(rt.flags, 'PLOT')
-              && (rt.partsA || []).length >= 5 && !(Array.isArray(rt.style.label) && rt.style.label.length);
-            // flat's single-color legend (legend.js 765-769, 1039-1046): a range
-            // theme of at most 2 classes without label/ranges, not
-            // CATEGORICAL, is one row — the swatch and "min ... max unit",
-            // or, when every value is 1 (a "$item$" count), its label or
-            // value field
-            const flatSingleRowLegend = rt._rangeClassed && !flatFlag(rt.flags, 'CATEGORICAL') && !flatFlag(rt.flags, 'PLOT')
-              && (rt.partsA || []).length <= 2 && !(Array.isArray(rt.style.label) && rt.style.label.length)
-              && !(Array.isArray(rt.style.ranges) && rt.style.ranges.length);
-            if (flatSingleRowLegend) {
-              renderRows = function() {
-                const rgb = rt.categoryColorsRgb[0] || [128, 128, 128];
-                const unit = String(rt.style.legendunits || rt.style.units || '').replace(/ /g, '&nbsp;');
-                const vMin = styleNum(rt.style.minvalue) || rt._valueMin, vMax = styleNum(rt.style.maxvalue) || rt._valueMax;
-                const label = rt.style.label != null && !Array.isArray(rt.style.label) ? String(rt.style.label) : String(rt.binding.value || '');
-                const text = vMin !== 1 || vMax !== 1
-                  ? flatFormatValue(vMin, 2, 'BLANK') + ' &nbsp;... ' + flatFormatValue(vMax, 2, 'BLANK') + ' ' + unit
-                  : label;
-                const marked = rt._markedClasses.has(0);
-                rowsEl.innerHTML = '<div class="ix-legend-row" data-idx="0" style="display:flex;align-items:center;gap:5px;padding:4px 3px;cursor:pointer;border-radius:4px;'
-                  + 'background:' + (marked ? legendColors.rowMarked : 'transparent') + ';">'
-                  + '<span style="flex:0 0 auto;width:1.6em;height:0.8em;background:rgb(' + rgb[0] + ',' + rgb[1] + ',' + rgb[2] + ');"></span>'
-                  + '<span>' + text + '</span></div>';
-                rowsEl.querySelectorAll('.ix-legend-row').forEach(row => {
-                  row.addEventListener('click', () => {
-                    if (rt._markedClasses.has(0)) window.ixmaps.unmarkThemeClass(rt.name, 0);
-                    else window.ixmaps.markThemeClass(rt.name, 0);
-                  });
-                });
-              };
-            } else
-            if (flatCompactLegend) {
-              renderRows = function() {
-                const n = rt.categoryColorsRgb.length;
-                const withAlpha = flatFlag(rt.flags, 'DOPACITY') && rt.binding.alpha && rt._alphaMax;
-                const nLines = withAlpha ? 3 : 1;
-                const dec = rt.style.decimals != null ? parseInt(rt.style.decimals, 10) : 2;
-                const unit = rt.style.legendunits || rt.style.units || '';
-                const ranges = Array.isArray(rt.style.ranges) && rt.style.ranges.length ? rt.style.ranges.map(Number) : null;
-                const vMin = ranges ? ranges[0] : rt._valueMin, vMax = ranges ? ranges[ranges.length - 1] : rt._valueMax;
-                let html = '<div style="display:grid;grid-template-columns:repeat(' + n + ',1fr)' + (withAlpha ? ' auto' : '') + ';gap:1px;align-items:center;">';
-                for (let line = 0; line < nLines; line++) {
-                  for (let c = 0; c < n; c++) {
-                    const ix = flatFlag(rt.flags, 'INVERT') ? n - c - 1 : c;
-                    const rgb = rt.categoryColorsRgb[ix];
-                    const part = rt.partsA[ix];
-                    const title = part ? flatFormatValue(part.min, dec, '') + unit + ' ... ' + flatFormatValue(part.max, dec, '') + unit : '';
-                    const marked = rt._markedClasses.has(ix);
-                    html += '<span class="ix-legend-row" data-idx="' + ix + '" title="' + title + '" style="cursor:pointer;height:14px;'
-                      + 'background:rgb(' + rgb[0] + ',' + rgb[1] + ',' + rgb[2] + ');opacity:' + (1 / (line + 1)) + ';'
-                      + (marked ? 'outline:2px solid ' + legendColors.fg + ';outline-offset:-2px;' : '') + '"></span>';
-                  }
-                  if (withAlpha) {
-                    const txt = line === 0 ? flatFormatValue(rt._alphaMax, 0, 'BLANK')
-                      : line === 1 ? '&#8595; ' + (rt.style.alphavalueunits || '') : flatFormatValue(rt._alphaMin || 0, 0, 'BLANK');
-                    html += '<span style="padding-left:0.5em;white-space:nowrap;">' + txt + '</span>';
-                  }
-                }
-                html += '</div><div style="display:flex;justify-content:space-between;margin-top:3px;' + (withAlpha ? 'margin-right:4em;' : '') + '">'
-                  + '<span>' + flatFormatValue(vMin, dec, '') + (unit ? ' ' + unit : '') + '</span>'
-                  + '<span>' + flatFormatValue(vMax, dec, '') + (unit && unit.length <= 3 ? ' ' + unit : '') + '</span></div>';
-                rowsEl.innerHTML = html;
-                rowsEl.querySelectorAll('.ix-legend-row').forEach(cell => {
-                  cell.addEventListener('click', () => {
-                    const idx = parseInt(cell.dataset.idx, 10);
-                    if (rt._markedClasses.has(idx)) window.ixmaps.unmarkThemeClass(rt.name, idx);
-                    else window.ixmaps.markThemeClass(rt.name, idx);
-                  });
-                });
-              };
-            } else
-            renderRows = function() {
-              // flat drops the rows without a count once any row has one
-              // (legend.js 754-760, 787-789: fCountBars && !count)
-              rowsEl.innerHTML = order.filter(i => !(maxTotal > 0) || totals[i]).map(i => {
-                const rgb = rt.categoryColorsRgb[i];
-                const color = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`;
-                const marked = rt._markedClasses.has(i);
-                const dimmed = rt._markedClasses.size > 0 && !marked;
-                const rowStyle = 'padding:4px 3px;border-radius:4px;cursor:pointer;opacity:' + (dimmed ? 0.4 : 1) + ';'
-                  + 'background:' + (marked ? legendColors.rowMarked : 'transparent') + ';';
-                if (isSimple) {
-                  // Swatch + label only, no bar/value — see rowsEl's own
-                  // comment above for why (SIMPLELEGEND).
-                  return '<div class="ix-legend-row" data-idx="' + i + '" style="' + rowStyle
-                    + 'display:inline-flex;align-items:center;gap:5px;padding:4px 8px;">'
-                    + '<span style="flex:0 0 8px;width:8px;height:8px;border-radius:50%;background:' + color + ';"></span>'
-                    + '<span>' + labels[i] + '</span>'
-                    + '</div>';
-                }
-                const pct = maxTotal ? Math.max(0, Math.min(100, (totals[i] / maxTotal) * 100)) : 0;
-                if (isCompact) {
-                  // Same two-line label/bar/value shape as full-width bar
-                  // mode below, just content-sized (flex:0 0 auto, no
-                  // min-width:0 flex-1 track) so multiple items pack onto
-                  // one line inside rowsEl's own flex-wrap — see
-                  // COMPACTLEGEND's own comment on rowsEl above.
-                  const barPx = Math.max(2, (pct / 100) * COMPACT_MAX_BAR_PX);
-                  return '<div class="ix-legend-row" data-idx="' + i + '" style="' + rowStyle + 'flex:0 0 auto;">'
-                    + '<div style="margin-bottom:3px;white-space:nowrap;">' + labels[i] + '</div>'
-                    + '<div style="display:flex;align-items:center;gap:6px;">'
-                    + '<span style="flex:0 0 8px;width:8px;height:8px;border-radius:50%;background:' + color + ';"></span>'
-                    + '<span style="flex:0 0 auto;width:' + barPx + 'px;height:6px;background:' + color + ';border-radius:3px;"></span>'
-                    + '<span style="flex:0 0 auto;white-space:nowrap;">' + rt._formatTooltipValue(totals[i]) + legendUnit + '</span>'
-                    + '</div>'
-                    + '</div>';
-                }
-                return '<div class="ix-legend-row" data-idx="' + i + '" style="' + rowStyle + '">'
-                  + '<div style="margin-bottom:3px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">' + labels[i] + '</div>'
-                  + '<div style="display:flex;align-items:center;gap:6px;">'
-                  + '<span style="flex:0 0 8px;width:8px;height:8px;border-radius:50%;background:' + color + ';"></span>'
-                  + '<span style="flex:1 1 auto;min-width:0;height:6px;background:' + legendColors.track + ';border-radius:3px;overflow:hidden;">'
-                  + '<span style="display:block;height:100%;width:' + pct + '%;background:' + color + ';border-radius:3px;"></span>'
-                  + '</span>'
-                  + '<span style="flex:0 0 auto;text-align:right;min-width:60px;">' + rt._formatTooltipValue(totals[i]) + legendUnit + '</span>'
-                  + '</div>'
-                  + '</div>';
-              }).join('');
-              // GL-PORT COMPAT: real ixmaps-flat's row markup wires its
-              // click handler inline (onclick="ixmaps.markThemeClass(...)"
-              // — legend.js:817), toggle decided by the caller. Same
-              // split here: the toggle check lives in this click
-              // handler, the actual add/remove-and-redraw primitive is
-              // the module-level ixmaps.markThemeClass/unmarkThemeClass
-              // (see their own comment) — so a page's OWN custom UI
-              // calling those same two globals drives this exact legend
-              // too, not just these rows.
-              rowsEl.querySelectorAll('.ix-legend-row').forEach(rowEl => {
-                rowEl.addEventListener('click', () => {
-                  const idx = parseInt(rowEl.dataset.idx, 10);
-                  if (rt._markedClasses.has(idx)) window.ixmaps.unmarkThemeClass(rt.name, idx);
-                  else window.ixmaps.markThemeClass(rt.name, idx);
-                });
-              });
-            };
-
-            // Recompute+re-render on EVERY redraw, not just mark toggles —
-            // this is what makes the legend map-view-aware: a plain pan/
-            // zoom/rotate fires this too (via the map's own 'move'
-            // listener -> scheduleRefresh -> notifyRedraw, debounced the
-            // same 400ms as the facets sidebar's own onRedraw use), same
-            // signal already used elsewhere in this file for "the visible
-            // data just changed, recompute".
-            engineApi.onRedraw(() => { computeTotals(); renderRows(); });
-            }
-
-            // rt._triggerRedraw: see its own doc comment on LayerRuntime
-            // (set here rather than at construction time since refresh()
-            // doesn't exist yet when the runtime is built). Kept
-            // unconditional (even for TEXTLEGEND, which never registers
-            // the onRedraw recompute above) — a page can still call
-            // ixmaps.markThemeClass/unmarkThemeClass directly with no
-            // visual row list to click, and that should still redraw the
-            // MAP's own dim/isolate effect even without a legend UI for
-            // it, matching real-engine global-API availability regardless
-            // of legend style.
-            rt._triggerRedraw = () => { refresh(); };
-
-            // Header row (title/snippet + collapse toggle) always stays
-            // visible; everything else lives in `bodyEl`, hidden/shown as
-            // a single unit by the toggle below — collapsing shows just
-            // the title bar, matching the real engine's own fold/unfold
-            // behavior (ixmaps.legendState + the "legend-folded" CSS
-            // class, ui/js/tools/legend.js) even though this port toggles
-            // via a plain display swap on one wrapper div rather than a
-            // shared stylesheet class (this panel has no external CSS at
-            // all — everything here is inline-styled, unlike the real
-            // engine's DOM/CSS-class-driven legend).
-            const header = document.createElement('div');
-            header.style.cssText = 'display:flex;align-items:flex-start;justify-content:space-between;gap:6px;';
-            const headerText = document.createElement('div');
-            headerText.style.cssText = 'min-width:0;flex:1 1 auto;';
-            let headerHtml = '';
-            if (rt.meta.title) headerHtml += '<div style="font-weight:600;font-size:13px;margin-bottom:2px;">' + rt.meta.title + '</div>';
-            if (rt.meta.snippet) headerHtml += '<div style="opacity:0.75;">' + rt.meta.snippet + '</div>';
-            headerText.innerHTML = headerHtml;
-            header.appendChild(headerText);
-            const collapseBtn = document.createElement('button');
-            collapseBtn.type = 'button';
-            collapseBtn.style.cssText = 'flex:0 0 auto;background:transparent;border:none;color:inherit;'
-              + 'font-size:14px;line-height:1;cursor:pointer;padding:2px 4px;opacity:0.7;';
-            header.appendChild(collapseBtn);
-            panel.appendChild(header);
-
-            const bodyEl = document.createElement('div');
-            bodyEl.style.cssText = 'display:flex;flex-direction:column;min-height:0;flex:1 1 auto;margin-top:8px;';
-            panel.appendChild(bodyEl);
-
-            // Collapsed by default under the real engine's own narrow-
-            // screen legend threshold (ui/js/tools/legend.js: `if
-            // (window.innerWidth < 500) ixmaps.legend.hide()`) — reusing
-            // that concrete precedent rather than picking an arbitrary
-            // "mobile" breakpoint of this port's own invention. Checked
-            // once at panel-build time, not on resize — matching the real
-            // engine's own one-shot-at-redraw-time check, not a live
-            // matchMedia listener.
-            const MOBILE_LEGEND_BREAKPOINT = 500;
-            let collapsed = legendFolded || window.innerWidth < MOBILE_LEGEND_BREAKPOINT;
-            function applyCollapsed() {
-              bodyEl.style.display = collapsed ? 'none' : 'flex';
-              collapseBtn.textContent = collapsed ? '▸' : '▾';
-              collapseBtn.title = collapsed ? 'Expand legend' : 'Collapse legend';
-            }
-            collapseBtn.addEventListener('click', () => { collapsed = !collapsed; applyCollapsed(); });
-            applyCollapsed();
-            rt._setLegendCollapsed = c => { collapsed = !!c; applyCollapsed(); }; // setLegendOption
-
-            // Selection/filter by field — opt-in via .style({legendfilter:
-            // "<field>"}), e.g. "country_long" on the power-plants sample.
-            // A NEW, ixmaps-gl-only convention: real ixmaps-flat's own
-            // style.filterfield names the DEFAULT field an unqualified
-            // .filter("text") search term matches against (maptheme.js:
-            // 1275-1276/7359-7362) — a different concept entirely, so this
-            // deliberately uses its own name rather than overloading that
-            // one. Options come from the FULL dataset (a world-spanning
-            // bbox, not the current viewport) and stay fixed regardless of
-            // pan/zoom — unlike the map-view-aware category totals below,
-            // a picker whose own choices kept shrinking as you panned
-            // would make it impossible to select a country not currently
-            // in view. Selecting a value reuses the engine's own existing
-            // facet-filter primitive (engineApi.setFacetFilter/
-            // clearFacetFilter — already propagates to sibling runtimes
-            // sharing the same data source and calls refresh()), so this
-            // is UI wiring only, no new filtering logic.
-            const filterField = rt.style.legendfilter;
-            if (filterField) {
-              const facet = engineApi.getFacets(rt.name, [filterField], { bbox: [-180, -85, 180, 85] })[0];
-              const values = (facet && facet.type === 'textual')
-                ? facet.values.slice().sort((a, b) => String(a).localeCompare(String(b)))
-                : [];
-              const filterEl = document.createElement('select');
-              filterEl.style.cssText = 'width:100%;margin-bottom:8px;background:' + legendColors.selectBg + ';'
-                + 'color:' + legendColors.fg + ';border:1px solid ' + legendColors.selectBorder + ';border-radius:4px;padding:4px 6px;font:inherit;';
-              filterEl.innerHTML = '<option value="">All (' + values.length + ')</option>'
-                + values.map(v => '<option value="' + escapeHtml(v) + '">' + escapeHtml(v) + '</option>').join('');
-              filterEl.addEventListener('change', () => {
-                if (filterEl.value) engineApi.setFacetFilter(rt.name, filterField, filterEl.value);
-                else engineApi.clearFacetFilter(rt.name, filterField);
-              });
-              bodyEl.appendChild(filterEl);
-            }
+      // longer debounce, separate from the map's own 150ms layer throttle
+      // above — measured cost: getFacets() over every configured field
+      // plus the sidebar DOM rebuild can run ~55-70ms at a zoomed-out
+      // viewport (tens of thousands of in-view points), vs ~5ms for
+      // refreshLayers() itself. Running that on every throttled pan/zoom
+      // tick visibly competed with the map's own frame budget; recomputing
+      // it only once movement settles (this fires once, NOTIFY_REDRAW_MS
+      // after the last 'move' event) keeps panning smooth and matches the
+      // real ixmaps engine's own shape — htmlgui_onDrawTheme (facets) fires
+      // once per completed theme redraw, not per intermediate pan frame.
+      const NOTIFY_REDRAW_MS = 400;
+      let notifyRedrawTimer = null;
+      function scheduleNotifyRedraw() {
+        clearTimeout(notifyRedrawTimer);
+        notifyRedrawTimer = setTimeout(notifyRedraw, NOTIFY_REDRAW_MS);
+      }
 
-            if (!isTextOnly) { bodyEl.appendChild(rowsScroll); renderRows(); }
-
-            if (rt.meta.description) {
-              const desc = document.createElement('div');
-              desc.style.cssText = 'margin-top:8px;font-size:11px;opacity:0.8;';
-              // Raw HTML, matching the real engine's own description
-              // rendering and this engine's existing .legend(html)/
-              // tooltip conventions (e.g. _buildTooltipContext) — real
-              // pages already embed their own source-citation markup
-              // inside meta.description (see the power-plants sample).
-              desc.innerHTML = rt.meta.description;
-              bodyEl.appendChild(desc);
-            }
+      map.on('move', scheduleRefresh);
+      window.addEventListener('resize', () => map.resize());
 
-            // Chart-size slider — real engine's own range (legend.js:
-            // 3196-3202), 100% == scale:1, wired to changeThemeStyle(
-            // themeId,"scale:"+pct/100,"set")+redrawTheme there; this
-            // engine's equivalent is rt.setStyle({scale}) + refresh(),
-            // the same primitive engineApi.setThemeStyle uses above.
-            // CHOROPLETH themes get an OPACITY slider instead, as in flat
-            // (legend.js ~3190: 0-100%, fillopacity·100, default 90;
-            // changeThemeStyle("fillopacity:"+pct/100,"set") + redraw).
-            // (flat labels a VECTOR theme's size slider "Line width" — gl has
-            // no VECTOR themes.)
-            // Flat tests the words (legend.js 2533-2535): a "CHOROPLETHE"
-            // theme has neither slider.
-            const typeWords = rt.flags.typeString != null ? rt.flags.typeString : [...rt.flags].join('|');
-            const isOpacitySlider = /\bCHOROPLETH\b/.test(typeWords);
-            const hasSlider = isOpacitySlider || /\bCHART\b|\bBUBBLE\b|\bDOT\b/.test(typeWords);
-            if (hasSlider) {
-            const sliderRow = document.createElement('div');
-            sliderRow.style.cssText = 'margin-top:10px;font-size:11px;opacity:0.8;';
-            const fillPct = Math.round(styleNum(rt.style.fillopacity) * 100);
-            const initialPct = isOpacitySlider
-              ? (Number.isFinite(fillPct) ? Math.max(0, Math.min(100, fillPct)) : 90)
-              : Math.round((styleNum(rt.style.scale) || 1) * 100);
-            const sliderLabel = isOpacitySlider ? 'Opacity' : 'Chart size';
-            sliderRow.innerHTML = sliderLabel + ': <span class="ix-legend-scale-val">' + initialPct + '</span>%';
-            bodyEl.appendChild(sliderRow);
-            const slider = document.createElement('input');
-            slider.type = 'range';
-            slider.min = isOpacitySlider ? '0' : '25';
-            slider.max = isOpacitySlider ? '100' : '200';
-            slider.value = String(initialPct);
-            slider.style.cssText = 'width:100%;margin-top:2px;';
-            slider.addEventListener('input', () => {
-              const pct = parseInt(slider.value, 10);
-              sliderRow.querySelector('.ix-legend-scale-val').textContent = pct;
-              rt.setStyle(isOpacitySlider ? { fillopacity: pct / 100 } : { scale: pct / 100 });
-              refresh();
+      // GL-PORT COMPAT: real ixmaps-flat's map.on("layerdraw", cb) fires
+      // once per THEME as it finishes drawing, handing the callback an
+      // event object carrying that theme's own id (e.constructor.id).
+      // This engine has no equivalent per-theme draw event — onRedraw
+      // fires once per REFRESH of the whole map (see its own comment,
+      // above) — so "layerdraw" is approximated by firing the registered
+      // callback once per CURRENT runtime, synthesizing {id: rt.name},
+      // every time onRedraw fires. A page reacting to "layerdraw" by
+      // reading THAT theme's own state (e.g. recomputing a stats sidebar
+      // via getThemeObj/getFacets — see the global compat shims, below)
+      // gets the same practical effect: fresh numbers after every redraw,
+      // for every theme, without needing the page rewritten around a
+      // finer-grained event this engine doesn't produce.
+      const layerdrawCbs = (this._pendingEvents || [])
+        .filter(([event]) => event === 'layerdraw')
+        .map(([, cb]) => cb);
+      if (layerdrawCbs.length) {
+        engineApi.onRedraw(() => {
+          runtimes.forEach(rt => {
+            layerdrawCbs.forEach(cb => {
+              try { cb({ id: rt.name }); } catch (err) { console.error('[ixmaps-gl] "layerdraw" callback failed:', err); }
             });
-            bodyEl.appendChild(slider);
-            }
-          }
-        };
-        runtimes.forEach(rt => addLegendPanel(rt));
+          });
+        });
       }
 
+      // the native legend: createLegend (its four hooks are what the rest
+      // of the map calls — panels, the legend option, sub-themes, layout)
+      ({ addLegendPanel, setLegendOption, updateSubTheme, layoutLegends } =
+        createLegend({ builder, map, el, overlay, runtimes, engineApi, built, refresh, scheduleRefresh, notifyRedraw }));
+
       _lastMapApi = engineApi;
       // ?ixgl-debug: ixmaps.__glDebug.check() reports, for the moment it is
       // called, every theme's geometry problems (invalid or mixed-dimension
@@ -5627,7 +5628,7 @@
   }
   // maptheme.js formatValue's NOBREAKS switch (26368): theme min > 999 and max < 3000
   function flatNoBreaks(vMin, vMax) {
-    return vMin > 999 && vMax < 3000;
+    return Number.isFinite(vMin) && Number.isFinite(vMax) && vMin > 999 && vMax < 3000;
   }
 
   // flat's chart position (maptheme.js 24441-24530 and 24603, the non-PLOT,
@@ -5737,9 +5738,13 @@
   // scale gate (maptheme.js 2609-2611, 8250-8260): the theme is hidden at
   // scales above featureupper and at or below featurelower ("1:200000" or
   // a bare denominator, __scanScaleValue 2021)
+  // a scale style value ("1:200000" or a bare denominator, flat's
+  // __scanScaleValue, maptheme.js 2021) as its denominator; 0 when unset
+  function scaleDenom(v) {
+    return (v == null || v === '' ? 0 : Number(String(v).includes(':') ? String(v).split(':')[1] : v)) || 0;
+  }
   function featuresHiddenByScale(style, zoom) {
-    const denom = v => (v == null || v === '' ? 0 : Number(String(v).includes(':') ? String(v).split(':')[1] : v)) || 0;
-    const upper = denom(style.featureupper), lower = denom(style.featurelower);
+    const upper = scaleDenom(style.featureupper), lower = scaleDenom(style.featurelower);
     if (!upper && !lower) return false;
     const scale = scaleDenominatorAt(zoom);
     return (lower && scale <= lower) || (upper && scale > upper);
@@ -5750,9 +5755,8 @@
   // chartupper and at or below chartlower; layerupper / layerlower stand in
   // for them when unset (1774-1779)
   function chartHiddenByScale(style, zoom) {
-    const denom = v => (v == null || v === '' ? 0 : Number(String(v).includes(':') ? String(v).split(':')[1] : v)) || 0;
-    const upper = denom(style.chartupper != null ? style.chartupper : style.layerupper);
-    const lower = denom(style.chartlower != null ? style.chartlower : style.layerlower);
+    const upper = scaleDenom(style.chartupper != null ? style.chartupper : style.layerupper);
+    const lower = scaleDenom(style.chartlower != null ? style.chartlower : style.layerlower);
     if (!upper && !lower) return false;
     const scale = scaleDenominatorAt(zoom);
     return !!((upper && scale > upper) || (lower && scale <= lower));
@@ -5761,8 +5765,7 @@
   // 1726-1734, 16986-16990): the GLOW halo is drawn at scales at or below
   // glowupper and at or above glowlower (both inclusive)
   function glowHiddenByScale(style, zoom) {
-    const denom = v => (v == null || v === '' ? 0 : Number(String(v).includes(':') ? String(v).split(':')[1] : v)) || 0;
-    const upper = denom(style.glowupper), lower = denom(style.glowlower);
+    const upper = scaleDenom(style.glowupper), lower = scaleDenom(style.glowlower);
     if (!upper && !lower) return false;
     const scale = scaleDenominatorAt(zoom);
     return !!((upper && scale > upper) || (lower && scale < lower));
@@ -5784,8 +5787,7 @@
     const on = style.shadow === true || style.shadow === 'true' || style.shadow === 1 || style.shadow === '1';
     if (!on) return false;
     if (count > (isNaN(styleNum(style.maxshadow)) ? 1000 : styleNum(style.maxshadow))) return false;
-    const denom = v => (v == null || v === '' ? 0 : Number(String(v).includes(':') ? String(v).split(':')[1] : v)) || 0;
-    const upper = denom(style.shadowupper), lower = denom(style.shadowlower);
+    const upper = scaleDenom(style.shadowupper), lower = scaleDenom(style.shadowlower);
     const scale = scaleDenominatorAt(zoom);
     return !((upper && scale > upper) || (lower && scale < lower));
   }
@@ -5799,8 +5801,7 @@
   // flat's BOX block (maptheme.js 18758-18760): the box — and its title —
   // is removed at scales above boxupper or below boxlower
   function boxHiddenByScale(style, zoom) {
-    const denom = v => (v == null || v === '' ? 0 : Number(String(v).includes(':') ? String(v).split(':')[1] : v)) || 0;
-    const upper = denom(style.boxupper), lower = denom(style.boxlower);
+    const upper = scaleDenom(style.boxupper), lower = scaleDenom(style.boxlower);
     const scale = scaleDenominatorAt(zoom);
     return !!((upper && scale > upper) || (lower && scale < lower));
   }
@@ -6133,8 +6134,9 @@
   // functionally deleted.
   const DIMMED_ICON_ALPHA = 8;
 
-  // deck.gl 8.9.35's IconLayer auto-packing atlas (icon-manager.ts) has NO
-  // eviction and NO cap of its own: its texture is 1024px wide (fixed) but
+  // deck.gl's IconLayer auto-packing atlas (icon-manager.ts, read and
+  // measured on 8.9.35; the guards below are kept for 9.x, not re-measured
+  // there) has NO eviction and NO cap of its own: its texture is 1024px wide (fixed) but
   // grows TALLER via power-of-two resize forever, for every distinct icon
   // id ever seen, for the lifetime of the layer — confirmed by reading
   // that file directly. There is no "atlas full" code path; it just keeps
@@ -6226,6 +6228,74 @@
     };
   }
 
+  // CHART|SYMBOL|SEQUENCE (flat maptheme.js 21184-21300, 21790-21925,
+  // 22296-22395): one symbol per category part of a chart, in category
+  // order or sorted (SORT: DOWN biggest first, UP smallest first), parts
+  // of value 0 left out. radiusOf(v) is the part's radius (flat: max radius
+  // · (v / max value)^(1/sizepow)). Placement:
+  //  - STAR: the first part is the center (star radius R = its radius); each
+  //    further part (with UP every part) sits on a circle around it, at
+  //    R + r (×1.5 EXPAND, ×2 EXPANDMAX, ×rangescale), stepping the angle
+  //    by f = 90° − asin(√((R+r)² − r²) / (R+r)) before and after it, so
+  //    neighbours touch; UP: radius R·(1 + parts/5), the angle step of the
+  //    7th part on divided by 1 + 2r/maxRadius; with EXPAND|SORT|UP,
+  //    R = (EXPANDMAX ? 2 : 0.5) · maxRadius · √(biggest / max value)
+  //    (LINEAR/SIZEP1: linear), COMPRESS halves it (COMPRESSMAX quarter)
+  //  - HORZ: side by side from the center to the right
+  //  - otherwise (or CENTER): all on the center
+  // Returns the parts in drawing order: { i, v, r, x, y } (pixels, y down).
+  function sequenceLayout(counts, flags, radiusOf, opts = {}) {
+    const has = f => flatFlag(flags, f);
+    const word = w => [...flags].some(f => new RegExp('\\b' + w + '\\b').test(f));
+    let order = counts.map((v, i) => ({ i, v }));
+    if (word('SORT')) {
+      if (word('UP')) order.sort((a, b) => a.v - b.v);
+      else if (word('DOWN')) order.sort((a, b) => b.v - a.v);
+    }
+    const parts = [];
+    const star = has('STAR') && !has('CENTER'), horz = has('HORZ') && !has('CENTER');
+    const up = word('UP');
+    const maxR = opts.maxRadius || 0;
+    const nStarParts = opts.nParts || counts.length;
+    let angle = 0, starR = null, x = 0;
+    order.forEach((p, k) => {
+      if (!p.v) return;
+      const r = radiusOf(p.v);
+      if (!(r > 0)) return;
+      let px = 0, py = 0;
+      if (star) {
+        if (starR === null) {
+          starR = r;
+          if (has('EXPAND') && word('SORT') && up) {
+            const big = order[order.length - 1].v, mv = opts.maxValue || big || 1;
+            starR = (has('EXPANDMAX') ? 2 : 0.5) * maxR * (has('LINEAR') || has('SIZEP1') ? big / mv : Math.sqrt(big / mv));
+          }
+          if (has('COMPRESS')) starR *= has('COMPRESSMAX') ? 0.25 : 0.5;
+        }
+        if (parts.length > 0 || up) {
+          const c = starR + r;
+          const b = Math.sqrt(Math.max(0, c * c - r * r));
+          let f = 90 - Math.asin(Math.min(1, b / c)) / Math.PI * 180;
+          let dist = starR + r;
+          if (up) {
+            if (k > 5) f /= (1 + 2 * (r / (maxR || r)));
+            dist = starR * (1 + nStarParts / 5);
+          }
+          if (opts.rangeScale) dist *= opts.rangeScale;
+          else dist = has('EXPANDMAX') ? dist * 2 : (has('EXPAND') ? dist * 1.5 : dist);
+          angle += f;
+          px = Math.cos(angle / 180 * Math.PI) * dist;
+          py = Math.sin(angle / 180 * Math.PI) * dist;
+          angle += f;
+        }
+      } else if (horz) {
+        x += r; px = x; x += r;
+      }
+      parts.push({ i: p.i, v: p.v, r, x: px, y: py });
+    });
+    return parts;
+  }
+
   // ---------------------------------------------------------------
   // Classification — pure functions (no LayerRuntime state): class
   // breaks for a numeric field, and which class a value falls in.
@@ -7180,7 +7250,7 @@
         key = `${snapped.x}:${snapped.y}`;
       }
       let cell = cells.get(key);
-      if (!cell) { cell = { snapped, sumX: 0, sumY: 0, n: 0, value: 0, classValue: 0, value100: 0, series: null, first: f }; cells.set(key, cell); }
+      if (!cell) { cell = { key, snapped, sumX: 0, sumY: 0, n: 0, value: 0, classValue: 0, value100: 0, series: null, first: f }; cells.set(key, cell); }
       cell.sumX += p.x; cell.sumY += p.y; cell.n++;
       cell.value += f.properties.value;
       if (f.properties.classValue !== undefined) cell.classValue += f.properties.classValue;
@@ -7202,6 +7272,9 @@
         ? { cluster: true, point_count: cell.n, value: cell.value, ...(hasClass ? { classValue: cell.classValue } : {}) }
         : cell.first.properties;
       if (cell.series && cell.n > 1) props = Object.assign({}, props, { series: cell.series });
+      // a field aggregation's cell key (the field value): the categories of
+      // one cell are merged by it (groupCoLocated), not by their positions
+      if (field) props = Object.assign({}, props, { aggKey: cell.key });
       if (post) {
         props = Object.assign({}, props);
         if (hasClass) props.classValue = post(cell.n > 1 ? cell.classValue : props.classValue, cell.value100, props.series);
@@ -7234,7 +7307,7 @@
     }
   }
 
-  function groupCoLocated(clusterFeatures, zoom, clusterRadiusPx, nCategories, flags) {
+  function groupCoLocated(clusterFeatures, zoom, clusterRadiusPx, nCategories, flags, atCellCenter = false) {
     // Merge tolerance MUST track the same theme-driven, scale-dependent
     // aggregation width the clustering itself just used (clusterRadiusPx,
     // set by _ensureClusterIndices right before this runs) — not an
@@ -7256,9 +7329,11 @@
       // recomputes ptPos as the mean of ptPosA regardless of which
       // grid produced the grouping key).
       const snapped = cellPx ? snapToAggregationGrid(p.x, p.y, cellPx, flags, zoom) : p;
-      const key = `${snapped.x}:${snapped.y}`;
+      // a field aggregation's categories each sit at the mean of their own
+      // records — merged by the field value, not by (float) position
+      const key = f.properties.aggKey != null ? f.properties.aggKey : `${snapped.x}:${snapped.y}`;
       let cell = cells.get(key);
-      if (!cell) { cell = { sumX: 0, sumY: 0, n: 0, counts: new Array(n).fill(0), recordCounts: new Array(n).fill(0), classTotal: undefined }; cells.set(key, cell); }
+      if (!cell) { cell = { sumX: 0, sumY: 0, n: 0, cx: snapped.x, cy: snapped.y, counts: new Array(n).fill(0), recordCounts: new Array(n).fill(0), classTotal: undefined }; cells.set(key, cell); }
       cell.sumX += p.x; cell.sumY += p.y; cell.n++;
       cell.counts[f.properties.cat] += f.properties.value;
       if (f.properties.classValue !== undefined) cell.classTotal = (cell.classTotal || 0) + f.properties.classValue;
@@ -7269,7 +7344,8 @@
       cell.recordCounts[f.properties.cat] += (f.properties.point_count || 1);
     });
     return Array.from(cells.values()).map(cell => {
-      const ll = worldPixelToLngLat(cell.sumX / cell.n, cell.sumY / cell.n, zoom);
+      // without RELOCATE flat's cell item sits at the cell center
+      const ll = atCellCenter && cellPx ? worldPixelToLngLat(cell.cx, cell.cy, zoom) : worldPixelToLngLat(cell.sumX / cell.n, cell.sumY / cell.n, zoom);
       return {
         geometry: { type: 'Point', coordinates: [ll.lng, ll.lat] },
         properties: { counts: cell.counts, total: cell.counts.reduce((a, c) => a + c, 0), recordCounts: cell.recordCounts, ...(cell.classTotal !== undefined ? { classTotal: cell.classTotal } : {}) }
@@ -7424,7 +7500,7 @@
         this._gridRefLat = (minLat <= maxLat) ? (minLat + maxLat) / 2 : 0;
       }
 
-      if (this.flags.has('DOMINANT') && this.binding.value) {
+      if (this.flags.has('DOMINANT') && this.binding.value && !isAggregatedCategoricalChoropleth(this)) {
         // .type("CHOROPLETH|DOMINANT") — a MULTI-field bound value
         // (binding.value is a pipe-joined field list, e.g. one CSV column
         // per age band for the same year/sex — same pipe convention
@@ -7774,6 +7850,26 @@
     }
 
     _rebuildActiveFeatures() {
+      // An AGGREGATE CATEGORICAL choropleth filters the RECORDS of each
+      // polygon (as its .filter() does before the join), then sums them —
+      // not the polygons by their first record
+      if (isAggregatedCategoricalChoropleth(this)) {
+        const expr = this._runtimeFilterExpr;
+        const clauses = Array.from(this.facetFilters.entries());
+        if (!expr && !clauses.length) { this._activeFeatures = null; return; }
+        const pred = expr ? flatFilterPredicate(String(expr)) : null;
+        this._activeFeatures = this.features.map(f => {
+          const rows = f.properties && f.properties[AGGREGATED_ROWS];
+          if (!rows) return f;
+          const kept = rows.filter(r => (!pred || pred(r)) && clauses.every(([field, clause]) => matchesFacetClause(r[field], clause)));
+          const properties = kept.length ? Object.assign({}, kept[0]) : {};
+          if (kept.length) Object.defineProperty(properties, AGGREGATED_ROWS, { value: kept });
+          const out = { type: 'Feature', geometry: f.geometry, properties };
+          if (f._flatAreaKm2 !== undefined) out._flatAreaKm2 = f._flatAreaKm2;
+          return out;
+        });
+        return;
+      }
       // Base set: this.features narrowed by the runtime WHERE-filter
       // (changeThemeStyle's own mechanism, see _runtimeFilterExpr's own
       // comment) if one is active — reusing applyWhereFilter, the SAME
@@ -8470,8 +8566,11 @@
         // unlike CHOROPLETH, there's no per-feature classification here.
         // flat puts fillopacity into the shape's fill-opacity only
         // (maptheme.js 13407, 14071-14078): the outline stays opaque
-        getFillColor: filled ? [...hexOrNamedToRgb(raw).slice(0, 3), Math.round(255 * (styleNum(this.style.fillopacity) || 1))] : [0, 0, 0, 0],
-        getLineColor: this.style.linecolor ? hexOrNamedToRgb(styleLineColor(this.style.linecolor)) : [130, 130, 130],
+        // (a fill color's own alpha — rgba(…, 0.5) — times fillopacity)
+        getFillColor: filled ? [...hexOrNamedToRgb(raw).slice(0, 3), Math.round(255 * cssColorAlpha(raw) * (styleNum(this.style.fillopacity) || 1))] : [0, 0, 0, 0],
+        getLineColor: this.style.linecolor
+          ? withAlpha(hexOrNamedToRgb(styleLineColor(this.style.linecolor)), cssColorAlpha(styleLineColor(this.style.linecolor)))
+          : [130, 130, 130],
         lineWidthMinPixels: styleNum(this.style.linewidth) || 1,
         // Confirmed live (2026-09-21, deck.gl v9.4/MapLibre-globe upgrade):
         // this layer's fill rendered with a moire/hatching pattern of
@@ -8540,9 +8639,10 @@
     // — plain/PERCENTOFMEAN/DEVIATION); or COMPOSECOLOR's per-polygon
     // BLEND across the same piped fields (_resolveComposedColor — no
     // single winning class, so no `cat`/tooltip chart line, just the
-    // blended color directly). CATEGORICAL choropleths (exact-match,
-    // single field) aren't implemented — no ported config uses that
-    // combination yet. Geometry + properties are already the joined
+    // blended color directly); AGGREGATE CATEGORICAL on one field — the
+    // dominant category of each polygon's records (aggregatedCategoricalClass).
+    // A plain CATEGORICAL choropleth (exact match of one row's value) is not
+    // implemented. Geometry + properties are already the joined
     // FeatureCollection from joinChoroplethFeatures. `zoom` is only used
     // for style.fillopacity:"auto" (see resolveAutoFillOpacity) — every
     // other branch here is zoom-independent.
@@ -8565,7 +8665,37 @@
       // DOPACITY/COMPOSECOLOR branches.
       const dopacityActive = !isComposeColor &&
         (this.flags.has('DOPACITY') || this.flags.has('DOPACITYMIN') || this.flags.has('DOPACITYMAX') || this.flags.has('DOPACITYMINMAX'));
+      // AGGREGATE CATEGORICAL: every polygon's parts and dominant class
+      // (aggregatedCategoricalClass), the biggest part per class over all
+      // polygons for the opacity (flat's nMaxA)
+      const aggCat = isAggregatedCategoricalChoropleth(this) && this.categoryIndexByLabel;
+      let aggOf = null, aggMaxA = null;
+      if (aggCat) {
+        const nCats = this.categoryLabels.length;
+        aggOf = new Map();
+        aggMaxA = new Array(nCats).fill(0);
+        source.forEach(f => {
+          const rows = f.properties && f.properties[AGGREGATED_ROWS];
+          if (!rows) return;
+          const agg = aggregatedCategoricalClass(rows, this.binding, this.flags, this.categoryIndexByLabel, nCats);
+          if (!agg) return;
+          aggOf.set(f, agg);
+          agg.parts.forEach((v, i) => { if (v > aggMaxA[i]) aggMaxA[i] = v; });
+        });
+      }
       const data = source.map(f => {
+        if (aggCat) {
+          const agg = aggOf.get(f);
+          return {
+            type: 'Feature',
+            geometry: f.geometry,
+            properties: {
+              // no part above 0: no item in flat, not painted
+              value: agg ? agg.value : undefined, raw: agg ? f.properties : {}, cat: agg ? agg.index : null,
+              dopacityAlpha: agg && dopacityActive ? dominantDopacityAlpha(this.style, this.flags, agg.value, aggMaxA[agg.index]) : null
+            }
+          };
+        }
         if (isComposeColor) {
           return {
             type: 'Feature',
@@ -8604,7 +8734,14 @@
       // evidence mode "isolate", the default (7715) — or grayed with
       // style.evidence "isolate_gray". ("highlight", flat's highlight list,
       // is shown grayed too here.) COMPOSECOLOR has no classes.
-      const lineRgb = this.style.linecolor ? hexOrNamedToRgb(styleLineColor(this.style.linecolor)) : [255, 255, 255];
+      // linecolor "none": no outline; a class color "none" (an explicit
+      // colorscheme list) leaves its polygons unpainted, an rgba() class
+      // color keeps its alpha — as flat's SVG fill does
+      const lineColorRaw = this.style.linecolor ? styleLineColor(this.style.linecolor) : null;
+      const lineRgb = lineColorRaw ? withAlpha(hexOrNamedToRgb(lineColorRaw), cssColorAlpha(lineColorRaw)) : [255, 255, 255];
+      const cs = this.style.colorscheme;
+      const classAlpha = Array.isArray(cs) && cs.length && !/^\d+$/.test(String(cs[0])) ? cs.map(cssColorAlpha) : null;
+      const alphaOfClass = i => (classAlpha && i != null && classAlpha[i] != null ? classAlpha[i] : 1);
       const evidenceMode = String(this.style.evidence || 'isolate');
       const unmarkedEvidence = d => {
         if (!this._markedClasses.size || this._onMarksChanged || this._markedClasses.has(d.properties.cat)) return null;
@@ -8624,7 +8761,8 @@
           const evidence = unmarkedEvidence(d);
           if (evidence === 'hide') return [0, 0, 0, 0];
           if (evidence === 'gray') return [...grayOf(rgb), 90];
-          return d.properties.dopacityAlpha != null ? [...rgb, Math.round(d.properties.dopacityAlpha * 255)] : rgb;
+          const a = alphaOfClass(d.properties.cat);
+          return d.properties.dopacityAlpha != null ? [...rgb.slice(0, 3), Math.round(d.properties.dopacityAlpha * a * 255)] : withAlpha(rgb, a);
         },
         // a per-polygon accessor only while a class is isolated
         getLineColor: this._markedClasses.size && !this._onMarksChanged && evidenceMode === 'isolate'
@@ -9568,6 +9706,14 @@
       });
 
       const doRelocate = this.flags.has('RELOCATE');
+      // SEQUENCE: flat's AGGREGATE cell is ONE chart with a part per
+      // category (RELOCATE only moves it to the records' mean position) —
+      // every category of a cell, single records included, in one group
+      if (flatFlag(this.flags, 'SEQUENCE') && this.flags.has('CATEGORICAL')) {
+        const groups = groupCoLocated(clusterFeatures.concat(individual), effectiveZoom, this._clusterRadiusPx,
+          this.categoryLabels ? this.categoryLabels.length : 1, this.flags, !doRelocate);
+        return { individual: [], groups };
+      }
       // without RELOCATE a cell's item already sits at the cell center
       // (aggregateOnGrid)
       const groups = doRelocate ? this._groupCoLocated(clusterFeatures, effectiveZoom) : clusterFeatures.map(f => {
@@ -9832,6 +9978,9 @@
         if (userLayers) return layers.concat(userLayers);
       }
       if (this.flags.has('LABEL')) return layers.concat(this._buildLabelChartLayers(combined, zoom, liveZoom, sizeValueOf));
+      if (flatFlag(this.flags, 'SEQUENCE') && this.flags.has('CATEGORICAL') && this.flags.has('AGGREGATE')) {
+        return layers.concat(this._buildSequenceChartLayers(combined, zoom, liveZoom));
+      }
       const fillOpacity = styleNum(this.style.fillopacity) || 0.85;
       // .style({linecolor, linewidth}) — an individual icon's own border,
       // see _buildSingleIcon's own comment. Real ixmaps-flat symbol
@@ -10144,6 +10293,164 @@
       return layers;
     }
 
+    // flat's nAllMaxValue for a SEQUENCE chart (maptheme.js 13211-13215):
+    // the biggest category part of any chart at this aggregation — over
+    // the whole dataset, not the view; cached per zoom
+    _sequenceMaxValue(zoom) {
+      if (this._seqMaxFor !== this._clusterIndices) { this._seqMaxFor = this._clusterIndices; this._seqMax = new Map(); }
+      if (!this._seqMax.has(zoom)) {
+        const { groups } = this._computeAggregatedItems([-180, -90, 180, 90], zoom);
+        let max = 0;
+        groups.forEach(g => g.properties.counts.forEach(c => { if (c > max) max = c; }));
+        this._seqMax.set(zoom, max || 1);
+      }
+      return this._seqMax.get(zoom);
+    }
+
+    // CHART|SYMBOL|SEQUENCE on an AGGREGATE CATEGORICAL theme: each cell is
+    // one chart of a symbol per category part (sequenceLayout), as flat's
+    // SYMBOL branch draws it (maptheme.js 21122-22400):
+    //  - part radius: max radius · (v / max value)^(1/sizepow), max value =
+    //    normalsizevalue, else the biggest part of any chart (21793)
+    //  - circle in the category color at fillopacity, stroked in linecolor
+    //    linewidth · unit · min(2r / max radius, 0.2) wide (21966)
+    //  - GLOW (and AURA): with SORT only around the first part, else around
+    //    every part (22009)
+    //  - marked legend classes: the other parts hidden, the marked ones
+    //    back on the center (14339-14420, evidence "isolate"); with
+    //    "isolate_gray" the others dimmed
+    //  - STAR: the center part drawn last, on top of its satellites (23145)
+    //  - VALUES: each part's value (COUNT: its records; valuefield: the class name)
+    //  - align / offsets as the SYMBOL branch: half size the normal radius
+    // A part's pick object carries its chart's properties (tooltip).
+    _buildSequenceChartLayers(charts, zoom, liveZoom) {
+      const st = this.style;
+      const seqMax = this._sequenceMaxValue(zoom);
+      const partRadius = v => valueRadius(v, liveZoom, st, this.mapOptions, this.flags, seqMax);
+      const unit = objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(st.scale) || 1);
+      const normalR = NORMAL_RADIUS_PX * unit;
+      const nCats = this.categoryLabels ? this.categoryLabels.length : 1;
+      const marking = this._markedClasses.size && !this._onMarksChanged;
+      const gray = marking && String(st.evidence || 'isolate') === 'isolate_gray';
+      const sorted = [...this.flags].some(f => /\bSORT\b/.test(f));
+      const fillOpacity = styleNum(st.fillopacity) || 0.85;
+      const borderRgb = st.linecolor && styleLineColor(st.linecolor) !== 'none' ? hexOrNamedToRgb(styleLineColor(st.linecolor)) : null;
+      const lineWidth = styleNum(st.linewidth) || 1;
+      const symbols = Array.isArray(st.symbols) ? st.symbols : null;
+      const shapeOf = i => { const sh = symbols && (symbols[i] || symbols[0]); return /^(circle|square|diamond|triangle)$/.test(sh) ? sh : 'circle'; };
+      const colorOf = i => this.categoryColorsRgb[i] || [128, 128, 128];
+      const parts = [], glows = [];
+      for (const d of charts) {
+        let layout = sequenceLayout(d.properties.counts, this.flags, partRadius, { maxRadius: normalR, maxValue: seqMax, nParts: nCats, rangeScale: styleNum(st.rangescale) || 0 });
+        if (!layout.length) continue;
+        // GLOW belongs to the first part (sorted) or to every part, and
+        // hides with it when its class is not marked
+        const glowParts = new Set(sorted ? [layout[0].i] : layout.map(p => p.i));
+        if (marking && !gray) {
+          layout = layout.filter(p => this._markedClasses.has(p.i)).map(p => ({ ...p, x: 0, y: 0 }));
+          if (!layout.length) continue;
+        }
+        // the chart's own ptNull.y: the last part's radius + 5 units (23204)
+        d._seqLast = layout[layout.length - 1].r;
+        const items = layout.map(p => {
+          const item = { geometry: d.geometry, properties: d.properties, chart: d, part: p };
+          if (glowParts.has(p.i)) glows.push(item);
+          return item;
+        });
+        // STAR: the first part (its center) is put on top at the end (23145)
+        if (flatFlag(this.flags, 'STAR') && items.length > 1) items.push(items.shift());
+        parts.push(...items);
+      }
+      const alignOf = this._chartAlignFn(liveZoom, d => (d.chart || d)._seqLast || 0);
+      const offsetOf = item => { const o = alignOf(item.chart); return [o[0] + item.part.x, o[1] + item.part.y]; };
+      const alphaOf = item => (gray && !this._markedClasses.has(item.part.i) ? DIMMED_ICON_ALPHA : 255);
+      const layers = [];
+      if (glows.length && this.flags.has('GLOW') && !glowHiddenByScale(st, liveZoom)) {
+        layers.push(new IconLayer({
+          id: `ix-glow-${this.name}-g${this._iconGeneration}`,
+          data: glows, pickable: false,
+          getPosition: d => d.geometry.coordinates,
+          getIcon: d => this._getGlowIcon(colorOf(d.part.i)),
+          getSize: d => d.part.r * 11,
+          getPixelOffset: offsetOf,
+          getColor: d => [255, 255, 255, alphaOf(d)],
+          sizeUnits: 'pixels', billboard: true,
+          parameters: ICON_LAYER_GLOBE_PARAMETERS
+        }));
+      } else if (glows.length && this.flags.has('AURA') && !glowHiddenByScale(st, liveZoom)) {
+        layers.push(new IconLayer({
+          id: `ix-aura-${this.name}-g${this._iconGeneration}`,
+          data: glows, pickable: false,
+          getPosition: d => d.geometry.coordinates,
+          getIcon: d => this._buildSingleIcon(borderRgb || colorOf(d.part.i), 0.3, 'circle', null, 0),
+          getSize: d => d.part.r * 2 * 1.3,
+          getPixelOffset: offsetOf,
+          getColor: d => [255, 255, 255, alphaOf(d)],
+          sizeUnits: 'pixels', billboard: true,
+          parameters: ICON_LAYER_GLOBE_PARAMETERS
+        }));
+      }
+      layers.push(new IconLayer({
+        id: `ix-bubbles-${this.name}-g${this._iconGeneration}`,
+        data: parts, pickable: true,
+        getPosition: d => d.geometry.coordinates,
+        // the stroke, in the icon raster's pixels (the icon is drawn at 2r)
+        getIcon: d => this._buildSingleIcon(colorOf(d.part.i), fillOpacity, shapeOf(d.part.i), borderRgb,
+          borderRgb ? Math.round(lineWidth * unit * Math.min(2 * d.part.r / normalR, 0.2) * BUBBLE_ICON_SIZE / Math.max(1, 2 * d.part.r) * 4) / 4 : 0),
+        getSize: d => d.part.r * 2,
+        getPixelOffset: offsetOf,
+        getColor: d => [255, 255, 255, alphaOf(d)],
+        sizeUnits: 'pixels', billboard: true,
+        parameters: ICON_LAYER_GLOBE_PARAMETERS
+      }));
+      // VALUES on each part (maptheme.js 22188-22250): the part's value — with
+      // COUNT its record count, with valuefield on the categorical field the
+      // class name — formatted with valuedecimals (else none) plus the unit;
+      // font min(1, 3.2 / L) · r · valuescale, L the length of the theme's
+      // biggest value text (szMaxText), normal weight, in valuecolor /
+      // textcolor, else ChartColors.textColor of the part color
+      if (this.flags.has('VALUES') && !valuesHiddenByScale(st, zoom)) {
+        const valueScale = styleNum(st.valuescale) || 1;
+        const { noBreaks } = this._valueTextOpts();
+        const units = st.units ? String(st.units) : '';
+        const unit = units ? (units[0] === '.' ? '' : ' ') + units : '';
+        const unitText = unit.length <= 5 ? unit : '';
+        const dec = styleNum(st.valuedecimals) || 0;
+        const fmt = v => flatGroupedValue(v, dec, noBreaks) + unitText;
+        const maxLen = fmt(seqMax).length;
+        const textOverride = st.valuecolor || st.textcolor;
+        const counting = flatFlag(this.flags, 'COUNT');
+        const labels = [];
+        parts.forEach(d => {
+          const rec = this._categoryValueRecord(d.part.i);
+          const name = rec ? String(rec[st.valuefield]) : null;
+          const t = counting && d.properties.recordCounts ? d.properties.recordCounts[d.part.i] : d.part.v;
+          const text = name != null ? name : fmt(t);
+          const L = Math.max((name != null ? name.length : 0) + 1, maxLen);
+          const fontSize = Math.min(1, 3.2 / L) * d.part.r * valueScale;
+          if (fontSize > VALUES_MIN_FONT_PX) {
+            labels.push({ geometry: d.geometry, text, fontSize, pixelOffset: offsetOf(d), alpha: alphaOf(d),
+              color: textOverride ? hexOrNamedToRgb(textOverride) : flatChartTextRgb(colorOf(d.part.i)) });
+          }
+        });
+        if (labels.length) {
+          layers.push(new TextLayer({
+            id: `ix-cluster-values-${this.name}`,
+            data: labels, pickable: false,
+            getPosition: d => d.geometry.coordinates,
+            getText: d => d.text,
+            getSize: d => d.fontSize,
+            getColor: d => [...d.color.slice(0, 3), d.alpha],
+            getPixelOffset: d => d.pixelOffset,
+            sizeUnits: 'pixels', fontFamily: 'arial', fontWeight: 'normal',
+            characterSet: 'auto',
+            getTextAnchor: 'middle', getAlignmentBaseline: 'center'
+          }));
+        }
+      }
+      return layers;
+    }
+
     // flat's chart position for this build (flatChartAlignOffset): a
     // function item → pixel offset, the same for every part of one chart
     // (symbol, glow, shadow, box, title, value text). unit is flat's
@@ -10387,6 +10694,23 @@
     }
   }
 
+  // a color's own opacity, 0..1, as SVG paints it in flat: "none" (SVG's
+  // no paint — a polygon with only its outline, or a class not painted)
+  // 0, rgba()/hsla() its alpha, #rrggbbaa / #rgba its alpha digits, else 1
+  function cssColorAlpha(v) {
+    if (typeof v !== 'string') return 1;
+    const c = v.trim().toLowerCase();
+    if (c === 'none' || c === 'transparent') return 0;
+    const m = c.match(/^(?:rgba|hsla)\([^)]*,\s*([\d.]+%?)\s*\)$/) || c.match(/^(?:rgb|hsl)a?\([^)]*\/\s*([\d.]+%?)\s*\)$/);
+    if (m) return Math.max(0, Math.min(1, m[1].endsWith('%') ? parseFloat(m[1]) / 100 : parseFloat(m[1])));
+    const h = c.match(/^#(?:[0-9a-f]{3}([0-9a-f])|[0-9a-f]{6}([0-9a-f]{2}))$/);
+    if (h) return parseInt(h[1] ? h[1] + h[1] : h[2], 16) / 255;
+    return 1;
+  }
+  // [r, g, b] with an alpha 0..1 — the plain [r, g, b] (opaque) when it is 1
+  function withAlpha(rgb, a) {
+    return a >= 1 ? rgb.slice(0, 3) : [...rgb.slice(0, 3), Math.round(255 * Math.max(0, a))];
+  }
   function hexOrNamedToRgb(v) {
     const NAMED = { gray: [128, 128, 128], grey: [128, 128, 128], black: [0, 0, 0], white: [255, 255, 255] };
     return parseCssColor(v) || NAMED[v] || [130, 130, 130];
@@ -10408,6 +10732,169 @@
   function escapeHtml(s) {
     return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
   }
+  // a legend's row labels as HTML: the page's .style({label}) as given,
+  // values from the data escaped
+  function legendRowLabels(rt) {
+    const display = rt.categoryDisplayLabels;
+    if (display && display !== rt.categoryLabels) return display;
+    return (rt.categoryLabels || []).map(v => escapeHtml(v));
+  }
+
+  // ===============================================================
+  // FLAT-COMPATIBILITY API — what a page written for ixmaps-flat calls on
+  // the global `ixmaps` object; it acts on the last built map:
+  //  - page hooks gl calls: htmlgui_onNewTheme, htmlgui_onDrawTheme,
+  //    htmlgui_onZoomAndPan
+  //  - the map handle ixmaps.map() and its methods (MAP_HANDLE_METHODS)
+  //  - view: getZoom, getCenter, getMapTypeId, getBoundingBox
+  //  - themes: getThemeObj (flat's theme object, with its data table and
+  //    the items on the map), getThemeDefinitionObj, getThemes,
+  //    changeThemeStyle / removeTheme / setBasemapOpacity (map name first),
+  //    refreshTheme, markThemeClass / unmarkThemeClass
+  //  - data: ixmaps.data (facets: getFacets, showFacets, …), the
+  //    embeddedSVG.window tables (setExternalData is with the data loading)
+  //  - projects: getProjectString, setProjectJSON, loadProject
+  //  - page UI: setTitle, setTitleBox, formatValue; message,
+  //    filterThemeItems and highlightThemeItems are accepted but not ported
+  // The object itself is assembled at the end of this section (global.ixmaps).
+  // ===============================================================
+
+  // flat's page hook ixmaps.htmlgui_onNewTheme(szId), called when a theme
+  // is created (maptheme.js 927) — with the theme's id (its name)
+  function themeIdOf(rt) {
+    return (rt.style && rt.style.name) || (rt.meta && rt.meta.name) || rt.name;
+  }
+  function notifyNewTheme(rt) {
+    const hook = pageIxmaps() && pageIxmaps().htmlgui_onNewTheme;
+    if (typeof hook !== 'function') return;
+    try { hook.call(global.ixmaps, themeIdOf(rt)); } catch (e) { console.error('[ixmaps-gl] htmlgui_onNewTheme:', e); }
+  }
+
+  // flat's ixmaps.map() — the running map's handle (htmlgui.js 173ff,
+  // htmlgui_flat.js). Its methods act on the last built map; called while
+  // the map is still building, they run once it is ready.
+  const MAP_HANDLE_METHODS = ['replace', 'add', 'remove', 'removeTheme', 'replaceTheme', 'changeThemeStyle', 'setThemeStyle',
+    'refreshTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible'];
+  const _mapHandle = {};
+  for (const m of MAP_HANDLE_METHODS) {
+    _mapHandle[m] = (...args) => {
+      if (_lastMapApi) { const r = _lastMapApi[m](...args); return r === _lastMapApi ? _mapHandle : r; }
+      _mapReady.then(api => api[m](...args));
+      return _mapHandle;
+    };
+  }
+  _mapHandle.getZoom = () => (_lastMapApi ? _lastMapApi.getZoom() : undefined);
+  _mapHandle.getThemeObj = id => getThemeObj(id);
+  function mapHandle() { return _mapHandle; }
+
+  // flat's ixmaps.formatValue(value, precision, flag) (ui/js/tools/format.js),
+  // which user chart scripts call: thousands separated by "." (BLANK: a
+  // space), the decimals after "," (BLANK: "."), CEIL / FLOOR rounding
+  function flatFormatPart(nPart, szLeading) {
+    szLeading = szLeading || '';
+    let szPart = '';
+    if (nPart < 100) szPart += szLeading;
+    if (nPart < 10) szPart += szLeading;
+    if (nPart === 0) szPart += szLeading;
+    else szPart += String(nPart);
+    return szPart;
+  }
+  function flatFormatValue(nValue, nPrecision, szFlag) {
+    nValue = Number(nValue);
+    if (!isFinite(nValue) || !isFinite(nPrecision)) return String(nValue);
+    if (nValue === 0) return String(nValue);
+    if (nValue > 1000000000000 || nValue < -1000000000000) return String(nValue);
+    nPrecision = Math.max(0, nPrecision || 0);
+    if (nValue > 0.0000001 && nPrecision > 0) {
+      while (Number(nValue.toFixed(nPrecision - 1)) === 0) nPrecision++;
+    }
+    let v = Number(nValue.toFixed(nPrecision + 1));
+    const clip = Math.pow(10, nPrecision);
+    if (szFlag && /CEIL/.test(szFlag)) v = Math.ceil(v * clip) / clip;
+    else if (szFlag && /FLOOR/.test(szFlag)) v = Math.floor(v * clip) / clip;
+    else v = Math.round(v * clip) / clip;
+    let szDecimals = String(v);
+    if (/\./.test(szDecimals)) {
+      szDecimals = szDecimals.split('.')[1];
+      while (szDecimals.length < nPrecision) szDecimals += '0';
+    } else szDecimals = '';
+    let szReturn = v < 0 ? '-' : '';
+    let szLeading = '';
+    let n = Math.floor(Math.abs(v));
+    if (!szFlag || !/NOBREAKS/.test(szFlag)) {
+      let nClip = 1000;
+      while (n > nClip) nClip *= 1000;
+      nClip /= 1000;
+      let szBreak = ' ';
+      while (nClip >= 1000) {
+        const nPart = Math.floor(n / nClip);
+        szReturn += flatFormatPart(nPart, szLeading);
+        n = n % nClip;
+        nClip /= 1000;
+        if (nPart) {
+          szLeading = '0';
+          szBreak = szFlag && /SPACE/.test(szFlag) ? '<span style="font-size:0.5em;">&nbsp;</span>' : szFlag && /BLANK/.test(szFlag) ? '&nbsp;' : '.';
+        }
+        szReturn += szBreak;
+      }
+    }
+    szReturn += flatFormatPart(n, szLeading);
+    if (!szReturn.length || szReturn === '-') szReturn += '0';
+    if (szDecimals.length && szDecimals !== '00') szReturn += (szFlag && /BLANK/.test(szFlag) ? '.' : ',') + szDecimals;
+    return szReturn;
+  }
+
+  function getZoom() { return _lastMapApi ? _lastMapApi.getZoom() : undefined; }
+
+  // flat's ixmaps.getBoundingBox() (htmlgui_sync_Leaflet_VT.js
+  // htmlMap_getBounds): [{lat, lng} south-west, {lat, lng} north-east] of
+  // the view, latitude clamped to ±85.05, longitude not capped. Set by the
+  // last build(): a broker (data.type "ext") is called while its map is
+  // still building, so until the MapLibre map exists the bounds come from
+  // the requested view and the container size (MapLibre's 512 px tiles).
+  let _boundsSource = null;
+  function viewBounds(lat, lng, mlZoom, width, height) {
+    const world = 512 * Math.pow(2, mlZoom);
+    const x = (lng + 180) / 360 * world;
+    const s = Math.sin(Math.max(-85.05, Math.min(85.05, lat)) * Math.PI / 180);
+    const y = (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * world;
+    const lngAt = px => px / world * 360 - 180;
+    const latAt = py => Math.atan(Math.sinh(Math.PI * (1 - 2 * py / world))) * 180 / Math.PI;
+    return [{ lat: latAt(y + height / 2), lng: lngAt(x - width / 2) }, { lat: latAt(y - height / 2), lng: lngAt(x + width / 2) }];
+  }
+  function getBoundingBox() {
+    const b = _boundsSource ? _boundsSource() : null;
+    if (!b) return null;
+    return [{ lat: Math.max(b[0].lat, -85.05), lng: b[0].lng }, { lat: Math.min(b[1].lat, 85.05), lng: b[1].lng }];
+  }
+
+  // flat's ixmaps.setTitle(html) / setTitleBox(text, color) (htmlgui.js
+  // 1311-1331): a message line over the last built map, same markup as
+  // flat's default (legend not aligned left); '' clears it.
+  let _titleHost = null;
+  function setTitle(szTitle) {
+    if (!_titleHost) return;
+    let box = _titleHost.querySelector(':scope > .ixmaps-gl-title');
+    if (!box) {
+      box = document.createElement('div');
+      box.className = 'ixmaps-gl-title';
+      box.style.cssText = 'position:absolute;top:11px;left:0;z-index:3;pointer-events:none;';
+      _titleHost.appendChild(box);
+    }
+    box.innerHTML = szTitle
+      ? "<div style='position:relative;left:100px;top:2px;font-style:arial,helvetica;font-size:22px'>" + szTitle + '</div>'
+      : '';
+  }
+  function setTitleBox(szTitle, szColor) {
+    setTitle("<span style='display:inline-flex;align-items:center;height:38px;box-sizing:border-box;padding:0 12px;border:1px solid #46494c;border-radius:8px;font-size:14px;font-family:courier new,Raleway,arial,helvetica;background:" + (szColor || 'rgba(255,255,255,0.95)') + ';color:' + (szColor ? '#fff' : '#222') + "'>" + szTitle + '</span>');
+  }
+  // flat's ixmaps.refreshTheme(szId): reloads the theme's data on the last
+  // built map (a broker is called again) — see engineApi.refreshTheme
+  function refreshTheme(szId) {
+    if (!_lastMapApi || !_lastMapApi.refreshTheme) return;
+    _lastMapApi.refreshTheme(szId).catch(err => console.error('[ixmaps-gl] refreshTheme:', err));
+  }
+
 
   // GL-PORT COMPAT: real ixmaps-flat's ixmaps.getThemeObj(szId) — a
   // global lookup by theme id, independent of which map built it — looked
@@ -10415,19 +10902,130 @@
   // definition wins" caveat). Returns null for an unknown id, same as the
   // real engine, rather than throwing.
   function getThemeObj(szId) {
-    const rt = _globalThemeRegistry.get(szId);
+    // no id: flat's current theme — here the one a page's facets were
+    // built for (its own facet script sets ixmaps.filterThemeId), else the
+    // last chart / choropleth theme
+    let rt = szId != null ? _globalThemeRegistry.get(szId) : null;
+    if (szId == null) {
+      const pid = pageIxmaps() && pageIxmaps().filterThemeId;
+      rt = (pid != null && _globalThemeRegistry.get(pid))
+        || [..._globalThemeRegistry.values()].reverse().find(r => r.flags.has('CHART') || r.flags.has('CHOROPLETH')) || null;
+    }
     if (!rt) return null;
+    const rgbHex = c => '#' + c.slice(0, 3).map(v => Math.round(v).toString(16).padStart(2, '0')).join('');
+    let items = null;
+    const onMap = () => items || (items = themeItemsOnMap(rt));
     return {
-      szId: rt.name,
+      // flat's theme id (style.name) — a .layer() name may be shared by
+      // several themes of a page
+      szId: themeIdOf(rt),
       szName: rt.name,
-      szFilter: rt._filterExpr || '',
+      // the filter in force: a runtime one (changeThemeStyle "filter")
+      // replaces the definition's
+      szFilter: rt._runtimeFilterExpr || rt._filterExpr || '',
       szFlag: Array.from(rt.flags).join('|'),
       // flat's fVisible is false for a FEATURE theme outside its
       // featureupper/featurelower scales too (maptheme.js 2609-2611) — a
       // broker reads it to skip refreshing a hidden theme
-      fVisible: !rt._hidden && !(_lastMapApi && _lastMapApi.map && themeHiddenByScale(rt.flags, rt.style, _lastMapApi.map.getZoom()))
+      fVisible: !rt._hidden && !(_lastMapApi && _lastMapApi.map && themeHiddenByScale(rt.flags, rt.style, _lastMapApi.map.getZoom())),
+      nScale: styleNum(rt.style.scale) || 1,
+      szUnits: rt.style.units || '',
+      // flat stores the unit with a leading space unless it starts with "."
+      szUnit: rt.style.units ? (String(rt.style.units)[0] === '.' ? '' : ' ') + rt.style.units : '',
+      szTitleField: rt.binding.title || null,
+      szFieldsA: rt.binding.value ? String(rt.binding.value).split('|') : [],
+      szSizeField: rt.binding.size || null,
+      // the classes, as flat's facet / legend scripts read them:
+      // colorScheme by class, nStringToValueA value → class + 1,
+      // szLabelA / szValuesA the style's label / values lists
+      colorScheme: (rt.categoryColorsRgb || []).map(rgbHex),
+      nStringToValueA: rt.categoryLabels ? Object.fromEntries(rt.categoryLabels.map((v, i) => [v, i + 1])) : {},
+      szLabelA: Array.isArray(rt.style.label) ? rt.style.label.map(String) : (rt.categoryDisplayLabels || null),
+      szValuesA: Array.isArray(rt.style.values) ? rt.style.values.map(String) : null,
+      partsA: rt.partsA || [],
+      // flat's own data surface, as a page's own facet / list scripts
+      // (flat's ui/js/tools facet.js, list.js) read it: the theme's data
+      // table (objTheme.dbTable/dbFields/dbRecords — records as arrays in
+      // field order) and the items on the map (indexA → itemA[i].dbIndexA,
+      // the records of each item). Here one item holds every record of
+      // the theme within the current view (shown, in scale, facet filters
+      // applied) — computed when read
+      get objTheme() { return themeDbTable(rt); },
+      // computed once per theme object (a page's loop reads itemA per record)
+      get indexA() { return onMap().indexA; },
+      get itemA() { return onMap().itemA; }
     };
   }
+  const _warnedOnce = new Set();
+  function warnOnce(key, msg) { if (!_warnedOnce.has(key)) { _warnedOnce.add(key); console.info(msg); } }
+  // the theme's records as flat's dbFields/dbRecords (cached per data)
+  function themeDbTable(rt) {
+    const features = rt.features || [];
+    if (rt._dbTableFor === features) return rt._dbTable;
+    const rowOf = f => (f.properties && f.properties.raw) || f.properties || {};
+    const names = [];
+    const seen = new Set();
+    for (const f of features.slice(0, 1000)) for (const k of Object.keys(rowOf(f))) if (!seen.has(k)) { seen.add(k); names.push(k); }
+    const indexOf = new Map();
+    const dbRecords = features.map((f, i) => { indexOf.set(f, i); const row = rowOf(f); return names.map(k => (row[k] == null ? '' : row[k])); });
+    rt._dbTableFor = features;
+    rt._dbIndexOf = indexOf;
+    const dbFields = names.map(id => ({ id, typ: 0, width: 16, decimals: 0 }));
+    // dbTable: data.js Table's own table header ({records, fields} counts)
+    rt._dbTable = { dbTable: { records: dbRecords.length, fields: dbFields.length }, dbFields, dbRecords };
+    return rt._dbTable;
+  }
+  // the records on the map now: none for a hidden / out of scale theme,
+  // else the (facet-filtered) records within the view
+  function themeItemsOnMap(rt) {
+    themeDbTable(rt);
+    const map = _lastMapApi && _lastMapApi.map;
+    const shown = map && !rt._hidden && !themeHiddenByScale(rt.flags, rt.style, map.getZoom());
+    if (!shown) return { indexA: [], itemA: {} };
+    const b = map.getBounds();
+    const bbox = [b.getWest(), b.getSouth(), b.getEast(), b.getNorth()];
+    const dbIndexA = [];
+    for (const f of (rt._activeFeatures || rt.features || [])) {
+      const g = f.geometry;
+      if (g && g.type === 'Point' && !pointInBbox(g, bbox)) continue;
+      const i = rt._dbIndexOf.get(f);
+      if (i != null) dbIndexA.push(i);
+    }
+    return { indexA: ['view'], itemA: { view: { dbIndexA } } };
+  }
+  // flat's ixmaps.getThemeDefinitionObj(szId): the theme's definition —
+  // type, style (sizefield/valuefield as flat names them), meta
+  function getThemeDefinitionObj(szId) {
+    const rt = _globalThemeRegistry.get(szId);
+    if (!rt) return null;
+    const style = Object.assign({}, rt.style);
+    if (rt.binding.size && !style.sizefield) style.sizefield = rt.binding.size;
+    if (rt.binding.title && !style.titlefield) style.titlefield = rt.binding.title;
+    style.type = rt.flags.typeString != null ? rt.flags.typeString : [...rt.flags].join('|');
+    const data = Object.assign({}, rt._definition && rt._definition.data);
+    if (!data.name) data.name = themeDataName(rt);
+    return { layer: rt.name, type: style.type, field: rt.binding.value, data, style, meta: Object.assign({}, rt.meta) };
+  }
+  // a theme's data table name — flat keeps named data tables in its map
+  // window (ixmaps.embeddedSVG.window[name], read by a page's own list
+  // scripts): the .data({name}) given, else one made from the theme id
+  function themeDataName(rt) {
+    const d = rt._definition && rt._definition.data;
+    return (d && d.name) || ('themeData_' + String(themeIdOf(rt)).replace(/\W/g, '_'));
+  }
+  // flat's ixmaps.embeddedSVG.window: here only its named data tables, as
+  // data.js Table objects {table, fields, records} of the themes' data
+  const embeddedSVG = {
+    window: new Proxy({}, {
+      get(target, key) {
+        if (typeof key !== 'string') return undefined;
+        const rt = [...new Set(_globalThemeRegistry.values())].find(r => themeDataName(r) === key);
+        if (!rt) return undefined;
+        const t = themeDbTable(rt);
+        return { table: t.dbTable, fields: t.dbFields, records: t.dbRecords };
+      }
+    })
+  };
 
   // GL-PORT COMPAT: real ixmaps-flat's global ixmaps.markThemeClass(szId,
   // index)/unmarkThemeClass(szId, index) (htmlgui.js:2196/2208 — a bare
@@ -10444,7 +11042,15 @@
   // here instead of redrawing.
   function markThemeClass(szId, index) {
     const rt = _globalThemeRegistry.get(szId);
-    if (!rt) return;
+    if (rt) markRuntimeClass(rt, index);
+  }
+  function unmarkThemeClass(szId, index) {
+    const rt = _globalThemeRegistry.get(szId);
+    if (rt) unmarkRuntimeClass(rt, index);
+  }
+  // the legend's own rows mark their theme directly: its .layer() name
+  // may be shared with other themes of the page
+  function markRuntimeClass(rt, index) {
     // flat: a non-CHART theme (choropleth) marks ONE class at a time —
     // MapTheme.markClass unmarks the previous class first (maptheme.js
     // 14301-14305); chart themes can mark several
@@ -10454,9 +11060,7 @@
     if (rt._onMarksChanged) rt._onMarksChanged();
     else if (rt._triggerRedraw) rt._triggerRedraw();
   }
-  function unmarkThemeClass(szId, index) {
-    const rt = _globalThemeRegistry.get(szId);
-    if (!rt) return;
+  function unmarkRuntimeClass(rt, index) {
     rt._markedClasses.delete(index);
     if (rt._onMarksChanged) rt._onMarksChanged();
     else if (rt._triggerRedraw) rt._triggerRedraw();
@@ -10759,13 +11363,30 @@
     layer, Map: createMap, setExternalData: setExternalDataBridge, getThemeObj, data: ixmapsData,
     szResourceBase: ixmapsSzResourceBase, getProjectString, setProjectJSON, loadProject,
     markThemeClass, unmarkThemeClass, getBoundingBox, setTitle, setTitleBox, refreshTheme, formatValue: flatFormatValue,
-    map: mapHandle, getZoom,
+    map: mapHandle, getZoom, getThemeDefinitionObj, embeddedSVG,
+    // flat's theme list: the theme objects of every theme
+    getThemes: () => [...new Set(_globalThemeRegistry.values())].map(rt => getThemeObj(themeIdOf(rt))).filter(Boolean),
+    // flat shows a short status message on the map; not ported
+    message: () => {},
+    // flat's item highlight / item filter (facet histogram hovers): not ported
+    filterThemeItems: () => warnOnce('filterThemeItems', '[ixmaps-gl] ixmaps.filterThemeItems is not supported yet'),
+    highlightThemeItems: () => warnOnce('highlightThemeItems', '[ixmaps-gl] ixmaps.highlightThemeItems is not supported yet'),
+    // flat's global forms with the map name first (htmlgui.js) — the map
+    // handle's methods on the last built map
+    getCenter: () => (_lastMapApi && _lastMapApi.map ? _lastMapApi.map.getCenter() : null),
+    getMapTypeId: () => (_lastMapApi && _lastMapApi.getMapTypeId ? _lastMapApi.getMapTypeId() : ''),
+    changeThemeStyle: (szMap, szId, szStyle, szFlag) => _mapHandle.changeThemeStyle(szId, szStyle, szFlag),
+    removeTheme: (szMap, szId) => _mapHandle.remove(szId),
+    setBasemapOpacity: (szMap, nOpacity, szMode) => _mapHandle.setBasemapOpacity(nOpacity, szMode),
     // 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
     htmlgui_onZoomAndPan: function (nZoom) {},
+    // flat calls it when a theme is drawn (htmlgui.js) — pages wrap it
+    // (statistics, facets); called after each settled redraw, notifyRedraw
+    htmlgui_onDrawTheme: function (szId) {},
     // carried over from a page's own pre-load `ixmaps.validate = ...`
     validate: _preloadValidate
   };
@@ -10780,7 +11401,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, computeBubblePackLayout, isolatedBubblePackLayout,
+    IXMAPS_GL_VERSION, legendRowLabels, scaleDenom, cssColorAlpha, aggregatedCategoricalClass, dominantDopacityAlpha, isAggregatedCategoricalChoropleth, computeBubblePackLayout, isolatedBubblePackLayout, sequenceLayout,
     normalizeTheme, projectThemeToDefinition, withoutProjectCode, groupRecordCount, resolveBasemapStyleUrl, resolveMapTypeColor, LayerBuilder, LayerRuntime, typeStyleNumbers, styleNum,
     resolveScriptUrl, isTrustedScriptUrl, loadProcessingScript, loadBrokerData, applyBrokerThemePatch, makeBrokerTheme,
     equalIntervalBreaks, quantileBreaks, naturalBreaks, evenStrideSample, jenksBreakValues, partsFromBreakValues, resolvePartsClass,