ixmaps-gl 0.2.9 → 0.2.11

package/ixmaps-gl.js

@@ -82,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.9';
+  const IXMAPS_GL_VERSION = '0.2.11';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -308,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.24/dist/validate.mjs';
+  const VALIDATOR_URL_DEFAULT = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-grammar@v0.1.25/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;
@@ -1972,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,
@@ -2101,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;
@@ -2261,7 +2125,7 @@
   // edit it by hand; `npm run unit` fails when it drifts.
   // ---------------------------------------------------------------
   // <grammar:binding-aliases>
-  // generated from ixmaps-grammar 0.1.24 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
+  // generated from ixmaps-grammar 0.1.25 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
   const FLAT_BINDING_ALIASES = {
     "aggregation": "style.aggregationfield",
     "aggregationfield": "style.aggregationfield",
@@ -2323,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.24 — 5 meta keys
+  // generated from ixmaps-grammar 0.1.25 — 5 meta keys
   const FLAT_META_KEYS = ["description","name","snippet","title","tooltip"];
   // </grammar:meta-keys>
 
@@ -2779,6 +2643,949 @@
     };
   }
 
+  // ---------------------------------------------------------------
+  // flat's map attribution (ui/html/mappage.html #attribution-div): the
+  // page's text bottom left on the map; hidden while empty ("null" counts
+  // as empty, htmlgui_flat.js 522-526). Here a MapLibre control in the
+  // bottom-left corner, styled like MapLibre's own attribution (the
+  // basemap credit, bottom right — same line, same pill: white, 12px
+  // radius, 12px/20px Helvetica Neue, links rgba(0,0,0,0.75)).
+  // ---------------------------------------------------------------
+  let _attributionCss = false;
+  function createAttribution(map) {
+    if (!_attributionCss && typeof document !== 'undefined') {
+      _attributionCss = true;
+      const css = document.createElement('style');
+      css.textContent = '.ixmaps-gl-attribution a{color:rgba(0,0,0,0.75);text-decoration:none}'
+        + '.ixmaps-gl-attribution a:hover{color:inherit;text-decoration:underline}';
+      document.head.appendChild(css);
+    }
+    const box = document.createElement('div');
+    box.className = 'maplibregl-ctrl ixmaps-gl-attribution';
+    box.style.cssText = 'background:#fff;border-radius:12px;padding:2px 8px;min-height:20px;box-sizing:content-box;'
+      + 'font:12px/20px "Helvetica Neue",Arial,Helvetica,sans-serif;color:#000;display:none;';
+    map.addControl({ onAdd: () => box, onRemove: () => box.remove() }, 'bottom-left');
+    let text = '';
+    return {
+      set(t) {
+        text = t == null || t === 'null' ? '' : String(t);
+        box.innerHTML = text;
+        box.style.display = text ? 'block' : 'none';
+      },
+      get() { return text; }
+    };
+  }
+
+  // ---------------------------------------------------------------
+  // 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:440px;max-height:360px;overflow:auto;' +
+      'padding:0.6em 1.6em 0.6em 0.7em;font-size:1em;';
+
+    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: '1em', padding: '0.5em 0.7em', maxWidth: '440px' }, 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;
@@ -2813,7 +3620,13 @@
     // needs (a chart library, a user chart) — page code, like a <script>
     // tag; loaded in order before the layers (see loadRequiredScripts)
     require(url) { this._required = (this._required || []).concat(url); return this; }
-    attribution(a) { this._attributionText = a; return this; }
+    // flat's .attribution(text): the page's attribution, bottom left on the
+    // map (createAttribution) — also after the map is built
+    attribution(a) {
+      this._attributionText = a;
+      if (this._setAttribution) this._setAttribution(a);
+      return this;
+    }
     legend(html) { this._legendHtml = html; return this; }
     // GL-PORT COMPAT: real ixmaps-flat's map.layer(name) returns a NEW
     // per-layer builder for a .data()...define() chain on the LAYER
@@ -3007,13 +3820,10 @@
                              : resolveBasemapStyleUrl(this.mapOptions.mapType),
         center: [lon, lat],
         zoom: this._viewZoom != null && this._viewZoom !== '' ? flatToMapLibreZoom(Number(this._viewZoom)) : 8,
