ixmaps-gl 0.2.11 → 0.2.15

package/ixmaps-gl.js

@@ -21,8 +21,8 @@
 // alpha100}) when set (alpha100:"$density$" divides by the polygon's
 // own geodesic area — see _prepareAlphaField/_resolveDopacityAlpha).
 // AGGREGATE CATEGORICAL on one field paints each polygon in its records'
-// dominant category; a plain CATEGORICAL choropleth is not implemented,
-// see _buildChoroplethLayers), and the CHART|SYMBOL|
+// dominant category; a plain CATEGORICAL choropleth matches each polygon's
+// raw value against the categories, see _buildChoroplethLayers), and the CHART|SYMBOL|
 // GLOW|CATEGORICAL|AGGREGATE|COUNT|RELOCATE|VALUES pipeline (categorical
 // clustering + sizing + glow + multi-bubble grouping + on-bubble value
 // labels, generalized to however many distinct category values the DATA
@@ -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.11';
+  const IXMAPS_GL_VERSION = '0.2.15';
 
   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.25/dist/validate.mjs';
+  const VALIDATOR_URL_DEFAULT = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-grammar@v0.1.27/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;
@@ -1951,6 +1951,10 @@
   // per-map handle — most real pages only ever build one map anyway. Set
   // once per successful build(), just before it returns engineApi below.
   let _lastMapApi = null;
+  // flat's map instance registry (htmlgui_flat.js 2416): the built maps by
+  // their Map() options name — ixmaps.map("name") is the handle of THAT
+  // map, ixmaps.map() stays the last built one
+  const _mapApis = Object.create(null);
   // resolves with the first built map's API: ixmaps.map() calls a page
   // makes while the map is still building wait for it
   let _resolveMapReady;
@@ -2125,7 +2129,7 @@
   // edit it by hand; `npm run unit` fails when it drifts.
   // ---------------------------------------------------------------
   // <grammar:binding-aliases>
-  // generated from ixmaps-grammar 0.1.25 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
+  // generated from ixmaps-grammar 0.1.27 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
   const FLAT_BINDING_ALIASES = {
     "aggregation": "style.aggregationfield",
     "aggregationfield": "style.aggregationfield",
@@ -2187,7 +2191,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.25 — 5 meta keys
+  // generated from ixmaps-grammar 0.1.27 — 5 meta keys
   const FLAT_META_KEYS = ["description","name","snippet","title","tooltip"];
   // </grammar:meta-keys>
 
@@ -2206,6 +2210,7 @@
     'style.alphafield': ['binding', 'alpha'],
     'style.alphafield100': ['binding', 'alpha100'],
     'style.valuefield': ['style', 'valuefield'],
+    'style.timefield': ['binding', 'time'], // setThemeTimeFrame, see LayerRuntime.setTimeFrame
     'style.titlefield': ['binding', 'title'], // {{theme.item.title}}, see _buildTooltipContext
     // the lookup key's normalization (flatLookupKey): flat's newTheme moves
     // binding.tonumber / digits / … into these style keys (htmlgui.js 1712)
@@ -2371,7 +2376,8 @@
   const STYLE_NUMBER_KEYS = ['linewidth', 'fillopacity', 'scale', 'classes', 'valuedecimals', 'normalsizevalue',
     'sizepow', 'rangescale', 'minvalue', 'maxvalue', 'markersize', 'boxopacity', 'outlierscale', 'valuescale',
     'brightness', 'fractionscale', 'dopacityscale', 'dopacitypow', 'gridwidthpx', 'textscale', 'rangecentervalue',
-    'shadowblur', 'shadowdx', 'shadowdy', 'maxshadow', 'offsetx', 'offsety'];
+    'shadowblur', 'shadowdx', 'shadowdy', 'maxshadow', 'offsetx', 'offsety', 'gridx', 'boxmargin', 'borderwidth',
+    'borderradius', 'maxcharts'];
   function toNumberIfNumeric(v) {
     if (typeof v !== 'string' || !v.trim()) return v;
     const n = Number(v);
@@ -2635,6 +2641,69 @@
     return { dark: false, bg: 'rgba(255,255,255,0.9)' };
   }
 
+  // ---------------------------------------------------------------
+  // Effective basemap darkness — what the map canvas actually shows,
+  // not what its name suggests. flatLegendLook's name-plus-opacity
+  // heuristic assumes the faded (basemapopacity <= 0.5) basemap blends
+  // against a WHITE page, so a dark basemap faded to half goes light;
+  // on a page with a dark background it reads dark all the same, and
+  // tooltips/legends styled light stick out (the exact bug fixed here).
+  // Rule: an explicit color (legendBackground, a color mapType) stays
+  // authoritative as before; with a real basemap style, a DARK style
+  // background means dark — except when it is faded to
+  // basemapopacity <= 0.5, where the mix is mostly the page background
+  // behind the semi-transparent canvas and THAT decides (dark page ->
+  // still dark; white page -> flat's washed-out light look). A light
+  // style background reads light however it is faded (flat's own rule).
+  // Falls back to the name heuristic while no style exists.
+  // ---------------------------------------------------------------
+  function styleBackgroundColorOf(map) {
+    try {
+      const style = map && map.getStyle && map.getStyle();
+      if (!style || !style.layers) return null;
+      for (const layer of style.layers) {
+        if (layer.type !== 'background') continue;
+        const paint = layer.paint || {};
+        const color = paint['background-color'] != null ? paint['background-color'] : (paint.background != null ? paint.background : null);
+        // the blank background substituted for a color mapType IS the page's
+        // requested background and never faded (see applyBasemapOpacity)
+        return { color: color, faded: layer.id !== BLANK_BACKGROUND_LAYER_ID };
+      }
+    } catch (e) { /* no style (yet) */ }
+    return null;
+  }
+
+  function pageBackgroundColorOf(el) {
+    let node = el;
+    while (node && node.nodeType === 1 && node !== document.documentElement) {
+      const m = String(getComputedStyle(node).backgroundColor)
+        .match(/^rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)(?:[,/\s]+([\d.]+))?\s*\)/i);
+      if (m && (m[4] === undefined || +m[4] > 0)) return [+m[1], +m[2], +m[3]];
+      node = node.parentElement;
+    }
+    return [255, 255, 255]; // the page default
+  }
+
+  function effectiveMapDark(map, el, basemapOpacity, mapType, legendBackground) {
+    const id = legendBackground || mapType;
+    if (flatIsCssColorValue(id)) return flatIsDarkColor(id);
+    const base = styleBackgroundColorOf(map);
+    const rgb = base && base.color != null ? parseCssColor(String(base.color)) : null;
+    if (!rgb) {
+      // no style (yet): the name heuristic, exactly as before
+      return flatLegendLook(mapType, basemapOpacity, legendBackground).dark;
+    }
+    const o = isNaN(basemapOpacity) ? 1 : Math.max(0, Math.min(1, basemapOpacity));
+    if (flatIsDarkColor('rgb(' + rgb.map(Math.round).join(',') + ')')) {
+      // a dark basemap faded to half or less shows mostly the page background
+      // behind the canvas - so at that point the PAGE decides (dark page ->
+      // still dark; white page -> the washed-out flat look stays light)
+      return (base.faded && o <= 0.5) ? flatIsDarkColor('rgb(' + pageBackgroundColorOf(el).map(Math.round).join(',') + ')') : true;
+    }
+    // a light basemap reads light however it is faded - flat's own rule
+    return false;
+  }
+
   function buildBlankBackgroundStyle(color) {
     return {
       version: 8,
@@ -2677,6 +2746,40 @@
   }
 
   // ---------------------------------------------------------------
+  // Embedded YouTube players in tooltips (data fields carrying <iframe
+  // src=".../embed/ID">) are replaced by a thumbnail with a play button; the
+  // real iframe is created on click. Keeps tooltips light, and a removed
+  // video or a refused embed (e.g. error 153 on file:// pages) degrades to a
+  // thumbnail that opens YouTube in a new tab instead of a broken player.
+  const YT_IFRAME_RE = /<iframe\b[^>]*?\bsrc\s*=\s*["']?(?:https?:)?\/\/(?:www\.)?youtube(?:-nocookie)?\.com\/embed\/([\w-]{6,})[^"'\s>]*["']?[^>]*>\s*<\/iframe>/gi;
+  function youtubeClickToPlay(html) {
+    if (!html || html.indexOf('youtube') < 0) return html;
+    return html.replace(YT_IFRAME_RE, (m, id) => {
+      const w = (/\bwidth\s*=\s*["']?(\d+)/i.exec(m) || [])[1] || 240;
+      const h = (/\bheight\s*=\s*["']?(\d+)/i.exec(m) || [])[1] || 180;
+      return '<div class="ixgl-yt" data-yt="' + id + '" data-w="' + w + '" data-h="' + h + '" ' +
+        'style="position:relative;width:' + w + 'px;height:' + h + 'px;cursor:pointer;background:#000 url(https://i.ytimg.com/vi/' + id + '/hqdefault.jpg) center/cover" ' +
+        'title="play"><span style="position:absolute;left:50%;top:50%;width:48px;height:34px;margin:-17px 0 0 -24px;' +
+        'border-radius:8px;background:rgba(220,0,0,0.9)"></span><span style="position:absolute;left:50%;top:50%;margin:-9px 0 0 -6px;' +
+        'border-style:solid;border-width:9px 0 9px 15px;border-color:transparent transparent transparent #fff"></span></div>';
+    });
+  }
+  if (typeof document !== 'undefined' && typeof document.addEventListener === 'function' && !global.__ixglYtClick) {
+    global.__ixglYtClick = true;
+    document.addEventListener('click', e => {
+      const el = e.target.closest && e.target.closest('.ixgl-yt');
+      if (!el) return;
+      e.stopPropagation();
+      const f = document.createElement('iframe');
+      f.width = el.dataset.w; f.height = el.dataset.h; f.frameBorder = '0';
+      f.allow = 'autoplay; encrypted-media; picture-in-picture; fullscreen';
+      f.allowFullscreen = true;
+      f.referrerPolicy = 'strict-origin-when-cross-origin';
+      f.src = 'https://www.youtube.com/embed/' + el.dataset.yt + '?autoplay=1&rel=0';
+      el.replaceWith(f);
+    }, true);
+  }
+
   // 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
@@ -2686,6 +2789,12 @@
   // ---------------------------------------------------------------
   function createTooltips(ctx) {
     const { builder, map, el, findRuntimeForLayerId } = ctx;
+    // the effective (rendered) dark/light probe for tooltip and legend —
+    // the builder carries it so the legend look (built later, without the
+    // map element at hand) can ask the same question
+    builder.__effectiveDark = function (basemapOpacity, mapType, legendBackground) {
+      return effectiveMapDark(map, el, basemapOpacity, mapType, legendBackground);
+    };
     // 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
@@ -2695,28 +2804,101 @@
     // 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
+    // Tooltip look, like the legend's: 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 —
+    // decided by the EFFECTIVE map darkness (style background vs page
+    // background, see effectiveMapDark), not the basemap name alone. Read
+    // when shown, so options set later (a
     // myMap.then(...).options({basemapopacity})) count.
-    const tooltipLook = () => {
+    const tooltipIsDark = () => {
       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 legendBackground = builder.mapOptions.legendBackground || builder.mapOptions.legendbackground;
+      return typeof builder.__effectiveDark === 'function'
+        ? builder.__effectiveDark(isNaN(o) ? 1 : o, builder.mapOptions.mapType, legendBackground)
+        : flatLegendLook(builder.mapOptions.mapType, isNaN(o) ? 1 : o, legendBackground).dark;
+    };
+    // flat's tooltip look (tooltip_mustache.js 118/151-154): arial narrow,
+    // the font size clamped to 11..14px; light: white 0.95, #444 text, thin
+    // black border; dark: rgba(50,50,50,0.95), #555 border (text light for
+    // readability — flat leaves its #444 on dark and only adapts the panel).
+    // line-height is declared so hover (deck.gl's .deck-tooltip stylesheet
+    // gives it 20px) and the pinned tooltip (a bare div that would inherit
+    // the page's 'normal') render the same content identically
+    const tooltipLook = () => {
+      const fontsize = Math.min(14, Math.max(11, (22 / 1200 * (global.innerWidth || 1200))));
+      const fonts = { fontFamily: 'arial narrow, system', fontSize: fontsize + 'px', lineHeight: '20px' };
+      return tooltipIsDark()
+        ? Object.assign(fonts, { background: 'rgba(50,50,50,0.95)', color: 'rgb(200,205,214)', border: '0.5px solid #555', borderRadius: '5px',
+            boxShadow: '0 2px 8px rgba(0,0,0,0.3)' })
+        : Object.assign(fonts, { 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' });
     };
+    // flat's content pane (tooltip_mustache.js 124): the whole tooltip
+    // content scrolls inside its own padded pane — a close button outside
+    // the pane stays visible while it scrolls, and the scrollbar clears
+    // the content by a small right margin
+    const TOOLTIP_PANE_STYLE = 'margin:0.5em;max-height:360px;overflow:auto';
+    const tooltipPaneHtml = (html) => `<div style="${TOOLTIP_PANE_STYLE}">${html}</div>`;
     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;';
+      'pointer-events:auto;max-width:440px;padding:0.5em 0.7em 0.5em 0.5em;';
+
+    // flat's own tooltip placement (tooltip_mustache.js 145-148): flip it
+    // to the left/above the anchor when there is no room right/below, then
+    // clamp it into the window — a tooltip must always be completely
+    // visible (an element larger than the viewport ends up at its edge)
+    function keepTooltipVisible(tipEl, x, y) {
+      const w = tipEl.offsetWidth, h = tipEl.offsetHeight;
+      const vw = global.innerWidth || 1200, vh = global.innerHeight || 800;
+      let tx = x > vw / 2 ? x - w - 30 : x + 30;
+      let ty = y > vh / 2 ? y - h - 20 : y + 20;
+      tx = Math.min(Math.max(8, tx), Math.max(8, vw - w - 8));
+      ty = Math.min(Math.max(8, ty), Math.max(8, vh - h - 8));
+      const transform = `translate(${Math.round(tx)}px, ${Math.round(ty)}px)`;
+      tipEl.style.transform = transform;
+      return transform;
+    }
 
     function updatePinnedTooltipPosition() {
       if (!pinned) return;
       const pt = map.project(pinned.lngLat);
-      pinnedTooltipEl.style.transform = `translate(${pt.x + 10}px, ${pt.y - 10}px)`;
+      keepTooltipVisible(pinnedTooltipEl, pt.x, pt.y);
+    }
+
+    // hover tooltip: deck.gl pins it at the pointer without any viewport
+    // logic (it overflows the right/bottom edge there) — watch the element's
+    // style mutations and re-place it inside the window every time deck
+    // moves it. Our own write is recognized and skipped (lastSetTransform).
+    let __hoverTooltipWatch = null;
+    function watchHoverTooltip() {
+      if (__hoverTooltipWatch || !el.parentElement) return;
+      const host = el.parentElement;
+      const attach = (tipEl) => {
+        let lastSetTransform = null;
+        const mo = new MutationObserver(() => {
+          if (tipEl.style.display === 'none' || !tipEl.textContent.trim()) return;
+          const t = tipEl.style.transform;
+          if (!t || t === lastSetTransform) return;
+          const m = /translate\((-?[\d.]+)px,\s*(-?[\d.]+)px\)/.exec(t);
+          if (!m) return;
+          lastSetTransform = keepTooltipVisible(tipEl, +m[1], +m[2]);
+        });
+        mo.observe(tipEl, { attributes: true, attributeFilter: ['style'] });
+        __hoverTooltipWatch = mo;
+      };
+      const existing = host.querySelector('.deck-tooltip');
+      if (existing) { attach(existing); return; }
+      const creation = new MutationObserver((muts, obs) => {
+        for (const mu of muts) for (const n of mu.addedNodes) {
+          if (n.nodeType === 1 && n.classList && n.classList.contains('deck-tooltip')) {
+            attach(n);
+            obs.disconnect();
+            return;
+          }
+        }
+      });
+      creation.observe(host, { childList: true, subtree: true });
     }
 
     // A stable per-geometry anchor coordinate for the identity check
@@ -2750,13 +2932,19 @@
     }
 
     // content lives in its own child so re-rendering (innerHTML) never
-    // wipes out the unpin button below (a sibling, not a descendant of it)
+    // content lives in its own child so re-rendering (innerHTML) never
+    // wipes out the unpin button below (a sibling, not a descendant of it).
+    // The content child sits inside a scroll PANE (flat's own tooltip
+    // structure): the pane scrolls, the close button outside it does not
+    const pinnedPaneEl = document.createElement('div');
+    pinnedPaneEl.style.cssText = TOOLTIP_PANE_STYLE;
     const pinnedContentEl = document.createElement('div');
-    pinnedTooltipEl.appendChild(pinnedContentEl);
+    pinnedPaneEl.appendChild(pinnedContentEl);
+    pinnedTooltipEl.appendChild(pinnedPaneEl);
 
     function renderPinnedTooltip() {
       if (!pinned) { pinnedTooltipEl.style.display = 'none'; return; }
-      const html = pinned.runtime.buildTooltipHtml(pinned.object);
+      const html = pinned.runtime.buildTooltipHtml(pinned.object, tooltipIsDark());
       if (!html) { pinned = null; pinnedTooltipEl.style.display = 'none'; return; }
       pinnedContentEl.innerHTML = html;
       Object.assign(pinnedTooltipEl.style, tooltipLook());
@@ -2797,7 +2985,15 @@
     // 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; }
+    // flat's map tool 'pan' (Map option mode:"pan", Api.setMapTool): pure
+    // navigation — no hover tooltip there (flat's own hover-tooltip paths
+    // run only for the ""/info/clickinfo tool types, mapscript2.js 5232).
+    // The click-to-pin tooltip stays: it is this engine's equivalent of
+    // flat's info popup, so a click still shows the permanent tooltip.
+    const isPanMode = () => /^\s*pan\s*$/i.test(String(builder.mapOptions.mode || ''));
+
     function tooltipFor({ object: picked, layer }) {
+        if (isPanMode()) return null;
         const object = pickedFeature(picked);
         if (!object || !layer) return null;
         // suppress the hover tooltip ONLY for the specific item that's
@@ -2807,8 +3003,10 @@
         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;
+        const html = rt.buildTooltipHtml(object, tooltipIsDark());
+        // same layout as the pinned tooltip: the content in flat's scroll
+        // pane, the shared look (fonts included) on the container
+        return html ? { html: tooltipPaneHtml(html), style: Object.assign({ padding: '0.5em 0.7em', maxWidth: '440px' }, tooltipLook()) } : null;
     }
     function clickFor(picked) {
         const info = picked && Object.assign({}, picked, { object: pickedFeature(picked.object) });
@@ -2868,10 +3066,13 @@
     }
     function mount() {
       map.on('move', updatePinnedTooltipPosition);
-      if (el.parentElement) {
-        el.parentElement.style.position = el.parentElement.style.position || 'relative';
-        el.parentElement.appendChild(pinnedTooltipEl);
-      }
+      watchHoverTooltip();
+      // anchor inside the map container: map.project() gives container-
+      // relative pixels, and styling the page's own body (relative) breaks
+      // any page element absolutely positioned against it (AirBnB's
+      // #onmap-buttons on a zero-height all-float body flew off-screen)
+      el.style.position = el.style.position || 'relative';
+      el.appendChild(pinnedTooltipEl);
     }
     return { getTooltip, onClick, mount };
   }
@@ -2885,7 +3086,7 @@
   // layoutLegends().
   // ---------------------------------------------------------------
   function createLegend(ctx) {
-    const { builder, map, el, overlay, runtimes, engineApi, built, refresh, scheduleRefresh, notifyRedraw } = ctx;
+    const { builder, map, el, overlay, runtimes, engineApi, built, refresh, scheduleRefresh, notifyRedraw, quietRefresh } = ctx;
     let addLegendPanel = () => {};
     let setLegendOption = () => {};
     let updateSubTheme = () => {};
@@ -3033,15 +3234,28 @@
         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;'
+          + 'display:flex;flex-direction:column;max-height:66.6%;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)}';
+          // the slider rules are flat's own legend.css .slider block
+          // (355-411) — its two duplicate blocks resolved to what the
+          // cascade actually shows: a 5px rounded grey track at 0.7
+          // opacity (1 on hover) and a green thumb
+          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)}'
+            + '.ix-legend-stack input[type=range]{-webkit-appearance:none;appearance:none;height:5px;border-radius:10px;background:rgba(155,155,155,0.3);border:solid #888 0px;outline:none;opacity:0.7;transition:opacity .2s;}'
+            + '.ix-legend-stack input[type=range]:hover{opacity:1;}'
+            + '.ix-legend-stack input[type=range]::-webkit-slider-thumb{-webkit-appearance:none;appearance:none;width:14px;height:14px;border-radius:0.5em;background:#4CAF50;cursor:pointer;}'
+            + '.ix-legend-stack input[type=range]::-moz-range-thumb{width:25px;height:25px;border-radius:50%;background:#4CAF50;cursor:pointer;}';
           document.head.appendChild(css);
         }
-        el.parentElement.appendChild(legendStack);
+        // flat anchors its legend inside the map div (#map-legend), so the
+        // panel's max-height resolves against the MAP's height — the stack's
+        // former parent anchor collapsed it to 0 on pages whose body has
+        // only floated children (height 0)
+        el.style.position = el.style.position || 'relative';
+        el.appendChild(legendStack);
         return legendStack;
       };
       // map.setLegend(value): the `legend` map option at runtime, same values as
@@ -3073,7 +3287,10 @@
         });
         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');
+      // a plain FEATURE(S) base layer has one flat fill (no classes); FEATURE|CATEGORICAL
+      // is coloured per category (see _buildFeaturesLayers), so it gets a legend
+      const legendApplies = rt => rt.categoryLabels && rt.categoryLabels.length
+        && (!(rt.flags.has('FEATURE') || rt.flags.has('FEATURES')) || rt.flags.has('CATEGORICAL')) && !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.
@@ -3083,7 +3300,7 @@
         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';
+        el.style.position = el.style.position || 'relative';
         {
         // .type("...|NOLEGEND") — the fourth real legend-related type()
         // token: opts a theme OUT of the legend entirely (real engine's
@@ -3109,8 +3326,16 @@
           // 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 legendBackground = builder.mapOptions.legendBackground || builder.mapOptions.legendbackground;
+          const flatLook = flatLegendLook(builder.mapOptions.mapType, isNaN(opacityOpt) ? 1 : opacityOpt, legendBackground);
+          // effective darkness (style background vs page background, see
+          // effectiveMapDark): a dark basemap faded to <= 0.5 over a DARK
+          // page still reads dark — flatLegendLook's name heuristic would
+          // wrongly switch the panel (and the tooltip) to light there
+          const looksDark = typeof builder.__effectiveDark === 'function'
+            ? builder.__effectiveDark(isNaN(opacityOpt) ? 1 : opacityOpt, builder.mapOptions.mapType, legendBackground)
+            : flatLook.dark;
+          const isLightLegend = rt.style.legendtheme === 'light' || (rt.style.legendtheme !== 'dark' && !looksDark);
           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)',
@@ -3118,24 +3343,26 @@
             : { 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.
+          // the panel bg follows the same effective decision (flatLegendLook
+          // would hand the dark look a light bg here: its dark branch never
+          // ran for this map, its light bg would clash with dark rows/text)
+          if (!rt.style.legendtheme) legendColors.bg = looksDark ? '#111' : flatLook.bg;
+          // max-height:66.6% resolves against el's own height (the map
+          // container, which always has a definite height for the map
+          // itself to render into) since this panel sits in the stack,
+          // absolutely positioned inside el. flex:0 1 auto + min-height:0
+          // lets the panel SHRINK to the stack's 2/3 cap so the ROWS
+          // wrapper (its own flex:1 1 auto + min-height:0 below) scrolls
+          // internally while the header/description/slider stay fixed —
+          // with flex:0 0 auto the panel grew past the cap and the whole
+          // stack scrolled instead. text-align:left: the page body may
+          // centre everything (the AirBnB port does), the legend is left
+          // aligned chrome.
           // 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;'
+          panel.style.cssText = 'position:relative;flex:0 1 auto;min-height:0;overflow:hidden;'
+            + 'display:flex;flex-direction:column;text-align:left;'
             + '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);
@@ -3208,7 +3435,11 @@
             (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;
+              // a polygon (FEATURE|CATEGORICAL) is counted at its first vertex
+              let pt = f.geometry && f.geometry.coordinates;
+              while (Array.isArray(pt) && Array.isArray(pt[0])) pt = pt[0];
+              if (!Array.isArray(pt)) return;
+              const [lng, lat] = pt;
               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;
@@ -3570,12 +3801,12 @@
           slider.min = isOpacitySlider ? '0' : '25';
           slider.max = isOpacitySlider ? '100' : '200';
           slider.value = String(initialPct);
-          slider.style.cssText = 'width:100%;margin-top:2px;';
+          slider.style.cssText = 'width:50%;margin-top:0.4em;'; // flat's own inline slider style (legend.js 2392)
           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();
+            quietRefresh();
           });
           bodyEl.appendChild(slider);
           }
@@ -3645,6 +3876,8 @@
       this._layerBuilders.push(nameOrBuilder);
       return this;
     }
+    // .Layer() — alias of .layer()
+    Layer(nameOrBuilder) { return this.layer(nameOrBuilder); }
     // GL-PORT COMPAT: real ixmaps-flat's map.on("layerdraw", cb) — only
     // "layerdraw" is actually wired up (see build()'s own note on how
     // it's translated into onRedraw + a synthetic per-runtime event); any
@@ -3843,6 +4076,16 @@
         // world once, at the cost of that zoom limit.
         renderWorldCopies: this._engineOptions.worldcopies !== false
       });