-        // .attribution(a) (MapBuilder, above) was stored but never read —
-        // unlike .legend()'s parallel _legendHtml, which the splash/legend
-        // block below actually renders. MapLibre's own AttributionControl
-        // is added automatically (not disabled anywhere in this file) and
-        // accepts extra text via customAttribution, appended alongside the
-        // basemap's own required CARTO/OpenStreetMap credit rather than
-        // replacing it.
+        // MapLibre's own AttributionControl (bottom right) keeps the
+        // basemap's required CARTO/OpenStreetMap credit; the page's own
+        // .attribution() goes bottom left, as flat shows it
+        // (createAttribution).
         //
         // A color `mapType` (mapTypeColor truthy — see
         // buildBlankBackgroundStyle above) has no real basemap at all, so
@@ -3024,7 +3834,6 @@
         // customAttribution's own required-credit behavior for a REAL
         // basemap is left untouched.
         ...(mapTypeColor ? { attributionControl: false } : {}),
-        ...(this._attributionText ? { customAttribution: this._attributionText } : {}),
         // MapLibre's default (true) is kept: with false it also stops the
         // zoom-out where the world gets narrower than the window, so a
         // world map can't open fully zoomed out. The deck.gl overlay takes
@@ -3122,112 +3931,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,
@@ -3235,88 +3940,17 @@
         // 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();
+      // the page's attribution (.attribution(), Map option attribution)
+      const attributionBox = createAttribution(map);
+      attributionBox.set(this._attributionText != null ? this._attributionText : this.mapOptions.attribution);
+      this._setAttribution = text => attributionBox.set(text);
 
       if (this._legendHtml && el.parentElement) {
         const legendEl = document.createElement('div');
@@ -3488,6 +4122,11 @@
         mapType: (id) => engineApi.setMapType(id),
         // flat's getMapTypeId(): the basemap type name in use
         getMapTypeId: () => String(builder.mapOptions.mapType || ''),
+        // flat's attribution (htmlgui.js htmlgui_set/getAttributionString)
+        setAttribution: (text) => { builder.attribution(text); return engineApi; },
+        // flat's map handle ixmaps.map().attribution(text) (htmlgui_flat.js 1381)
+        attribution: (text) => engineApi.setAttribution(text),
+        getAttribution: () => attributionBox.get(),
         setBasemapOpacity: (delta, mode) => {
           _basemapOpacity = mode === 'relative'
             ? Math.max(0, Math.min(1, _basemapOpacity + (parseFloat(delta) || 0)))
@@ -4337,698 +4976,10 @@
         });
       }
 
-      // 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 || '';
-            // 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));
-      }
+      // 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
@@ -7362,7 +7313,10 @@
       const geometry = { type: 'Point', coordinates: [ll.lng, ll.lat] };
       const hasClass = cell.first.properties.classValue !== undefined;
       let props = cell.n > 1
-        ? { cluster: true, point_count: cell.n, value: cell.value, ...(hasClass ? { classValue: cell.classValue } : {}) }
+        // titleRaw: the cell's first record — flat titles an aggregated
+        // item by it (itemTitle)
+        ? { cluster: true, point_count: cell.n, value: cell.value, ...(hasClass ? { classValue: cell.classValue } : {}),
+            titleRaw: cell.first.properties.raw || cell.first.properties }
         : 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
@@ -7428,6 +7382,7 @@
       let cell = cells.get(key);
       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++;
+      if (!cell.titleRaw) cell.titleRaw = f.properties.titleRaw || f.properties.raw || null;
       cell.counts[f.properties.cat] += f.properties.value;
       if (f.properties.classValue !== undefined) cell.classTotal = (cell.classTotal || 0) + f.properties.classValue;
       // point_count is the aggregated-record count of a multi-record
@@ -7441,7 +7396,8 @@
       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 } : {}) }
+        properties: { counts: cell.counts, total: cell.counts.reduce((a, c) => a + c, 0), recordCounts: cell.recordCounts, ...(cell.classTotal !== undefined ? { classTotal: cell.classTotal } : {}),
+          ...(cell.titleRaw ? { titleRaw: cell.titleRaw } : {}) }
       };
     });
   }
@@ -8346,14 +8302,31 @@
     //     only available for an individual, unaggregated point — an
     //     aggregated/grouped bubble has no single underlying record to
     //     tabulate, so it resolves to an empty string there.