+      // ixmaps.Map(id, {mapProjection}): flat's orthographic map is MapLibre's
+      // native globe here (same mapping as loadProject, applyProjectMap);
+      // "ortographic" is the spelling flat pages commonly carry. Any other
+      // value stays mercator.
+      if (/^(orth?ographic|globe)$/i.test(String(this.mapOptions.mapProjection || '').trim())) {
+        map.once('style.load', () => {
+          try { map.setProjection({ type: 'globe' }); }
+          catch (e) { console.warn('[ixmaps-gl] mapProjection "globe": map.setProjection failed (needs maplibre-gl >=5.0.1)', e); }
+        });
+      }
       _boundsSource = () => {
         const b = map.getBounds();
         return [{ lat: b.getSouth(), lng: b.getWest() }, { lat: b.getNorth(), lng: b.getEast() }];
@@ -3937,9 +4180,11 @@
       const overlay = new MapLibreOverlay({
         interleaved: true,
         layers: [],
-        // pointer becomes a hand over anything pickable (bubbles/points),
-        // so hovering something clickable actually looks clickable
-        getCursor: ({ isDragging, isHovering }) => (isDragging ? 'grabbing' : (isHovering ? 'pointer' : 'grab')),
+        // pointer becomes a hand over anything pickable (bubbles/points), so
+        // hovering something clickable actually looks clickable — except in
+        // the 'pan' input mode, where nothing responds to hovering
+        getCursor: ({ isDragging, isHovering }) =>
+          (isDragging ? 'grabbing' : ((isHovering && !/^\s*pan\s*$/i.test(String(this.mapOptions.mode || ''))) ? 'pointer' : 'grab')),
         // (guarded: see createTooltips)
         getTooltip: tooltips.getTooltip,
         onClick: tooltips.onClick
@@ -3952,12 +4197,14 @@
       attributionBox.set(this._attributionText != null ? this._attributionText : this.mapOptions.attribution);
       this._setAttribution = text => attributionBox.set(text);
 
-      if (this._legendHtml && el.parentElement) {
+      if (this._legendHtml) {
         const legendEl = document.createElement('div');
         legendEl.style.cssText = 'position:absolute;top:0;left:0;z-index:5;pointer-events:none';
         legendEl.innerHTML = this._legendHtml;
-        el.parentElement.style.position = el.parentElement.style.position || 'relative';
-        el.parentElement.appendChild(legendEl);
+        // inside the map container, never the page's body (see the pinned
+        // tooltip mount) — styling body breaks page-positioned elements
+        el.style.position = el.style.position || 'relative';
+        el.appendChild(legendEl);
       }
 
       // themes are addressed by either the layer()'s own name (e.g. "AREU")
@@ -4216,6 +4463,18 @@
             refresh();
           }
         },
+        // flat's ixmaps.setThemeTimeFrame(szId, min, max): show only the
+        // records whose timefield lies in [min, max) (ms or Date-
+        // parsable). null min+max clears. szId null/undefined = every theme
+        // that has a timefield (flat: one call updates all themes at once).
+        setThemeTimeFrame: (themeId, min, max) => {
+          const targets = themeId == null ? runtimes.filter(r => r.binding && r.binding.time) : (() => {
+            const rt = findRuntime(themeId);
+            return rt ? siblingRuntimes(rt).filter(r => r.binding && r.binding.time) : [];
+          })();
+          targets.forEach(rt => rt.setTimeFrame(min, max));
+          if (targets.length) refresh();
+        },
         // shows/hides a whole theme (all the deck.gl layers its
         // buildDeckLayers would otherwise produce) without touching its
         // data or style — for toggle controls like the real page's
@@ -4301,6 +4560,8 @@
           };
           return lb;
         },
+        // .Layer() — alias of .layer()
+        Layer: (nameOrBuilder) => engineApi.layer(nameOrBuilder),
         // Real ixmaps-flat's loadProject (htmlgui.js loadProject →
         // setProjectJSON → continueSetProjectJSON): src is a project object,
         // a JSON string, or a URL (fetched as DATA — nothing a project names
@@ -4633,7 +4894,15 @@
         const svg = String(m.map || '');
         if (svg && !/generic\/(mercator|orthographic)\.svg$/i.test(svg)) report.notes.push(`flat SVG map "${svg.split('/').pop()}" is not available in ixmaps-gl — mercator used`);
         if (typeof map.setProjection === 'function') {
-          try { map.setProjection({ type: /orthographic\.svg$/i.test(svg) ? 'globe' : 'mercator' }); }
+          try {
+            map.setProjection({ type: /orthographic\.svg$/i.test(svg) ? 'globe' : 'mercator' });
+            // the layers are projection-dependent (globe: far-hemisphere cull,
+            // chart placement) and are otherwise rebuilt only by a pan: rebuild
+            // now, and again once the new projection has rendered
+            refreshLayers();
+            map.triggerRepaint();
+            map.once('idle', refreshLayers);
+          }
           catch (e) { console.warn('[ixmaps-gl] loadProject: map.setProjection failed (needs maplibre-gl >=5.0.1)', e); }
         } else {
           console.warn('[ixmaps-gl] loadProject: map.setProjection not available on the loaded maplibre-gl build (needs >=5.0.1) — projection unchanged');
@@ -4979,9 +5248,18 @@
       // 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 }));
+        createLegend({ builder, map, el, overlay, runtimes, engineApi, built, refresh, scheduleRefresh, notifyRedraw,
+          // flat's legend slider (legend.js 2839-2854) patches the style and
+          // calls redrawTheme — a per-theme redraw that does NOT fire
+          // htmlgui_onDrawTheme, so a page's own onDrawTheme hook (this
+          // port's hookStatistics re-applying its own slider's scale)
+          // only reasserts on the next full redraw (pan/zoom). refresh()
+          // here would notify synchronously and clobber the new scale in
+          // the same tick — this quiet variant is that flat behavior.
+          quietRefresh: () => { refreshLayers(); } }));
 
       _lastMapApi = engineApi;
+      if (this.mapOptions && this.mapOptions.name) _mapApis[this.mapOptions.name] = engineApi;
       // ?ixgl-debug: ixmaps.__glDebug.check() reports, for the moment it is
       // called, every theme's geometry problems (invalid or mixed-dimension
       // coordinates, a shape far larger than the theme's others) and what
@@ -5047,6 +5325,27 @@
     }
   }
 
+  // GL-PORT COMPAT: flat's ixmaps.Map(div, opts, cb) hands the callback a
+  // mapApi HANDLE (htmlgui_flat.js 904-935) — a real page keeps it and
+  // calls its methods on it (__map.setView(...), __map.replace(...) —
+  // AirBnB's city selector). This engine hands the callback the BUILDER
+  // for its own .options().view().layer() chain; the builder here also
+  // carries flat's handle methods, delegated to the map handle of THIS
+  // map's options name (calls before the map exists wait for it, exactly
+  // as ixmaps.map() does). The builder's own methods with different
+  // semantics — layer, view, options, require, attribution, on — keep
+  // theirs and are not overridden.
+  for (const m of ['replace', 'add', 'remove', 'removeTheme', 'replaceTheme', 'changeThemeStyle', 'setThemeStyle',
+    'refreshTheme', 'redrawTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'resize',
+    'loadProject', 'project', 'setThemeVisible', 'setThemeTimeFrame', 'show', 'hide', 'getZoom', 'getThemeObj',
+    'getThemes', 'theme', 'setView']) {
+    if (!MapBuilder.prototype[m]) {
+      MapBuilder.prototype[m] = function (...args) {
+        return mapHandle(this.mapOptions && this.mapOptions.name)[m](...args);
+      };
+    }
+  }
+
   // named createMap (not Map) so it doesn't shadow the built-in ES6 Map
   // class used throughout this file — a real bug caught during testing
   // (every `new Map()` below silently resolved to *this* function instead)
@@ -5179,6 +5478,8 @@
   // earlier hand-tuned 12.5 drew every symbol 1.2× (with the reference
   // below, 1.3×) smaller than flat.
   const NORMAL_RADIUS_PX = 15;
+  // largest BOX side (px) still drawn as a canvas icon (at 2×), see _buildBoxIcon
+  const BOX_ICON_MAX_PX = 2048;
   // Flat's own map scale, which dynamic object scaling compares with
   // normalSizeScale (mapscript2.js 2849: dx = nTrueMapScale · nZoomScale /
   // nNormalSizeScale), read from a real flat page: the generic Mercator
@@ -5425,6 +5726,16 @@
 
   function valueRadius(value, zoom, style, mapOptions, flags, maxSizeValue) {
     const zoomFactor = objectZoomFactor(zoom, mapOptions);
+    // FIXSIZE (a symbol chart; PLOT / GRIDSIZE size their markers
+    // themselves): one radius for every item, whatever its value — the
+    // normal radius ÷ normalsizevalue, half of it for BUBBLE (maptheme.js
+    // 20711, 21847; measured on flat: PNRR "details", r = 1.5 units at
+    // scale 0.1)
+    if (flags && flags.has('FIXSIZE') && !flags.has('PLOT') && !flags.has('GRIDSIZE')) {
+      const fixed = NORMAL_RADIUS_PX * (styleNum(style.scale) || 1) / (styleNum(style.normalsizevalue) || 1)
+        * (flatChartBranch(flags) === 'bubble' ? 0.5 : 1);
+      return Math.max(VALUE_RADIUS_MIN, Math.min(VALUE_RADIUS_MAX, fixed * zoomFactor));
+    }
     // Real default (maptheme.js ~line 5059) when the theme sets no
     // normalsizevalue: the dataset's own max value on the bound size
     // field (maxSizeValue, from LayerRuntime._prepare), not a fixed
@@ -5629,6 +5940,8 @@
     const field = binding.size ? binding.size
       : (symbols && !flags.has('CATEGORICAL') && !flags.has('AGGREGATE') && binding.value && !String(binding.value).includes('|') ? binding.value : null);
     if (!field) return undefined;
+    // "$item$": every record counts 1
+    if (field === '$item$') return features.length ? 1 : 0;
     return features.reduce((max, f) => {
       const v = parseFloat(f.properties[field]);
       return isNaN(v) ? max : Math.max(max, v);
@@ -6228,6 +6541,13 @@
   // researched safe range (~1480-2980 distinct 48px icons before a real
   // device's WebGL MAX_TEXTURE_SIZE is at risk).
   const ICON_ATLAS_RESET_AFTER = 3000;
+  // The same reset by icon AREA: a few large icons (BOX rectangles around
+  // MULTIQUAD grids, hundreds of px each, new sizes at every zoom) fill
+  // deck.gl's 1024 px wide atlas long before 3000 icons — on the PNRR
+  // page a dozen boxes doubled it per zoom step, until it passed WebGL's
+  // MAX_TEXTURE_SIZE (16384) and the boxes drew black. 2 Mpx leaves room
+  // for the atlas's row-packing waste (measured ~2×) below that limit.
+  const ICON_ATLAS_AREA_RESET_AFTER = 2 * 1024 * 1024;
 
   // Shared packing layout for a multi-category group's sub-bubbles — used
   // both to draw the packed icon raster (_buildBubbleIcon) and to position
@@ -6272,6 +6592,56 @@
     };
   }
 
+  // MULTIQUAD / MULTISQUARE (flat maptheme.js 18648-18690): the items at
+  // one position, in drawing order, fill quads around it — the k-th at
+  // square = ⌊√k⌋, (k − square², square) while that is within the square,
+  // else (square, square − (k − square² − square)); once square reaches
+  // gridx, rows of gridx go on upward (k % gridx, ⌊k / gridx⌋). Steps of
+  // 2 · normal radius · rangescale (flat's chart size, measured on the PNRR
+  // page); y up. Returns per item its pixel offset and index, and per
+  // position's first item the extent [minX, minY, maxX, maxY] of the
+  // offsets there (flat sizes the BOX around all of them).
+  function multiQuadOffsets(items, normalRadiusPx, rangeScale, gridX) {
+    const step = 2 * normalRadiusPx * (rangeScale || 1);
+    const count = new Map(), offset = new Map(), index = new Map(), first = new Map(), extent = new Map();
+    for (const d of items) {
+      const c = d.geometry && d.geometry.coordinates;
+      const key = c ? c[0] + ',' + c[1] : '';
+      const k = count.get(key) || 0;
+      count.set(key, k + 1);
+      index.set(d, k);
+      if (k === 0) { first.set(key, d); extent.set(d, [0, 0, 0, 0]); }
+      let x = 0, y = 0;
+      if (k > 0) {
+        const square = Math.floor(Math.sqrt(k));
+        if (square < (gridX || Infinity)) {
+          const line = k - square * square;
+          x = line <= square ? line : square;
+          y = line <= square ? square : square - (line - square);
+        } else {
+          x = k % gridX;
+          y = Math.floor(k / gridX);
+        }
+      }
+      offset.set(d, [x * step, -y * step]);
+      const e = extent.get(first.get(key));
+      e[0] = Math.min(e[0], x * step); e[1] = Math.min(e[1], -y * step);
+      e[2] = Math.max(e[2], x * step); e[3] = Math.max(e[3], -y * step);
+    }
+    return { offset, index, extent };
+  }
+
+  // A pixel offset [dx, dy] (y down) from lngLat at MapLibre zoom `zoom`,
+  // as lng/lat (Web Mercator, 512 px world tiles) — for shapes too large
+  // for an icon, drawn in map coordinates (rebuilt with every refresh).
+  function pixelOffsetLngLat(lngLat, offset, zoom) {
+    const world = 512 * Math.pow(2, zoom);
+    const lat0 = lngLat[1] * Math.PI / 180;
+    const y = (0.5 - Math.log(Math.tan(Math.PI / 4 + lat0 / 2)) / (2 * Math.PI)) * world + offset[1];
+    const lat = (2 * Math.atan(Math.exp((0.5 - y / world) * 2 * Math.PI)) - Math.PI / 2) * 180 / Math.PI;
+    return [lngLat[0] + offset[0] * 360 / world, lat];
+  }
+
   // CHART|SYMBOL|SEQUENCE (flat maptheme.js 21184-21300, 21790-21925,
   // 22296-22395): one symbol per category part of a chart, in category
   // order or sorted (SORT: DOWN biggest first, UP smallest first), parts
@@ -7194,9 +7564,13 @@
   //    set (e.g. roma: summed Pericolosita, normalized to 0..1).
   // (flat's per-item nSize holds a record count in that last case, but it
   // is not what draws a value-based symbol.)
+  // "$item$" (as size or value) is flat's record count: 1 per record — it
+  // is no column (read as one, every record was 0 and a LABEL|TEXTONLY
+  // theme's text 0.08 px high).
   function resolveAggregateValue(binding, flags, props) {
+    if (binding.size === '$item$') return 1;
     if (binding.size) return parseFloat(props[binding.size]) || 0;
-    if (flags.has('CATEGORICAL') || binding.value == null) return 1;
+    if (flags.has('CATEGORICAL') || binding.value == null || binding.value === '$item$') return 1;
     return parseFloat(props[binding.value]) || 0;
   }
 
@@ -7294,7 +7668,12 @@
         key = `${snapped.x}:${snapped.y}`;
       }
       let cell = cells.get(key);
-      if (!cell) { cell = { key, snapped, sumX: 0, sumY: 0, n: 0, value: 0, classValue: 0, value100: 0, series: null, first: f }; cells.set(key, cell); }
+      if (!cell) { cell = { key, snapped, sumX: 0, sumY: 0, n: 0, value: 0, classValue: 0, value100: 0, series: null, first: f, raws: null }; cells.set(key, cell); }
+      // the members' own records, for the tooltip's {{theme.item.data}}
+      // (flat's __add_data tables them, numbered, up to 50)
+      if (f.properties.raw && (!cell.raws || cell.raws.length < 50)) {
+        (cell.raws = cell.raws || []).push(f.properties.raw);
+      }
       cell.sumX += p.x; cell.sumY += p.y; cell.n++;
       cell.value += f.properties.value;
       if (f.properties.classValue !== undefined) cell.classValue += f.properties.classValue;
@@ -7316,7 +7695,8 @@
         // 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 }
+            titleRaw: cell.first.properties.raw || cell.first.properties,
+            ...(cell.raws && cell.raws.length ? { raws: cell.raws } : {}) }
         : 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
@@ -7383,6 +7763,18 @@
       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;
+      // the members' own records, for the tooltip's {{theme.item.data}} —
+      // flat's __add_data tables them (numbered, up to 50) for aggregated
+      // items too; references only, so no copy is made. A member can itself
+      // be a pre-aggregated cluster node, whose records it carries in raws
+      if (!cell.raws) cell.raws = [];
+      if (cell.raws.length < 50) {
+        if (f.properties.raw) cell.raws.push(f.properties.raw);
+        else if (f.properties.raws) for (const r of f.properties.raws) {
+          if (cell.raws.length >= 50) break;
+          cell.raws.push(r);
+        }
+      }
       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
@@ -7397,6 +7789,7 @@
       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 } : {}),
+          ...(cell.raws && cell.raws.length ? { raws: cell.raws } : {}),
           ...(cell.titleRaw ? { titleRaw: cell.titleRaw } : {}) }
       };
     });
@@ -7441,13 +7834,25 @@
     return count;
   }
 