+    // an item's title as flat gives it (maptheme.js 11838-11886): the title
+    // field of its record — of an aggregated item its first record; an
+    // aggregated grid cell (no aggregation field) of more than 3 records,
+    // or without a title, is titled "(n)"
+    _itemTitle(props) {
+      const raw = props.raw || props.titleRaw;
+      const title = this.binding.title && raw && raw[this.binding.title] != null ? String(raw[this.binding.title]) : '';
+      const aggregated = !!(props.counts || props.cluster);
+      if (aggregated && this._clusterRadiusPx && !this._clusterField) {
+        const n = groupRecordCount(props);
+        if (!title || n > 3) return '(' + n + ')';
+      }
+      return title;
+    }
+
     buildTooltipHtml(object) {
-      if (!this.meta.tooltip) return null;
+      // no .meta({tooltip}): flat's default template (tooltip_mustache.js 394)
+      // — the theme title, the item's title and its chart
+      const template = this.meta.tooltip || FLAT_DEFAULT_TOOLTIP;
       if (!global.Mustache) {
-        console.warn('[ixmaps-gl] .meta({tooltip}) is set but Mustache.js is not loaded — ' +
+        console.warn('[ixmaps-gl] tooltips need Mustache.js, which is not loaded — ' +
           'include https://unpkg.com/mustache@4.2.0/mustache.min.js before ixmaps-gl.js.');
         return null;
       }
-      return global.Mustache.render(this.meta.tooltip, this._buildTooltipContext(object));
+      return global.Mustache.render(template, this._buildTooltipContext(object));
     }
 
     _buildTooltipContext(object) {
@@ -8374,9 +8347,7 @@
             label: isGroup ? '' : (this.categoryDisplayLabels ? (this.categoryDisplayLabels[props.cat] || '') : ''),
             // flat: the item's title is its titlefield value (binding title/
             // titlefield, e.g. the comune name); else the class label
-            title: isGroup ? '' : (this.binding.title && props.raw && props.raw[this.binding.title] != null
-              ? String(props.raw[this.binding.title])
-              : (this.categoryDisplayLabels ? (this.categoryDisplayLabels[props.cat] || '') : '')),
+            title: this._itemTitle(props) || (isGroup ? '' : (this.categoryDisplayLabels ? (this.categoryDisplayLabels[props.cat] || '') : '')),
             count: isGroup ? (props.recordCounts ? props.recordCounts.reduce((a, c) => a + c, 0) : '') : 1,
             class: isGroup ? '' : props.cat
           }
@@ -8409,11 +8380,16 @@
     // breakdown, one line per present category, each with its own legend
     // color swatch and its OWN value (never summed across categories).
     _renderItemChartHtml(props) {
+      const unitOf = this.style.units ? ' ' + this.style.units : '';
+      // an AGGREGATE CATEGORICAL choropleth polygon: its sum per category
+      if (props.parts) {
+        const labels = this.categoryDisplayLabels || this.categoryLabels || [];
+        return tooltipTable(props.parts.map((v, i) => (v > 0 ? { rgb: this.categoryColorsRgb[i], label: labels[i] || '(n/d)', value: this._formatTooltipValue(v) + unitOf } : null)).filter(Boolean));
+      }
       if (this.flags.has('CHOROPLETH') && (this.flags.has('DOMINANT') || this.flags.has('COMPOSECOLOR')) && props.raw) {
         return this._renderMultiFieldBarsHtml(props.raw);
       }
-      const swatch = rgb => `<span style="display:inline-block;width:0.7em;height:0.7em;border-radius:50%;background:rgb(${rgb.join(',')});margin-right:0.4em;vertical-align:middle"></span>`;
-      const unit = this.style.units ? ' ' + this.style.units : '';
+      const unit = unitOf;
 
       // PLOT|GRIDSIZE curve cells: properties.values is an array parallel
       // to _plotCategories() (e.g. one FERITI sum per year), not a single
@@ -8423,10 +8399,10 @@
       if (Array.isArray(props.values)) {
         const categories = this._isItemPlot() ? this._itemPlotLabels() : this._plotCategories();
         const labels = this._isItemPlot() ? categories : Array.isArray(this.style.label) ? this.style.label.map(String) : categories;
-        return props.values.map((v, i) => {
+        return tooltipTable(props.values.map((v, i) => {
           if (v == null || isNaN(v)) return null;
-          return `<div>${labels[i] || categories[i] || i}: ${this._formatTooltipValue(v)}${unit}</div>`;
-        }).filter(Boolean).join('');
+          return { rgb: null, label: labels[i] || categories[i] || i, value: this._formatTooltipValue(v) + unit };
+        }).filter(Boolean));
       }
 
       if (props.counts) {
@@ -8445,19 +8421,17 @@
         // zoom until something resets it. Root cause of the "trackpad
         // zoom sometimes just stops updating" reports.
         const labels = this.categoryDisplayLabels || this.categoryLabels || [];
-        return labels.map((label, i) => {
+        return tooltipTable(labels.map((label, i) => {
           if (!(props.counts[i] > 0)) return null;
-          const rgb = this.categoryColorsRgb[i];
-          return `<div>${swatch(rgb)}${label || '(n/d)'}: ${this._formatTooltipValue(props.counts[i])}${unit}</div>`;
-        }).filter(Boolean).join('');
+          return { rgb: this.categoryColorsRgb[i], label: label || '(n/d)', value: this._formatTooltipValue(props.counts[i]) + unit };
+        }).filter(Boolean));
       }
       if (props.cat != null) {
         const label = this.categoryDisplayLabels ? (this.categoryDisplayLabels[props.cat] || '') : '';
         const rgb = this.categoryColorsRgb ? this.categoryColorsRgb[props.cat] : null;
         // no bound size field (e.g. a plain DOT|CATEGORICAL layer) -> just
         // the category label, no ": undefined" value suffix
-        const valueSuffix = this._hasValue(props.value) ? `: ${this._formatTooltipValue(props.value)}${unit}` : '';
-        return `<div>${rgb ? swatch(rgb) : ''}${label}${valueSuffix}</div>`;
+        return tooltipTable([{ rgb, label, value: this._hasValue(props.value) ? this._formatTooltipValue(props.value) + unit : '' }]);
       }
       return '';
     }
@@ -8518,7 +8492,7 @@
         .filter(k => k !== 'geometry')
         .map(k => `<tr><td style="padding:0 0.6em 0 0;color:#888">${k}</td><td>${this._isNumericValue(raw[k]) ? this._formatTooltipValue(raw[k]) : raw[k]}</td></tr>`)
         .join('');
-      return `<table style="font-size:0.85em;border-collapse:collapse">${rows}</table>`;
+      return `<table style="font-size:0.95em;border-collapse:collapse">${rows}</table>`;
     }
 
     _isNumericValue(v) {
@@ -8784,7 +8758,7 @@
             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,
+              value: agg ? agg.value : undefined, raw: agg ? f.properties : {}, cat: agg ? agg.index : null, parts: agg ? agg.parts : undefined,
               dopacityAlpha: agg && dopacityActive ? dominantDopacityAlpha(this.style, this.flags, agg.value, aggMaxA[agg.index]) : null
             }
           };