+  // flat matches type flags as substrings (szFlag.match(/SYMBOL/)), so a
+  // "SYMBOLS" flag (PNRR pages) is a SYMBOL chart there. With only the symbol
+  // "label" (maptheme.js 21833: the value as text, TEXTONLY: text alone) it is
+  // the LABEL chart this engine draws as _buildLabelChartLayers.
+  function symbolsFlagCompat(flags, style) {
+    if (!flags.has('SYMBOLS') || flags.has('SYMBOL') || flags.has('LABEL')) return flags;
+    const out = new Set(flags);
+    const symbols = [].concat((style && style.symbols) || []);
+    out.add(symbols.length && symbols.every(v => String(v) === 'label') ? 'LABEL' : 'SYMBOL');
+    return out;
+  }
+
   class LayerRuntime {
     // spec: a normalizeTheme() result — never a raw LayerBuilder
     constructor(spec, fc, mapOptions) {
       this.name = spec.name;
       this.binding = spec.binding;
-      this.flags = spec.flags;
       this.style = spec.style;
+      this.flags = symbolsFlagCompat(spec.flags, spec.style);
       this.meta = spec.meta;
       // GL-PORT COMPAT: retained only for ixmaps.getThemeObj()'s szFilter
       // (real ixmaps-flat global compat shim, see _globalThemeRegistry) —
@@ -7481,6 +7886,7 @@
       // ICON_ATLAS_RESET_AFTER for why this is necessary at all).
       this._iconGeneration = 0;
       this._iconsSinceAtlasReset = 0;
+      this._iconAreaSinceAtlasReset = 0;
       this._prepare();
     }
 
@@ -7503,9 +7909,11 @@
     _cacheIcon(key, icon) {
       if (!this._iconCache.has(key)) {
         this._iconsSinceAtlasReset++;
-        if (this._iconsSinceAtlasReset > ICON_ATLAS_RESET_AFTER) {
+        this._iconAreaSinceAtlasReset += (icon.width || 0) * (icon.height || 0);
+        if (this._iconsSinceAtlasReset > ICON_ATLAS_RESET_AFTER || this._iconAreaSinceAtlasReset > ICON_ATLAS_AREA_RESET_AFTER) {
           this._iconGeneration++;
           this._iconsSinceAtlasReset = 0;
+          this._iconAreaSinceAtlasReset = 0;
         }
       }
       if (this._iconCache.size >= ICON_CACHE_MAX) {
@@ -7646,6 +8054,10 @@
       // a page could in principle use both at once, though no current
       // ported page does.
       this._runtimeFilterExpr = '';
+      // flat's setThemeTimeFrame(id, min, max): records whose style.timefield
+      // value lies in [min, max) — null = no time filter. AND'd with the
+      // filters above in _rebuildActiveFeatures.
+      this._timeFrame = null;
 
       // GRIDSIZE layers (PLOT curves-chart, or its grid-mesh companion)
       // also carry AGGREGATE in their type string, but they bin into a
@@ -7842,6 +8254,44 @@
       this._rebuildActiveFeatures();
     }
 
+    // setThemeTimeFrame: min/max in ms or any Date-parsable value; a null /
+    // NaN bound is open-ended, both null clears the frame.
+    setTimeFrame(min, max) {
+      const toMs = v => (v == null || v === '' ? NaN : (typeof v === 'number' ? v : new Date(v).getTime()));
+      const lo = toMs(min), hi = toMs(max);
+      // flat: with the slider at its start position (frame starts at or
+      // before the earliest record) every item is shown, not just the first window
+      const field = this.binding && this.binding.time;
+      if (field && !isNaN(lo)) {
+        if (this._timeMin === undefined) {
+          let m = Infinity;
+          for (const f of this.features) {
+            const v = f.properties && f.properties[field];
+            const t = typeof v === 'number' ? v : new Date(v).getTime();
+            if (!isNaN(t) && t < m) m = t;
+          }
+          this._timeMin = m;
+        }
+        if (lo <= this._timeMin) { this._timeFrame = null; this._rebuildActiveFeatures(); return; }
+      }
+      this._timeFrame = isNaN(lo) && isNaN(hi) ? null : { min: lo, max: hi };
+      this._rebuildActiveFeatures();
+    }
+
+    // predicate over a record's properties for the active time frame
+    _timePredicate() {
+      const tf = this._timeFrame;
+      if (!tf) return null;
+      const field = this.binding && this.binding.time;
+      if (!field) return null;
+      return props => {
+        const v = props && props[field];
+        const t = typeof v === 'number' ? v : new Date(v).getTime();
+        if (isNaN(t)) return false;
+        return (isNaN(tf.min) || t >= tf.min) && (isNaN(tf.max) || t < tf.max);
+      };
+    }
+
     // `_featuresByCategory` (plain per-category bucketing — NOT yet
     // grid-aggregated; that's a separate, later step gated by AGGREGATE
     // alone, see _computeAggregatedItems) is needed whenever this runtime
@@ -7872,7 +8322,8 @@
     replaceFeatures(fc) {
       // new data → new deck.gl layers (see _dataLayerId)
       this._dataGen = (this._dataGen || 0) + 1;
-      const facetFilters = this.facetFilters, runtimeFilterExpr = this._runtimeFilterExpr;
+      this._timeMin = undefined;
+      const facetFilters = this.facetFilters, runtimeFilterExpr = this._runtimeFilterExpr, timeFrame = this._timeFrame;
       this.binding = this._specBinding;
       this.features = applyField100(filterFlatValues(this._withDensity(fc.features), this.binding, this.flags), this.binding, this.flags, this.style);
       this.binding = field100Binding(this.binding, this.flags);
@@ -7882,6 +8333,7 @@
       this._prepare();
       this.facetFilters = facetFilters;
       this._runtimeFilterExpr = runtimeFilterExpr;
+      this._timeFrame = timeFrame;
       this._rebuildActiveFeatures();
     }
 
@@ -7894,6 +8346,27 @@
     // the next redraw.
     _dataLayerId(base) { return this._dataGen ? `${base}-d${this._dataGen}` : base; }
 
+    // deck.gl compares a layer's data by reference: a new object makes it
+    // re-process every polygon (on the PNRR page ~300 ms per refresh for
+    // 8 000 comuni, at every pan tick). Polygon data that doesn't depend
+    // on the view is therefore handed over as the same object until its
+    // inputs change.
+    _featureCollection() {
+      if (!this._featuresFC || this._featuresFC.features !== this.features) {
+        this._featuresFC = { type: 'FeatureCollection', features: this.features };
+      }
+      return this._featuresFC;
+    }
+    // the same for derived data: build() runs only when an entry of key
+    // (compared by identity) differs from the last call's
+    _cachedPolygonData(slot, key, build) {
+      const last = this[slot];
+      if (last && last.key.length === key.length && last.key.every((v, i) => v === key[i])) return last.data;
+      const data = build();
+      this[slot] = { key, data };
+      return data;
+    }
+
     _usesAggregationIndex() {
       return (this.flags.has('AGGREGATE') || isSymbolChart(this.flags)) && !this.flags.has('GRIDSIZE');
     }
@@ -7905,8 +8378,10 @@
       if (isAggregatedCategoricalChoropleth(this)) {
         const expr = this._runtimeFilterExpr;
         const clauses = Array.from(this.facetFilters.entries());
-        if (!expr && !clauses.length) { this._activeFeatures = null; return; }
-        const pred = expr ? flatFilterPredicate(String(expr)) : null;
+        const timePred = this._timePredicate();
+        if (!expr && !clauses.length && !timePred) { this._activeFeatures = null; return; }
+        const wherePred = expr ? flatFilterPredicate(String(expr)) : null;
+        const pred = wherePred && timePred ? (r => wherePred(r) && timePred(r)) : (wherePred || timePred);
         this._activeFeatures = this.features.map(f => {
           const rows = f.properties && f.properties[AGGREGATED_ROWS];
           if (!rows) return f;
@@ -7924,11 +8399,13 @@
       // comment) if one is active — reusing applyWhereFilter, the SAME
       // parser the layer's load-time .filter(expr) already uses, just
       // invoked again here instead of once at build time.
-      const base = this._runtimeFilterExpr
+      let base = this._runtimeFilterExpr
         ? applyWhereFilter({ type: 'FeatureCollection', features: this.features }, this._runtimeFilterExpr).features
         : this.features;
+      const timePred = this._timePredicate();
+      if (timePred) base = base.filter(f => timePred(f.properties));
       if (this.facetFilters.size === 0) {
-        this._activeFeatures = this._runtimeFilterExpr ? base : null;
+        this._activeFeatures = (this._runtimeFilterExpr || timePred) ? base : null;
       } else {
         const clauses = Array.from(this.facetFilters.entries());
         this._activeFeatures = base.filter(f =>
@@ -8298,10 +8775,11 @@
     //     formatting) instead of an inline SVG chart — one line per present
     //     category, each showing ITS OWN value, never summed across
     //     categories (same rule as the VALUES bubble labels).
-    //   - theme.item.data (a table of the hovered record's raw fields) is
-    //     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.
+    //   - theme.item.data (a table of the hovered record's raw fields)
+    //     tables an individual point's record, and an aggregated item's
+    //     member records (numbered, up to 50 — flat's __add_data does the
+    //     same); only a group without retained records (cluster-level
+    //     groups) 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,
@@ -8317,7 +8795,7 @@
       return title;
     }
 
-    buildTooltipHtml(object) {
+    buildTooltipHtml(object, fDark) {
       // 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;
@@ -8326,11 +8804,16 @@
           'include https://unpkg.com/mustache@4.2.0/mustache.min.js before ixmaps-gl.js.');
         return null;
       }
-      return global.Mustache.render(template, this._buildTooltipContext(object));
+      return youtubeClickToPlay(global.Mustache.render(template, this._buildTooltipContext(object, fDark)));
     }
 
-    _buildTooltipContext(object) {
-      const props = object.properties;
+    _buildTooltipContext(object, fDark) {
+      let props = object.properties;
+      // a FEATURE|CATEGORICAL polygon is the raw data record itself, not the
+      // {raw, cat, value} wrapper the other layer kinds build
+      if (props && !props.raw && (this.flags.has('FEATURE') || this.flags.has('FEATURES')) && this.flags.has('CATEGORICAL')) {
+        props = { raw: props, cat: this._resolveClassIndex(props[this.binding.value]) };
+      }
       const isGroup = !!props.counts;
       const chartHtml = this._renderItemChartHtml(props);
 
@@ -8342,7 +8825,7 @@
           chart: chartHtml,
           item: {
             chart: chartHtml,
-            data: isGroup ? '' : this._renderItemDataTableHtml(props.raw),
+            data: isGroup ? this._renderGroupDataTableHtml(props.raws, fDark) : this._renderItemDataTableHtml(props.raw, fDark),
             value: this._hasValue(isGroup ? props.total : props.value) ? this._formatTooltipValue(isGroup ? props.total : props.value) : '',
             label: isGroup ? '' : (this.categoryDisplayLabels ? (this.categoryDisplayLabels[props.cat] || '') : ''),
             // flat: the item's title is its titlefield value (binding title/
@@ -8485,14 +8968,49 @@
     }
 
     // theme.item.data approximation — a plain field:value table of the
-    // hovered record's own raw properties (individual points only).
-    _renderItemDataTableHtml(raw) {
+    // hovered record's own raw properties (individual points only) — flat's
+    // own row markup (tooltip_mustache.js 568-590, main.css .tooltip): the
+    // field name right-aligned, the value left, a dotted rule above the
+    // value, the table at 0.85em with flat's min-width. Light is flat
+    // exactly (#cccccc labels, #000000 values, dotted black); dark keeps
+    // the same visibility hierarchy inverted - DIM labels, BRIGHT values -
+    // with its own colors, a dotted #555 rule and #888 record pills
+    _renderItemDataTableHtml(raw, fDark) {
       if (!raw) return '';
+      const value = fDark ? '#e0e4ea' : '#000000';
+      const label = fDark ? '#787d85' : '#cccccc';
+      const rule = fDark ? '#555' : 'black';
       const rows = Object.keys(raw)
         .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>`)
+        .map(k => `<tr><td></td><td style="text-align:right;vertical-align:top;color:${label}">${k}</td>` +
+          `<td style="text-align:left;vertical-align:top;color:${value};padding:0 0.2em 0 0.8em;border-top:dotted ${rule} 0.1px">` +
+          `${this._isNumericValue(raw[k]) ? this._formatTooltipValue(raw[k]) : raw[k]}</td></tr>`)
         .join('');
-      return `<table style="font-size:0.95em;border-collapse:collapse">${rows}</table>`;
+      return `<table style="font-size:0.85em;min-width:300px;border-collapse:collapse">${rows}</table>`;
+    }
+
+    // an aggregated item's own records, numbered, up to 50 — like real
+    // flat's __add_data (tooltip_mustache.js 490-570: one numbered block
+    // per record when the item holds more than one). A single-record
+    // group renders like an individual point.
+    _renderGroupDataTableHtml(raws, fDark) {
+      if (!raws || !raws.length) return '';
+      if (raws.length === 1) return this._renderItemDataTableHtml(raws[0], fDark);
+      const value = fDark ? '#e0e4ea' : '#000000';
+      const label = fDark ? '#787d85' : '#cccccc';
+      const rule = fDark ? '#555' : 'black';
+      const pill = fDark ? '#888' : 'black';
+      const rows = raws.slice(0, 50).map((raw, d) =>
+        '<tr><td style="font-size:1em;">&nbsp;</td></tr>' +
+        `<tr><td style="font-size:1.5em;border:solid ${pill} 1px;border-radius:1em;padding:0.1em 0.4em 0em 0.3em">${d + 1}</td></tr>` +
+        Object.keys(raw)
+          .filter(k => k !== 'geometry')
+          .map(k => `<tr><td></td><td style="text-align:right;vertical-align:top;color:${label}">${k}</td>` +
+            `<td style="text-align:left;vertical-align:top;color:${value};padding:0 0.2em 0 0.8em;border-top:dotted ${rule} 0.1px">` +
+            `${this._isNumericValue(raw[k]) ? this._formatTooltipValue(raw[k]) : raw[k]}</td></tr>`)
+          .join('')
+      ).join('');
+      return `<table style="font-size:0.85em;min-width:300px;border-collapse:collapse">${rows}</table>`;
     }
 
     _isNumericValue(v) {
@@ -8619,11 +9137,19 @@
       const cs = this.style.colorscheme;
       const raw = Array.isArray(cs) ? cs[0] : cs;
       const filled = raw !== 'none';
+      // FEATURE|CATEGORICAL: polygons coloured by their category (flat colours
+      // each shape by its class), not one flat fill
+      const byCategory = filled && this.flags.has('CATEGORICAL') && this.categoryIndexByLabel && this.binding.value
+        && this.categoryColorsRgb && this.categoryColorsRgb.length;
+      const catAlpha = Math.round(255 * (styleNum(this.style.fillopacity) || 1));
+      const nodataRgb = parseCssColor(this.style.nodatacolor) || [255, 255, 255];
       const shadow = filled && flatShadowOn(this.style, this.features.length, zoom)
         ? this._buildShadowLayers(hexOrNamedToRgb(raw), zoom, bbox) : [];
       return shadow.concat([new GeoJsonLayer({
         id: this._dataLayerId(`ix-features-${this.name}`),
-        data: { type: 'FeatureCollection', features: this.features },
+        data: this._featureCollection(),
+        // FEATURE|CATEGORICAL polygons carry the data record: hover / click tooltips
+        pickable: !!byCategory,
         // linecolor "none": no outline (a FEATURES theme of points with
         // colorscheme and linecolor "none" draws nothing, as flat)
         stroked: styleLineColor(this.style.linecolor) !== 'none',
@@ -8634,7 +9160,13 @@
         // flat puts fillopacity into the shape's fill-opacity only
         // (maptheme.js 13407, 14071-14078): the outline stays opaque
         // (a fill color's own alpha — rgba(…, 0.5) — times fillopacity)
-        getFillColor: filled ? [...hexOrNamedToRgb(raw).slice(0, 3), Math.round(255 * cssColorAlpha(raw) * (styleNum(this.style.fillopacity) || 1))] : [0, 0, 0, 0],
+        ...(byCategory ? { updateTriggers: { getFillColor: JSON.stringify(this.categoryColorsRgb) } } : {}),
+        getFillColor: byCategory
+          ? f => {
+            const cat = this._resolveClassIndex(f.properties[this.binding.value]);
+            return [...(cat != null ? this.categoryColorsRgb[cat] : nodataRgb).slice(0, 3), catAlpha];
+          }
+          : filled ? [...hexOrNamedToRgb(raw).slice(0, 3), Math.round(255 * cssColorAlpha(raw) * (styleNum(this.style.fillopacity) || 1))] : [0, 0, 0, 0],
         getLineColor: this.style.linecolor
           ? withAlpha(hexOrNamedToRgb(styleLineColor(this.style.linecolor)), cssColorAlpha(styleLineColor(this.style.linecolor)))
           : [130, 130, 130],
@@ -8708,8 +9240,8 @@
     // single winning class, so no `cat`/tooltip chart line, just the
     // blended color directly); AGGREGATE CATEGORICAL on one field — the
     // dominant category of each polygon's records (aggregatedCategoricalClass).
-    // A plain CATEGORICAL choropleth (exact match of one row's value) is not
-    // implemented. Geometry + properties are already the joined
+    // A plain CATEGORICAL choropleth matches the raw value of the polygon's
+    // row against the category labels. Geometry + properties are already the joined
     // FeatureCollection from joinChoroplethFeatures. `zoom` is only used
     // for style.fillopacity:"auto" (see resolveAutoFillOpacity) — every
     // other branch here is zoom-independent.
@@ -8735,65 +9267,76 @@
       // AGGREGATE CATEGORICAL: every polygon's parts and dominant class
       // (aggregatedCategoricalClass), the biggest part per class over all
       // polygons for the opacity (flat's nMaxA)
-      const aggCat = isAggregatedCategoricalChoropleth(this) && this.categoryIndexByLabel;
-      let aggOf = null, aggMaxA = null;
-      if (aggCat) {
-        const nCats = this.categoryLabels.length;
-        aggOf = new Map();
-        aggMaxA = new Array(nCats).fill(0);
-        source.forEach(f => {
-          const rows = f.properties && f.properties[AGGREGATED_ROWS];
-          if (!rows) return;
-          const agg = aggregatedCategoricalClass(rows, this.binding, this.flags, this.categoryIndexByLabel, nCats);
-          if (!agg) return;
-          aggOf.set(f, agg);
-          agg.parts.forEach((v, i) => { if (v > aggMaxA[i]) aggMaxA[i] = v; });
-        });
-      }
-      const data = source.map(f => {
+      // the polygons' classes don't depend on the view or on marked
+      // classes (those only change the colors, see updateTriggers below):
+      // the data is rebuilt only when its inputs change
+      const dataKey = [source, this._dataGen, this.categoryIndexByLabel, this.partsA, this._classSeparate,
+        dopacityActive ? baseOpacity : null, JSON.stringify(this.style), JSON.stringify(this.binding)];
+      const collection = this._cachedPolygonData('_choroplethData', dataKey, () => {
+        const aggCat = isAggregatedCategoricalChoropleth(this) && this.categoryIndexByLabel;
+        let aggOf = null, aggMaxA = null;
         if (aggCat) {
-          const agg = aggOf.get(f);
-          return {
-            type: 'Feature',
-            geometry: f.geometry,
-            properties: {
-              // no part above 0: no item in flat, not painted
-              value: agg ? agg.value : undefined, raw: agg ? f.properties : {}, cat: agg ? agg.index : null, parts: agg ? agg.parts : undefined,
-              dopacityAlpha: agg && dopacityActive ? dominantDopacityAlpha(this.style, this.flags, agg.value, aggMaxA[agg.index]) : null
-            }
-          };
-        }
-        if (isComposeColor) {
-          return {
-            type: 'Feature',
-            geometry: f.geometry,
-            properties: { raw: f.properties, composedColor: this._resolveComposedColor(f.properties) }
-          };
+          const nCats = this.categoryLabels.length;
+          aggOf = new Map();
+          aggMaxA = new Array(nCats).fill(0);
+          source.forEach(f => {
+            const rows = f.properties && f.properties[AGGREGATED_ROWS];
+            if (!rows) return;
+            const agg = aggregatedCategoricalClass(rows, this.binding, this.flags, this.categoryIndexByLabel, nCats);
+            if (!agg) return;
+            aggOf.set(f, agg);
+            agg.parts.forEach((v, i) => { if (v > aggMaxA[i]) aggMaxA[i] = v; });
+          });
         }
-        if (isDominant) {
-          const dom = this._resolveDominantClass(f.properties);
-          const value = dom ? dom.value : undefined;
+        const data = source.map(f => {
+          if (aggCat) {
+            const agg = aggOf.get(f);
+            return {
+              type: 'Feature',
+              geometry: f.geometry,
+              properties: {
+                // no part above 0: no item in flat, not painted
+                value: agg ? agg.value : undefined, raw: agg ? f.properties : {}, cat: agg ? agg.index : null, parts: agg ? agg.parts : undefined,
+                dopacityAlpha: agg && dopacityActive ? dominantDopacityAlpha(this.style, this.flags, agg.value, aggMaxA[agg.index]) : null
+              }
+            };
+          }
+          if (isComposeColor) {
+            return {
+              type: 'Feature',
+              geometry: f.geometry,
+              properties: { raw: f.properties, composedColor: this._resolveComposedColor(f.properties) }
+            };
+          }
+          if (isDominant) {
+            const dom = this._resolveDominantClass(f.properties);
+            const value = dom ? dom.value : undefined;
+            return {
+              type: 'Feature',
+              geometry: f.geometry,
+              properties: {
+                value, raw: f.properties, cat: dom ? dom.index : null,
+                dopacityAlpha: dopacityActive ? this._resolveDopacityAlpha(f, value, baseOpacity) : null
+              }
+            };
+          }
+          // a polygon without a data row is no item in flat: no value
+          const hasRow = f.properties && Object.keys(f.properties).length > 0;
+          // CATEGORICAL matches the raw value against the category labels
+          // (a text value has no numeric form: flatNumber would give NaN)
+          const rawVal = hasRow ? f.properties[this.binding.value] : undefined;
+          const value = this.categoryIndexByLabel ? rawVal : (hasRow ? flatNumber(rawVal, this.flags) : NaN);
+          const cat = this._resolveClassIndex(value);
           return {
             type: 'Feature',
             geometry: f.geometry,
             properties: {
-              value, raw: f.properties, cat: dom ? dom.index : null,
+              value, raw: f.properties, cat,
               dopacityAlpha: dopacityActive ? this._resolveDopacityAlpha(f, value, baseOpacity) : null
             }
           };
-        }
-        // a polygon without a data row is no item in flat: no value
-        const hasRow = f.properties && Object.keys(f.properties).length > 0;
-        const value = hasRow ? flatNumber(f.properties[this.binding.value], this.flags) : NaN;
-        const cat = this._resolveClassIndex(value);
-        return {
-          type: 'Feature',
-          geometry: f.geometry,
-          properties: {
-            value, raw: f.properties, cat,
-            dopacityAlpha: dopacityActive ? this._resolveDopacityAlpha(f, value, baseOpacity) : null
-          }
-        };
+        });
+        return { type: 'FeatureCollection', features: data };
       });
       // A marked class (legend row click / ixmaps.markThemeClass) as real
       // ixmaps-flat shows it on a choropleth (MapTheme.markClass,
@@ -8815,9 +9358,13 @@
         return evidenceMode === 'isolate' ? 'hide' : 'gray';
       };
       const grayOf = ([r, g, b]) => { const y = Math.round(0.299 * r + 0.587 * g + 0.114 * b); return [y, y, y]; };
+      // deck.gl re-runs the color accessors only for new data or a changed trigger
+      const colorKey = JSON.stringify([[...this._markedClasses], !!this._onMarksChanged, evidenceMode,
+        this.categoryColorsRgb, fallbackRgb, classAlpha, lineRgb]);
       return [new GeoJsonLayer({
         id: this._dataLayerId(`ix-choropleth-${this.name}`),
-        data: { type: 'FeatureCollection', features: data },
+        data: collection,
+        updateTriggers: { getFillColor: colorKey, getLineColor: colorKey },
         pickable: true,
         stroked: true,
         filled: true,
@@ -9890,7 +10437,11 @@
         this._valueMedian = sorted[Math.floor((sorted.length - 1) / 2)];
       }
 
-      this._aggregateStatsCache = { zoom, outlier, normalize, breaks };
+      // flat's default normalsizevalue is the largest aggregated size (maptheme.js 5021-5022)
+      let sizeMax = 0;
+      for (const v of rawSizeTotals) if (Math.abs(v) > sizeMax) sizeMax = Math.abs(v);
+
+      this._aggregateStatsCache = { zoom, outlier, normalize, breaks, sizeMax };
       return this._aggregateStatsCache;
     }
 
@@ -9914,6 +10465,12 @@
       // _computeAggregatedItems below — a plain (non-AGGREGATE)
       // BUBBLE/CHART theme never reads them.
       if (this.flags.has('AGGREGATE')) this._ensureClusterIndices(zoom);
+      // AGGREGATE sums without a normalsizevalue: flat's default is the
+      // largest aggregated value (defaultNormalSizeValue leaves it unset, the
+      // sizes depend on the aggregation)
+      if (this.flags.has('AGGREGATE') && !this.flags.has('CATEGORICAL') && !styleNum(this.style.normalsizevalue) && !this.binding.size) {
+        this._maxSizeValue = this._ensureAggregateStats(zoom).sizeMax || undefined;
+      }
       let { individual, groups } = this._computeAggregatedItems(bbox, zoom);
       // Far-hemisphere cull under globe projection — see
       // isOnVisibleHemisphere's own comment for why this is needed at
@@ -9930,7 +10487,7 @@
       }
       const layers = [];
 
-      if (this.flags.has('NOOUTLIER') || this.flags.has('NORMALIZE') || this._rangeClassed) {
+      if (this.flags.has('NOOUTLIER')|| this.flags.has('NORMALIZE') || this._rangeClassed) {
         const stats = this._ensureAggregateStats(zoom);
 
         // the quantity NOOUTLIER/NORMALIZE/classes act on: the separate
@@ -10041,6 +10598,10 @@
       // _buildTooltipContext's own `isGroup` check already uses).
       const sizeValueOf = d => d.properties.counts ? d.properties.total : d.properties.value;
       const combined = individual.concat(groups).sort((a, b) => sizeValueOf(a) - sizeValueOf(b));
+      // maxcharts: like the flat engine (maptheme.js nMaxCharts), draw only the
+      // biggest N items — combined is ascending, so drop from the front
+      const maxCharts = Math.round(styleNum(this.style.maxcharts)) || 0;
+      if (maxCharts > 0 && combined.length > maxCharts) combined.splice(0, combined.length - maxCharts);
       if (this.flags.has('USER')) {
         const userLayers = this._buildUserChartLayers(combined, liveZoom, sizeValueOf);
         if (userLayers) return layers.concat(userLayers);
@@ -10063,7 +10624,16 @@
       const itemRgb = d => this.categoryColorsRgb[d.properties.counts ? dominant(d.properties.counts) : d.properties.cat] || [128, 128, 128];
       const radiusOf = d => valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue);
       // align / offsetx / offsety: the whole chart moves (flatChartAlignOffset)
-      const alignOf = this._chartAlignFn(liveZoom, radiusOf);
+      // MULTIQUAD / MULTISQUARE: the items at one position side by side
+      // (multiQuadOffsets), added to the chart position
+      const baseAlign = this._chartAlignFn(liveZoom, radiusOf);
+      const multi = flatFlag(this.flags, 'MULTIQUAD') || flatFlag(this.flags, 'MULTISQUARE')
+        ? multiQuadOffsets(combined, NORMAL_RADIUS_PX * objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(this.style.scale) || 1),
+          styleNum(this.style.rangescale) || 1, styleNum(this.style.gridx) || 0)
+        : null;
+      const alignOf = multi
+        ? Object.assign(d => { const a = baseAlign(d), m = multi.offset.get(d) || [0, 0]; return [a[0] + m[0], a[1] + m[1]]; }, { active: true })
+        : baseAlign;
 
       // SHADOW (style.shadow, flat's gate: maxshadow, shadowupper/lower — flatShadowOn): a soft
       // drop shadow under each symbol, see _getShadowIcon
@@ -10145,28 +10715,42 @@
       // (#888888) over a half-opaque white halo (stroke font/7); its first
       // baseline one font below the box (BOTTOMTITLE) or 0.7 font above it.
       // Box and title are removed outside boxupper/boxlower.
+      // Flat draws box and title in the chart group, which is scaled by
+      // style.scale: the units below are u · scale. Its size measure W is
+      // the chart's width (2r; with MULTIQUAD the width of the whole grid
+      // at the position, the box enclosing all of it); flat's chart size
+      // is 30 units.
       const boxShown = flatFlag(this.flags, 'BOX') && !boxHiddenByScale(this.style, liveZoom);
       const circular = flatFlag(this.flags, 'CIRCULAR');
-      const unitPx = objectZoomFactor(liveZoom, this.mapOptions);
+      const unitPx = objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(this.style.scale) || 1);
       const boxMarginU = styleNum(this.style.boxmargin) || 2;
       const titleShown = boxShown && flatFlag(this.flags, 'TITLE') && !!this.binding.title;
       const titleFontPx = 5 * unitPx * (styleNum(this.style.textscale) || styleNum(this.style.valuescale) || 1);
+      // flat: fill-opacity (boxopacity || 1) on the raw style value — the
+      // usual string "0" is transparent; typed here, a given 0 is too
+      const boxOpacity = isNaN(styleNum(this.style.boxopacity)) ? 1 : styleNum(this.style.boxopacity);
       const bottomTitle = flatFlag(this.flags, 'BOTTOMTITLE');
       const alignRight = /right/.test(String(this.style.align || ''));
-      const boxLayout = boxShown ? combined.map(d => {
+      // with MULTIQUAD only the first item of a position gets its box/title
+      const boxLayout = boxShown ? combined.filter(d => !multi || multi.index.get(d) === 0).map(d => {
         const r = valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue);
-        const margin = Math.min(2 * boxMarginU * unitPx, boxMarginU * r / 15);
+        const ext = multi ? multi.extent.get(d) : [0, 0, 0, 0];
+        const chart = [ext[0] - r, ext[1] - r, ext[2] + r, ext[3] + r];
+        const w = chart[2] - chart[0];
+        const margin = Math.min(2 * boxMarginU * unitPx, boxMarginU * w / 30);
         const boxR = circular ? r * 1.1 + margin : r;
         let title = null;
         if (titleShown) {
           const text = this._itemTitle(d.properties);
           if (text) {
             const f = titleFontPx;
-            const lines = wrapTitleLines(text, f, boxR * 2).split('\n');
+            const lines = wrapTitleLines(text, f, circular ? boxR * 2 : w).split('\n');
             const width = Math.max(...lines.map(l => titleTextWidth(l, f)));
             // first baseline; lines go down one font each
-            const base = bottomTitle ? boxR + f : -boxR - 0.7 * f - (lines.length - 1) * f;
-            const x = circular ? unitPx / 2 : (alignRight ? r : -r);
+            const base = circular
+              ? (bottomTitle ? boxR + f : -boxR - 0.7 * f - (lines.length - 1) * f)
+              : (bottomTitle ? chart[3] + f : chart[1] - 0.7 * f - (lines.length - 1) * f);
+            const x = circular ? unitPx / 2 : (alignRight ? chart[2] : chart[0]);
             const anchor = circular ? 'middle' : (alignRight ? 'end' : 'start');
             const x0 = anchor === 'middle' ? x - width / 2 : anchor === 'end' ? x - width : x;
             // arial: ascent 0.905, descent 0.212 of the font size
@@ -10176,16 +10760,16 @@
         }
         let rect = null;
         if (!circular) {
-          const e = [-r, -r, r, r];
+          const e = chart.slice();
           // with a title flat trims 0.1 font off the top of chart + title
           if (title) { e[0] = Math.min(e[0], title.extent[0]); e[1] = Math.min(e[1], title.extent[1]) + 0.1 * titleFontPx; e[2] = Math.max(e[2], title.extent[2]); e[3] = Math.max(e[3], title.extent[3]); }
           rect = [e[0] - margin, e[1] - margin, e[2] + margin, e[3] + margin];
         }
-        return { d, r, boxR, rect, title };
+        return { d, r, w, boxR, rect, title };
       }) : null;
       if (boxShown && circular) {
         const boxRgb = hexOrNamedToRgb(this.style.boxcolor || '#eeeeee');
-        const boxAlpha = Math.round(255 * (styleNum(this.style.boxopacity) || 1));
+        const boxAlpha = Math.round(255 * boxOpacity);
         const borderRgb = hexOrNamedToRgb(this.style.bordercolor || '#dddddd');
         // ScatterplotLayer has no pixel offset: a moved chart (align,
         // offsetx/offsety) gets its circle as an icon
@@ -10218,20 +10802,47 @@
         const borderStyle = String(this.style.borderstyle || '');
         const boxLook = {
           fill: this.style.boxcolor || 'white',
-          fillOpacity: styleNum(this.style.boxopacity) || 1,
+          fillOpacity: boxOpacity,
           stroke: borderStyle === 'none' ? null : styleLineColor(this.style.bordercolor) || '#bbbbbb',
           strokeOpacity: /^(solid|dotted|dashed)$/.test(borderStyle) ? 1 : 0.3,
         };
         const borderWidth = styleNum(this.style.borderwidth) || 1;
         const borderRadius = styleNum(this.style.borderradius);
-        boxLayout.forEach(b => {
+        const strokeOf = b => borderWidth * 0.2 * b.w / 30;
+        // a box larger than BOX_ICON_MAX_PX (a MULTIQUAD grid of thousands
+        // of items) would need a huge canvas: it is drawn as a polygon in
+        // map coordinates instead (square corners)
+        const bigBox = b => Math.max(b.rect[2] - b.rect[0], b.rect[3] - b.rect[1]) > BOX_ICON_MAX_PX;
+        const iconBoxes = boxLayout.filter(b => !bigBox(b)), polygonBoxes = boxLayout.filter(bigBox);
+        iconBoxes.forEach(b => {
           b.icon = this._buildBoxIcon(b.rect[2] - b.rect[0], b.rect[3] - b.rect[1],
-            isNaN(borderRadius) ? 0 : borderRadius * Math.min(unitPx, b.r * 2 / 30),
-            borderWidth * 0.2 * b.r * 2 / 30, boxLook);
+            isNaN(borderRadius) ? 0 : borderRadius * Math.min(unitPx, b.w / 30),
+            strokeOf(b), boxLook);
         });
-        layers.push(new IconLayer({
+        if (polygonBoxes.length) {
+          const fillRgb = hexOrNamedToRgb(boxLook.fill);
+          const strokeRgb = boxLook.stroke ? hexOrNamedToRgb(boxLook.stroke) : null;
+          layers.push(new GeoJsonLayer({
+            id: `ix-box-polygons-${this.name}`,
+            data: polygonBoxes.map(b => {
+              const o = alignOf(b.d), c = b.d.geometry.coordinates, r = b.rect;
+              const at = (x, y) => pixelOffsetLngLat(c, [x + o[0], y + o[1]], liveZoom);
+              return { type: 'Feature', properties: { stroke: strokeOf(b) },
+                geometry: { type: 'Polygon', coordinates: [[at(r[0], r[1]), at(r[2], r[1]), at(r[2], r[3]), at(r[0], r[3]), at(r[0], r[1])]] } };
+            }),
+            pickable: false,
+            filled: boxLook.fillOpacity > 0,
+            stroked: !!strokeRgb,
+            getFillColor: [...fillRgb.slice(0, 3), Math.round(255 * boxLook.fillOpacity)],
+            getLineColor: strokeRgb ? [...strokeRgb.slice(0, 3), Math.round(255 * boxLook.strokeOpacity)] : [0, 0, 0, 0],
+            getLineWidth: f => f.properties.stroke,
+            lineWidthUnits: 'pixels',
+            parameters: ICON_LAYER_GLOBE_PARAMETERS
+          }));
+        }
+        if (iconBoxes.length) layers.push(new IconLayer({
           id: `ix-box-${this.name}-g${this._iconGeneration}`,
-          data: boxLayout, pickable: false,
+          data: iconBoxes, pickable: false,
           getPosition: b => b.d.geometry.coordinates,
           getIcon: b => b.icon,
           // the icon is drawn at 2× with a stroke padding around the box
@@ -10251,7 +10862,9 @@
           ? this._buildBubbleIcon(d.properties.counts, this.categoryColorsRgb, this._groupIsolation(d))
           : this._buildSingleIcon(this.categoryColorsRgb[d.properties.cat], fillOpacity, this._resolveSymbolShape(d.properties), singleBorderColorRgb, singleBorderWidthPx),
         getSize: d => valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue) * 2,
-        getColor: d => [255, 255, 255, this._iconAlpha(d)],
+        // group icons bake a fixed 0.9 alpha; an explicit fillopacity scales it
+        // so a near-transparent theme doesn't show opaque 1-px-cell clusters
+        getColor: d => [255, 255, 255, Math.round(this._iconAlpha(d) * (d.properties.counts && this.style.fillopacity != null ? fillOpacity : 1))],
         ...(alignOf.active ? { getPixelOffset: alignOf } : {}),
         sizeUnits: 'pixels',
         billboard: true,
@@ -10816,6 +11429,7 @@
   //  - themes: getThemeObj (flat's theme object, with its data table and
   //    the items on the map), getThemeDefinitionObj, getThemes,
   //    changeThemeStyle / removeTheme / setBasemapOpacity (map name first),
+  //    setThemeTimeFrame (themeId, min, max),
   //    refreshTheme, markThemeClass / unmarkThemeClass
   //  - data: ixmaps.data (facets: getFacets, showFacets, …), the
   //    embeddedSVG.window tables (setExternalData is with the data loading)
@@ -10859,22 +11473,73 @@
     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.
+  // flat's ixmaps.themeApi (htmlgui_flat.js 1112-1196): the theme handle a
+  // page gets from map().theme(name) — changeStyle is flat's canonical
+  // global changeThemeStyle(szThemeName, szStyle, szFlag) (htmlgui.js 2050)
+  // in handle form; show / hide / toggle are setThemeVisible, remove the map
+  // handle's. flat's own markClass delegates 3-arg — a stale call against
+  // htmlgui.js's 2-arg markThemeClass (2196) — the canonical form is used
+  // here. Theme ids are global (the registry), so the map binding only
+  // matters for replace.
+  function themeApi(szMap, szTheme) {
+    this.szMap = szMap || null;
+    this.szTheme = szTheme || null;
+  }
+  themeApi.prototype = {
+    changeStyle(szStyle, szFlag) { compatChangeThemeStyle(this.szTheme, szStyle, szFlag); return this; },
+    markClass(nClass) { markThemeClass(this.szTheme, nClass); return this; },
+    unmarkClass(nClass) { unmarkThemeClass(this.szTheme, nClass); return this; },
+    show() { mapHandle(this.szMap).setThemeVisible(this.szTheme, true); return this; },
+    hide() { mapHandle(this.szMap).setThemeVisible(this.szTheme, false); return this; },
+    toggle() {
+      const rt = _globalThemeRegistry.get(this.szTheme);
+      mapHandle(this.szMap).setThemeVisible(this.szTheme, rt ? !!rt._hidden : false);
+      return this;
+    },
+    remove() { mapHandle(this.szMap).remove(this.szTheme); return this; },
+    replace(theme, flag) { mapHandle(this.szMap).replaceTheme(this.szTheme, theme, flag); return this; }
+  };
+
+  // flat's ixmaps.map() / ixmaps.api(szMap) — the running map's handle
+  // (htmlgui.js 173ff, htmlgui_flat.js mapApi 1283). Its methods act on the
+  // map named by szMap (its Map() options name) or, without a name, 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;
-    };
+    'refreshTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible', 'setThemeTimeFrame', 'attribution'];
+  const _mapHandles = Object.create(null);
+  function makeMapHandle(szMap) {
+    const h = {};
+    const api = () => (szMap && _mapApis[szMap]) || _lastMapApi;
+    for (const m of MAP_HANDLE_METHODS) {
+      h[m] = (...args) => {
+        const a = api();
+        if (a) { const r = a[m](...args); return r === a ? h : r; }
+        _mapReady.then(ready => ready[m](...args));
+        return h;
+      };
+    }
+    h.getZoom = () => { const a = api(); return a ? a.getZoom() : undefined; };
+    h.getThemeObj = id => getThemeObj(id);
+    // flat's mapApi.theme(szTheme) (htmlgui_flat.js 1571): the theme handle
+    h.theme = szTheme => new themeApi(szMap, szTheme);
+    // flat's mapApi aliases (htmlgui_flat.js 1286+): show/hide a theme,
+    // redrawTheme (refreshTheme here), project (loadProject), getThemes(),
+    // setView (view, both flat's object form and (array, zoom))
+    h.show = id => h.setThemeVisible(id, true);
+    h.hide = id => h.setThemeVisible(id, false);
+    h.redrawTheme = id => h.refreshTheme(id);
+    h.project = (...a) => h.loadProject(...a);
+    h.setView = (...a) => h.view(...a);
+    h.getThemes = () => [...new Set(_globalThemeRegistry.values())].map(rt => getThemeObj(themeIdOf(rt))).filter(Boolean);
+    return h;
+  }
+  const _mapHandle = makeMapHandle(null);
+  function mapHandle(szMap) {
+    if (!szMap) return _mapHandle;
+    if (!_mapHandles[szMap]) _mapHandles[szMap] = makeMapHandle(szMap);
+    return _mapHandles[szMap];
   }
-  _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
@@ -11090,6 +11755,7 @@
     const style = Object.assign({}, rt.style);
     if (rt.binding.size && !style.sizefield) style.sizefield = rt.binding.size;
     if (rt.binding.title && !style.titlefield) style.titlefield = rt.binding.title;
+    if (rt.binding.time && !style.timefield) style.timefield = rt.binding.time;
     style.type = rt.flags.typeString != null ? rt.flags.typeString : [...rt.flags].join('|');
     const data = Object.assign({}, rt._definition && rt._definition.data);
     if (!data.name) data.name = themeDataName(rt);
@@ -11448,10 +12114,44 @@
     return _lastMapApi.loadProject(src, flags);
   }
 
+  // flat's global compat forms come in two arities: the canonical
+  // theme-first signatures — changeThemeStyle(szThemeName, szStyle, szFlag)
+  // (htmlgui.js 2050, with its duplicate-leading shift, 2052),
+  // removeTheme(szThemeId) (1884), setBasemapOpacity(nOpacity, szMode)
+  // (1409) — and the older map-first pages calling
+  // (null|szMap, szId, ...) — PNRR passes an explicit null. Arity tells
+  // them apart; theme ids are global (the registry), so the leading map
+  // argument only matters for setBasemapOpacity, where a registered map
+  // name targets that map and null or an unknown name the last built one.
+  function themeStyleArgs(a) {
+    if (a.length >= 4) a = a.slice(1);
+    else if (a[0] === a[1]) a = a.slice(1);
+    return a;
+  }
+  function compatChangeThemeStyle(...a) {
+    const [szId, szStyle, szFlag] = themeStyleArgs(a);
+    return _mapHandle.changeThemeStyle(szId, szStyle, szFlag);
+  }
+  function compatRemoveTheme(...a) {
+    return _mapHandle.remove(a.length >= 2 ? a[1] : a[0]);
+  }
+  function compatSetBasemapOpacity(...a) {
+    if (a.length >= 3) {
+      const api = (a[0] && _mapApis[a[0]]) || _lastMapApi;
+      if (api) api.setBasemapOpacity(a[1], a[2]);
+      return;
+    }
+    return _mapHandle.setBasemapOpacity(a[0], a[1]);
+  }
+
   global.ixmaps = {
-    layer, Map: createMap, setExternalData: setExternalDataBridge, getThemeObj, data: ixmapsData,
+    layer, Layer: layer, Map: createMap, setExternalData: setExternalDataBridge, getThemeObj, data: ixmapsData,
     szResourceBase: ixmapsSzResourceBase, getProjectString, setProjectJSON, loadProject,
     markThemeClass, unmarkThemeClass, getBoundingBox, setTitle, setTitleBox, refreshTheme, formatValue: flatFormatValue,
+    // flat's ixmaps.__formatValue (ui/js/tools/legend.js 451-553) — pages call
+    // it for statistics/legend values; legend's own variant differs from
+    // format.js's only in the SPACE flag, which flatFormatValue covers too
+    __formatValue: flatFormatValue,
     map: mapHandle, getZoom, getThemeDefinitionObj, embeddedSVG,
     // flat's theme list: the theme objects of every theme
     getThemes: () => [...new Set(_globalThemeRegistry.values())].map(rt => getThemeObj(themeIdOf(rt))).filter(Boolean),
@@ -11468,9 +12168,11 @@
     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),
+    changeThemeStyle: compatChangeThemeStyle,
+    removeTheme: compatRemoveTheme,
+    // flat's time slider: show the records of a theme (null = all themes) whose timefield lies in [min, max)
+    setThemeTimeFrame: (szId, nMin, nMax) => _mapHandle.setThemeTimeFrame(szId, nMin, nMax),
+    setBasemapOpacity: compatSetBasemapOpacity,
     // this engine's version (flat's own ixmaps.version numbers flat)
     glVersion: IXMAPS_GL_VERSION,
     // flat always has this page hook (its layer legend tool defines it,
@@ -11494,8 +12196,8 @@
   // 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, tooltipTable, legendRowLabels, scaleDenom, cssColorAlpha, aggregatedCategoricalClass, dominantDopacityAlpha, isAggregatedCategoricalChoropleth, computeBubblePackLayout, isolatedBubblePackLayout, sequenceLayout,
-    normalizeTheme, projectThemeToDefinition, withoutProjectCode, groupRecordCount, resolveBasemapStyleUrl, resolveMapTypeColor, LayerBuilder, LayerRuntime, typeStyleNumbers, styleNum,
+    IXMAPS_GL_VERSION, youtubeClickToPlay, symbolsFlagCompat, tooltipTable, legendRowLabels, scaleDenom, cssColorAlpha, aggregatedCategoricalClass, dominantDopacityAlpha, isAggregatedCategoricalChoropleth, computeBubblePackLayout, isolatedBubblePackLayout, sequenceLayout, multiQuadOffsets, pixelOffsetLngLat,
+    normalizeTheme, projectThemeToDefinition, withoutProjectCode, groupRecordCount, resolveBasemapStyleUrl, resolveMapTypeColor, LayerBuilder, LayerRuntime, MapBuilder, typeStyleNumbers, styleNum,
     resolveScriptUrl, isTrustedScriptUrl, loadProcessingScript, loadBrokerData, applyBrokerThemePatch, makeBrokerTheme,
     equalIntervalBreaks, quantileBreaks, naturalBreaks, evenStrideSample, jenksBreakValues, partsFromBreakValues, resolvePartsClass,
     computeAlphaStats, computeMultiFieldClasses, computeDominantStats, resolveDominantClass, computeComposeColorStats,
@@ -11504,7 +12206,7 @@
     flatToMapLibreZoom, mapLibreToFlatZoom, scaleDenominatorAt, resolveZoomReference, resolveAggregationPx, valuesHiddenByScale,
     fetchLayerData, parseCsvText, dataTableRows, geometryRowsToFeatureCollection, filterFlatValues, applyField100, field100Binding, rangeClassLegendTotals, resolveAggregateValue, classValueSeparate, cellAggregatedValues, oneHot, groupCoLocated, aggregateOnGrid, GridAggregateIndex, flatRangeParts, aggregateField100, valueRadius, itemPlotGeometry, itemAnchor, objectZoomFactor, resolveZoomReference, defaultNormalSizeValue,
     applyWhereFilter, joinChartPositions, flatLookupKey, flatShapeCenter, chartHiddenByScale, glowHiddenByScale, isSymbolChart, flatChartAlignOffset, flatChartBranch, flatValueText, categoryValueRecord, flatDerivateRgb, flatChartTextRgb, flatGroupedValue, flatNoBreaks, featuresHiddenByScale, boxHiddenByScale, flatShadowOn, snapToAggregationGrid,
-    flatFormatValue,
+    flatFormatValue, themeStyleArgs,
     dataCacheKey, dataCacheDisabled, cachedLayerData, featuresBounds, wantsZoomToExtent, legendIsOn,
   };
   global.__setFilter = __setFilter;