@@ -9813,7 +9787,8 @@
         return {
           geometry: f.geometry,
           properties: { counts: this._oneHot(f.properties.cat, f.properties.point_count), total: f.properties.value,
-            ...(f.properties.classValue !== undefined ? { classTotal: f.properties.classValue } : {}) }
+            ...(f.properties.classValue !== undefined ? { classTotal: f.properties.classValue } : {}),
+            ...(f.properties.titleRaw ? { titleRaw: f.properties.titleRaw } : {}) }
         };
       });
       return { individual, groups };
@@ -10184,9 +10159,7 @@
         const boxR = circular ? r * 1.1 + margin : r;
         let title = null;
         if (titleShown) {
-          const raw = d.properties.raw;
-          const n = groupRecordCount(d.properties);
-          const text = n > 3 ? '(' + n + ')' : (raw && raw[this.binding.title] != null ? String(raw[this.binding.title]) : '');
+          const text = this._itemTitle(d.properties);
           if (text) {
             const f = titleFontPx;
             const lines = wrapTitleLines(text, f, boxR * 2).split('\n');
@@ -10822,6 +10795,9 @@
   // nothing here authored that string. Escaped before going into
   // innerHTML so a stray `<`/`&`/quote in a source field can't break the
   // option markup (or worse).
+  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) {
@@ -10829,10 +10805,186 @@
     if (display && display !== rt.categoryLabels) return display;
     return (rt.categoryLabels || []).map(v => escapeHtml(v));
   }
-  function escapeHtml(s) {
-    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+  // ===============================================================
+  // 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)
+  // flat's tooltip for a theme without its own template (ui/js/tools/
+  // tooltip_mustache.js 394)
+  // tooltip_mustache.js 394) — the same parts, structured: the theme title
+  // as h2, the item title as h3, the chart (tooltipTable) below
+  // (inline styles throughout: a page's own h2 / table / td rules must not
+  // restyle the tooltip)
+  const FLAT_DEFAULT_TOOLTIP = "<h2 style='margin:0 0 0.15em;padding:0;font-size:1.25em;font-weight:600;text-align:left;white-space:nowrap;overflow:hidden;text-overflow:ellipsis'>{{theme.title}}</h2>"
+    + "{{#theme.item.title}}<h3 style='margin:0 0 0.4em;padding:0;font-size:1.1em;font-weight:600;text-align:left;white-space:nowrap;overflow:hidden;text-overflow:ellipsis'>{{theme.item.title}}</h3>{{/theme.item.title}}"
+    + "{{theme.item.chart}}";
+  // {{theme.item.chart}} as a table: per row a color swatch (or none), the
+  // label (left, one line) and the value (right-aligned)
+  function tooltipTable(rows) {
+    if (!rows.length) return '';
+    const swatch = rgb => (rgb ? `<span style="display:inline-block;width:0.75em;height:0.75em;border-radius:50%;background:rgb(${rgb.slice(0, 3).join(',')})"></span>` : '');
+    const td = 'border:none;background:transparent;font:inherit;color:inherit;line-height:1.15;';
+    return '<table style="border-collapse:collapse;border:none;background:transparent;margin:0.2em 0;font-size:1em;line-height:1.15">'
+      + rows.map(r => '<tr>'
+        + `<td style="${td}padding:0.05em 0.4em 0.05em 0;vertical-align:middle">${swatch(r.rgb)}</td>`
+        // one line: a long label ends in an ellipsis (full text as its title)
+        + `<td style="${td}padding:0.05em 0.8em 0.05em 0;text-align:left"><span title="${escapeHtml(String(r.label).replace(/<[^>]*>/g, ''))}" style="display:inline-block;max-width:13em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;vertical-align:bottom">${r.label}</span></td>`
+        + `<td style="${td}padding:0.05em 0;text-align:right;white-space:nowrap">${r.value}</td></tr>`).join('')
+      + '</table>';
+  }
+  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', 'attribution'];
+  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
   // up from _globalThemeRegistry (see its own comment for the "last
@@ -11312,6 +11464,10 @@
     // handle's methods on the last built map
     getCenter: () => (_lastMapApi && _lastMapApi.map ? _lastMapApi.map.getCenter() : null),
     getMapTypeId: () => (_lastMapApi && _lastMapApi.getMapTypeId ? _lastMapApi.getMapTypeId() : ''),
+    // flat's attribution: ixmaps.setAttribution(text) and its htmlgui_ pair
+    setAttribution: (text) => { if (_lastMapApi && _lastMapApi.setAttribution) _lastMapApi.setAttribution(text); },
+    htmlgui_setAttributionString: (text) => { if (_lastMapApi && _lastMapApi.setAttribution) _lastMapApi.setAttribution(text); },
+    htmlgui_getAttributionString: () => (_lastMapApi && _lastMapApi.getAttribution ? _lastMapApi.getAttribution() : ''),
     changeThemeStyle: (szMap, szId, szStyle, szFlag) => _mapHandle.changeThemeStyle(szId, szStyle, szFlag),
     removeTheme: (szMap, szId) => _mapHandle.remove(szId),
     setBasemapOpacity: (szMap, nOpacity, szMode) => _mapHandle.setBasemapOpacity(nOpacity, szMode),
@@ -11338,7 +11494,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, legendRowLabels, scaleDenom, cssColorAlpha, aggregatedCategoricalClass, dominantDopacityAlpha, isAggregatedCategoricalChoropleth, computeBubblePackLayout, isolatedBubblePackLayout, sequenceLayout,
+    IXMAPS_GL_VERSION, tooltipTable, 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,