ixmaps-gl 0.2.24 → 0.2.30

package/ixmaps-gl.js

@@ -100,7 +100,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.24';
+  const IXMAPS_GL_VERSION = '0.2.30';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -220,7 +220,7 @@
   let IconLayer, ScatterplotLayer, GeoJsonLayer, MapLibreOverlay, TextLayer, PathLayer, PathStyleExtension;
   // PieSliceLayer (see makePieSliceLayer) and BarShapeLayer
   // (makeBarShapeLayer) are derived from ScatterplotLayer once deck.gl is there
-  let PieSliceLayer, BarShapeLayer;
+  let PieSliceLayer, BarShapeLayer, FlowPathLayer;
 
   // CHART|PIE / DONUT slices (_buildPieLayers): one instance per slice — a
   // ScatterplotLayer circle (billboarded, pixel radius, pixel offset, the
@@ -242,6 +242,111 @@
   // without anti-aliasing between them (a hard partition: no background
   // seam shows between two slices); the circle's rim keeps
   // ScatterplotLayer's own anti-aliasing.
+  // flat's VECTOR|DASH (maptheme.js 18240-18256, the bezier branch):
+  // the flow lines are dashed — one long dash, a small gap — and the
+  // dash pattern MOVES toward the target: flat animates each SVG line's
+  // stroke-dashoffset from d1+d2+random down to random (1-2s, infinite),
+  // the offset decreasing walking the pattern along the path direction.
+  // Here the same in the fragment shader — but deck.gl tessellates a
+  // path into per-SEGMENT quads whose vPathPosition.y restarts at 0 at
+  // every segment vertex (and is in half-stroke-width units, not
+  // pixels), so the pattern is NOT continuous from the segment
+  // coordinate alone. deck's own PathStyleExtension with dashMode
+  // 'path' (HIGH_PRECISION_DASH) supplies the missing cumulative term:
+  // its calculateDashMetrics fills per-segment [distance so far, path
+  // length] and its vertex shader turns it into vDashOffset, making
+  //   alongPath = vPathPosition.y + vDashOffset
+  // continuous across segments (deck's own dash shader uses exactly
+  // this; the pattern is periodic, so the mod() in vDashOffset is
+  // seamless). The extension's own gap stays 0 (getDashArray's second
+  // component — it renders the line solid); THIS layer's
+  // DECKGL_FILTER_COLOR discards the moving gap: the solid length and
+  // flat's random per-arc phase as an instanced attribute, a time
+  // uniform advanced by the wall clock (one full dash cycle every 2s),
+  // and fragments outside the moving dash window discarded — the layers
+  // themselves are NOT rebuilt per frame. The discard skips the picking
+  // pass (picking.isActive): flat's dashed SVG line is hover-tested
+  // across its gaps too, so the arcs keep their tooltips while the
+  // dash runs
+  function makeFlowPathLayer(Base) {
+    // deck.gl 9: a layer's custom uniforms live in shader MODULES — an
+    // std140 block named <module>Uniforms, its layout declared by the
+    // module's own GLSL and uniformTypes, values pushed per draw via
+    // setShaderModuleProps (the picking module's picking.isActive works
+    // exactly the same way). A plain GLSL uniform would have no backing
+    // buffer, and deck 8's state.model.setUniforms() no longer exists.
+    const FLOW_MODULE = {
+      name: 'flow',
+      uniformTypes: { uFlowTime: 'f32' },
+      defaultUniforms: { uFlowTime: 0 },
+      vs: 'layout(std140) uniform flowUniforms { float uFlowTime; } flow;',
+      fs: 'layout(std140) uniform flowUniforms { float uFlowTime; } flow;'
+    };
+    class Layer extends Base {
+      getShaders() {
+        const shaders = super.getShaders();
+        shaders.modules = (shaders.modules || []).concat(FLOW_MODULE);
+        const inject = Object.assign({}, shaders.inject || {});
+        inject['vs:#decl'] = (inject['vs:#decl'] || '') + `
+in vec2 instanceFlowPhase;
+out vec2 vFlowPhase;
+`;
+        inject['vs:#main-end'] = (inject['vs:#main-end'] || '') + `
+vFlowPhase = instanceFlowPhase;
+`;
+        inject['fs:#decl'] = (inject['fs:#decl'] || '') + `
+in vec2 vFlowPhase;
+`;
+        // before the picking module's own filter; the dash is skipped
+        // there (see the class comment). vDashArray/vDashOffset come
+        // from the PathStyleExtension (see the layer's extensions),
+        // the position along the path is geometry.uv (the path
+        // layer's main sets it to vPathPosition before the filter
+        // runs; the varying itself is NOT redeclared here — the base
+        // shader already declares it, and the injected block lands
+        // before the base source, so a redeclaration is a
+        // redefinition error). uFlowTime comes from the flow module's
+        // block (see FLOW_MODULE)
+        inject['fs:DECKGL_FILTER_COLOR'] = (inject['fs:DECKGL_FILTER_COLOR'] || '') + `
+{
+  float period = vDashArray.x;
+  float pickingActive = 0.0;
+#ifdef MODULE_PICKING
+  pickingActive = picking.isActive;
+#endif
+  if (period > 0.0 && pickingActive < 0.5) {
+    float alongPath = geometry.uv.y + vDashOffset;
+    float pos = fract((alongPath - flow.uFlowTime * period + vFlowPhase.y) / period);
+    if (pos * period > vFlowPhase.x) discard;
+  }
+}
+`;
+        shaders.inject = inject;
+        return shaders;
+      }
+      initializeState() {
+        super.initializeState();
+        this.getAttributeManager().addInstanced({
+          instanceFlowPhase: { size: 2, accessor: 'getFlowPhase', defaultValue: [0, 0] }
+        });
+      }
+      draw(opts) {
+        // one full dash cycle every 2s — flat's animate dur (the bezier
+        // branch); the offset decreases, so the pattern walks toward
+        // the target (alongPath grows along the path). setProps on
+        // the shader inputs; the model's predraw flushes the uniform
+        // buffer when super.draw renders
+        this.setShaderModuleProps({ flow: { uFlowTime: (Date.now() % 2000) / 2000 } });
+        super.draw(opts);
+      }
+    }
+    Layer.layerName = 'FlowPathLayer';
+    Layer.defaultProps = Object.assign({}, Base.defaultProps, {
+      getFlowPhase: { type: 'accessor', value: [0, 0] }
+    });
+    return Layer;
+  }
+
   function makePieSliceLayer(Base) {
     class Layer extends Base {
       getShaders() {
@@ -293,12 +398,15 @@ in vec4 vPieLineColor;
   }
   // in device pixels (fwidth: CSS px per device pixel), so a hairline
   // stays one at any device pixel ratio. Half the outline lies inside
-  // each slice (the other half in its neighbour); below a pixel it fades
-  // in by its width
+  // each slice (the other half in its neighbour). No fade-in by the
+  // width: the browser rasterizes flat's sub-pixel SVG strokes as
+  // hairlines — one device pixel at FULL opacity (Skia's stroke floor,
+  // measured on the ISTAT story: 0.17 CSS px strokes render gray 32) —
+  // so the line keeps full alpha and only its extent grows past 1px
   float pieAA = max(fwidth(pieR), 1e-4);
   float pieH = vPieLineWidth * 0.5 / pieAA;
   float pieDD = pieD / pieAA;
-  float pieLine = pieH > 0.0 ? clamp(min(pieH + 0.5 - pieDD, 2.0 * pieH), 0.0, 1.0) : 0.0;
+  float pieLine = pieH > 0.0 ? clamp(pieH + 0.5 - pieDD, 0.0, 1.0) : 0.0;
   float pieRim = clamp((vPieRadius - pieR) / pieAA + 0.5, 0.0, 1.0);
   color = vec4(mix(color.rgb, vPieLineColor.rgb, pieLine), mix(color.a, vPieLineColor.a * pieRim, pieLine));
   if (pieInner > 0.0) color.a *= clamp((pieR - pieInner) / pieAA + 0.5, 0.0, 1.0);
@@ -503,6 +611,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         ({ IconLayer, ScatterplotLayer, GeoJsonLayer, MapLibreOverlay, TextLayer, PathLayer, PathStyleExtension } = global.deck);
         PieSliceLayer = makePieSliceLayer(ScatterplotLayer);
         BarShapeLayer = makeBarShapeLayer(ScatterplotLayer);
+        FlowPathLayer = makeFlowPathLayer(PathLayer);
         // which engine and libraries this page really runs (a page may
         // bring its own MapLibre/deck.gl — the loaded ones are named)
         const ml = global.maplibregl && typeof global.maplibregl.getVersion === 'function' ? global.maplibregl.getVersion() : '?';
@@ -662,10 +771,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     return ring;
   }
 
+  // a quantized topology's point positions are absolute (not delta-encoded
+  // like arcs) quantized integers: x * scale + translate
+  function decodePoint(p, transform) {
+    if (!transform) return p;
+    return [p[0] * transform.scale[0] + transform.translate[0], p[1] * transform.scale[1] + transform.translate[1]];
+  }
+
   function topoGeometryToGeoJSON(geom, arcs, transform) {
     switch (geom.type) {
-      case 'Point': return { type: 'Point', coordinates: geom.coordinates };
-      case 'MultiPoint': return { type: 'MultiPoint', coordinates: geom.coordinates };
+      case 'Point': return { type: 'Point', coordinates: decodePoint(geom.coordinates, transform) };
+      case 'MultiPoint': return { type: 'MultiPoint', coordinates: geom.coordinates.map(p => decodePoint(p, transform)) };
       case 'LineString': return { type: 'LineString', coordinates: ringCoords(geom.arcs, arcs, transform) };
       case 'MultiLineString': return { type: 'MultiLineString', coordinates: geom.arcs.map(a => ringCoords(a, arcs, transform)) };
       case 'Polygon': return { type: 'Polygon', coordinates: geom.arcs.map(ring => ringCoords(ring, arcs, transform)) };
@@ -941,11 +1057,40 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // ixmaps-flat dev tree, Themes.prototype.setExternalData). This engine
   // has no such pipeline to resume, so the bridge only needs to do the
   // ONE thing fetchLayerData actually needs: resolve the promise a
-  // query()-mode fetch is awaiting. build()'s layer-loading loop is
-  // strictly sequential (one .data({query}) in flight at a time, see its
-  // dataCache), so a single pending-resolver slot is enough — not a
-  // registry keyed by data name like the real engine's.
-  let _pendingQueryResolve = null;
+  // query()-mode fetch is awaiting. Queries run in parallel (several
+  // layers, a later map.layer()), so every pending one has its own entry,
+  // keyed by the options object its query function received — real pages
+  // hand that same object back: query(themeObj, options) …
+  // ixmaps.setExternalData(data, options). In data order: oldest first.
+  const _pendingQueries = new Map(); // options object → { name, resolve, reject, timer }
+  // a pending query's timeout (0: DATAJS_LOAD_TIMEOUT_MS) — a field so the
+  // unit tests can shorten it
+  const QUERY_HANDOFF = { timeoutMs: 0 };
+  function settleQuery(opts, err, data) {
+    const q = _pendingQueries.get(opts);
+    if (!q) return;
+    _pendingQueries.delete(opts);
+    clearTimeout(q.timer);
+    if (err) q.reject(err); else q.resolve(data);
+  }
+  // the pending query a setExternalData(data, opt) belongs to: the one
+  // given that very options object, else the one of that data name, else —
+  // no name — the oldest (exact while only one is pending)
+  function pendingQueryOf(opt) {
+    if (opt && _pendingQueries.has(opt)) return opt;
+    const name = opt && opt.name;
+    if (name != null && name !== '') {
+      for (const [o, q] of _pendingQueries) if (q.name === String(name)) return o;
+      return null;
+    }
+    const first = _pendingQueries.keys().next();
+    if (first.done) return null;
+    if (_pendingQueries.size > 1) {
+      console.warn('[ixmaps-gl] ixmaps.setExternalData without its query\'s options object or a name, while ' + _pendingQueries.size +
+        ' .data({query}) fetches are pending — handed to the oldest; pass the options the query function received');
+    }
+    return first.value;
+  }
   // Data by name, as flat (maptheme.js 2570-2593, 8286-8310):
   // setExternalData(data, {type, name}) makes a data.js Table of the data
   // and keeps it as window[name]; whoever waits for that name gets it, and
@@ -991,6 +1136,12 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // globals a data name must not overwrite
   const _engineGlobalsGuard = { ixmaps: 1, Data: 1, deck: 1, maplibregl: 1, window: 1, document: 1, $: 1, jQuery: 1 };
   function setExternalDataBridge(dataObj, opt) {
+    const query = pendingQueryOf(opt);
+    if (query) {
+      if (dataObj == null) settleQuery(query, new Error('[ixmaps-gl] .data({query}): the query handed over no data (ixmaps.setExternalData(null, …))'));
+      else settleQuery(query, null, dataObj);
+      return;
+    }
     const name = opt && opt.name;
     if (name != null && name !== '') {
       (dataObj == null ? Promise.resolve(null) : externalDataToTable(dataObj, opt))
@@ -998,13 +1149,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         .catch(err => { console.error(err); publishNamedData(String(name), null); });
       return;
     }
-    if (!_pendingQueryResolve) {
-      console.warn('[ixmaps-gl] ixmaps.setExternalData called with no pending .data({query}) fetch — ignored');
-      return;
-    }
-    const resolve = _pendingQueryResolve;
-    _pendingQueryResolve = null;
-    resolve(dataObj);
+    console.warn('[ixmaps-gl] ixmaps.setExternalData called with no pending .data({query}) fetch — ignored');
   }
 
   // ---------------------------------------------------------------
@@ -1056,7 +1201,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     if (!table || !Array.isArray(table.records) || !Array.isArray(table.fields)) {
       return table && typeof table.json === 'function' ? table.json() : [];
     }
-    const names = table.fields.map(f => f.id);
+    // a header cell that spans lines ("Sezione (*)\nSektion", bilingual
+    // exports) reads as one line, as in flat: "Sezione (*) Sektion"
+    const names = table.fields.map(f => String(f.id).replace(/[\r\n]+/g, ' '));
     const rows = new Array(table.records.length);
     for (let i = 0; i < table.records.length; i++) {
       const rec = table.records[i], o = {};
@@ -1065,6 +1212,26 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     }
     return rows;
   }
+  // .data({process}) on topojson/geojson, as flat: its data.js hands the
+  // process function the features' properties as a Table (column(...).map,
+  // addColumn, ...); the result goes back onto the same features, by row
+  function processFeatureCollection(fc, dataConfig) {
+    if (!dataConfig.process || !fc || !Array.isArray(fc.features) || !fc.features.length) return fc;
+    requireDataJs('process');
+    const headers = [];
+    const seen = new Set();
+    for (const f of fc.features) {
+      for (const k of Object.keys(f.properties || {})) if (!seen.has(k)) { seen.add(k); headers.push(k); }
+    }
+    const table = new global.Data.Table().setArray([headers, ...fc.features.map(f => headers.map(h => (f.properties || {})[h]))]);
+    const rows = dataTableRows(runDataProcess(table, dataConfig));
+    if (rows.length !== fc.features.length) {
+      console.warn(`[ixmaps-gl] .data({process}) changed the row count of ${dataConfig.type} features (${fc.features.length} → ${rows.length}); process result ignored`);
+      return fc;
+    }
+    fc.features.forEach((f, i) => { f.properties = rows[i]; });
+    return fc;
+  }
   // parse CSV text with data.js (as flat) → a Table
   function dataJsCsvTable(text) {
     return new Promise((resolve, reject) => {
@@ -1386,8 +1553,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // genuinely CSV-shaped .obj with a missing binding.position would
     // throw, even though this .obj was never row data in the first place.
     if (dataConfig.obj) {
-      if (dataConfig.type === 'topojson') return topojsonToFeatureCollection(dataConfig.obj, dataConfig.object);
-      if (dataConfig.type === 'geojson') return sanitizeGeoJSON(dataConfig.obj);
+      if (dataConfig.type === 'topojson') return processFeatureCollection(topojsonToFeatureCollection(dataConfig.obj, dataConfig.object), dataConfig);
+      if (dataConfig.type === 'geojson') return processFeatureCollection(sanitizeGeoJSON(dataConfig.obj), dataConfig);
       let obj = dataConfig.obj;
       if (dataConfig.process) {
         requireDataJs('process');
@@ -1402,7 +1569,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         }
         obj = runDataProcess(obj, dataConfig);
       }
-      const rows = typeof obj.json === 'function' ? obj.json() : obj;
+      // a raw jsonDB object ({fields, records}) → rows, with or without
+      // process (and without needing data.js)
+      const isJsonDb = !Array.isArray(obj) && Array.isArray(obj.fields) && Array.isArray(obj.records);
+      const rows = typeof obj.json === 'function' ? obj.json() : isJsonDb ? dataTableRows(obj) : obj;
       return rowsResult(rows, binding);
     }
 
@@ -1412,9 +1582,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           '<script src="https://cdn.jsdelivr.net/gh/gjrichter/data.js@master/data.js"> before ixmaps-gl.js');
       }
       const queryFn = typeof dataConfig.query === 'function' ? dataConfig.query : new Function(`return (${dataConfig.query});`)();
-      const dataObj = await new Promise(resolve => {
-        _pendingQueryResolve = resolve;
-        queryFn({}, {});
+      // its own options object: the query hands it back with the data
+      const opts = { type: dataConfig.type, name: dataConfig.name };
+      const timeoutMs = QUERY_HANDOFF.timeoutMs || DATAJS_LOAD_TIMEOUT_MS;
+      const dataObj = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => settleQuery(opts, new Error(`[ixmaps-gl] .data({query}): no data handed over (ixmaps.setExternalData) within ${timeoutMs / 1000}s`)), timeoutMs);
+        _pendingQueries.set(opts, { name: dataConfig.name != null ? String(dataConfig.name) : null, resolve, reject, timer });
+        try { queryFn({}, opts); } catch (err) { settleQuery(opts, err); }
       });
       return rowsResult((dataConfig.process ? runDataProcess(dataObj, dataConfig) : dataObj).json(), binding);
     }
@@ -1436,8 +1610,21 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // parser (PapaParse), so the Table arrives via the callback
         const tables = await Promise.all(texts.map(dataJsCsvTable));
         let table = tables[0];
-        for (const t of tables.slice(1)) table.records = table.records.concat(t.records);
-        if (table.table) table.table.records = table.records.length;
+        // records are positional: align each later file's columns to the
+        // first file's by name (a column only a later file has is added),
+        // as the no-data.js path below gets from each file's own header
+        for (const t of tables.slice(1)) {
+          const ids = table.fields.map(f => f.id);
+          const tIds = t.fields.map(f => f.id);
+          if (tIds.length === ids.length && tIds.every((id, c) => id === ids[c])) {
+            table.records = table.records.concat(t.records);
+            continue;
+          }
+          t.fields.forEach(f => { if (!ids.includes(f.id)) { ids.push(f.id); table.fields.push(f); } });
+          const src = ids.map(id => tIds.indexOf(id));
+          table.records = table.records.concat(t.records.map(rec => src.map(c => (c < 0 ? undefined : rec[c]))));
+        }
+        if (table.table) { table.table.records = table.records.length; table.table.fields = table.fields.length; }
         if (scriptProcess) table = scriptProcess(table);
         else if (dataConfig.process) table = runDataProcess(table, dataConfig);
         rows = dataTableRows(table);
@@ -1459,8 +1646,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // them into a table with a geometry column, and back)
       const resp = await fetch(dataConfig.url);
       if (!resp.ok) throw new Error(`[ixmaps-gl] failed to fetch ${dataConfig.url}: ${resp.status}`);
-      if (dataConfig.type === 'topojson') return topojsonToFeatureCollection(await resp.json(), dataConfig.object);
-      return sanitizeGeoJSON(await resp.json());
+      if (dataConfig.type === 'topojson') return processFeatureCollection(topojsonToFeatureCollection(await resp.json(), dataConfig.object), dataConfig);
+      return processFeatureCollection(sanitizeGeoJSON(await resp.json()), dataConfig);
     }
     // every other format (json, jsonstat, ndjson, rss, kml, gml, geobuf,
     // flatgeobuf, geopackage, parquet, ...) through data.js, as flat
@@ -1858,21 +2045,25 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     if (isAggregatedCategoricalChoropleth(spec)) {
       const groups = new Map();
       for (const row of table.rows) {
-        const key = String(row[lookupField]);
+        if (row[lookupField] == null) continue;
+        const key = flatLookupKey(row[lookupField], spec.style);
         if (!groups.has(key)) groups.set(key, []);
         groups.get(key).push(row);
       }
       return {
         type: 'FeatureCollection',
         features: geomRt.features.map(f => {
-          const rows = groups.get(String(f.properties[idField]));
+          const rows = f.properties[idField] == null ? null : groups.get(String(f.properties[idField]));
           const properties = rows ? Object.assign({}, rows[0]) : {};
           if (rows) Object.defineProperty(properties, AGGREGATED_ROWS, { value: rows });
           return { type: 'Feature', geometry: f.geometry, properties, _flatAreaKm2: flatShapeAreaKm2(geomRt, f) };
         })
       };
     }
-    const rowsByKey = new Map(table.rows.map(row => [String(row[lookupField]), row]));
+    // the data side's key as flat makes it (lookupdigits/toupper/tonumber),
+    // the geometry id as is — the same rule as joinChartPositions
+    // a missing key on either side joins nothing (not "undefined" to "undefined")
+    const rowsByKey = new Map(table.rows.filter(row => row[lookupField] != null).map(row => [flatLookupKey(row[lookupField], spec.style), row]));
     // Unmatched polygons (no CSV row for that id) keep their geometry with
     // empty properties — real-world data: not every comune necessarily has
     // a row in every demographic source. Renders as "no data" (see
@@ -1881,7 +2072,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     const features = geomRt.features.map(f => ({
       type: 'Feature',
       geometry: f.geometry,
-      properties: rowsByKey.get(String(f.properties[idField])) || {},
+      properties: (f.properties[idField] != null && rowsByKey.get(String(f.properties[idField]))) || {},
       _flatAreaKm2: flatShapeAreaKm2(geomRt, f)
     }));
     return { type: 'FeatureCollection', features };
@@ -2294,13 +2485,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // this list; the rest is still recognized-but-inert
   const KNOWN_INERT_FLAGS = ['CLIPTOGEOBOUNDS', 'OUTLIER',
     'POW2', 'POW3', 'NOSORT'];
-  // flat's PIE / DONUT variants with no rendering here (see _buildPieLayers)
-  const PIE_INERT_FLAGS = [/3D/, /VOLUME/, /HEIGHT/, /STARBURST/, /FLOWER/, /RAYS/, /BOW/, /ZOOM/, /DIRECTION/, /DIRECTED/, /POLAR/];
+  // flat's PIE / DONUT variants with no rendering here (see _buildPieLayers).
+  // STARBURST / FLOWER / RAYS (the starburst rays, with the XLRAYS & kin
+  // angle/gap variants) and POLAR (its reference circles) ARE drawn — see
+  // pieSliceLayout; the rest is still recognized-but-inert
+  const PIE_INERT_FLAGS = [/3D/, /VOLUME/, /HEIGHT/, /BOW/, /ZOOM/, /DIRECTION/, /DIRECTED/];
   // ... and of AGGREGATE / CATEGORICAL pies: GRIDSIZE's pie the size of its
-  // grid cell (drawn by the SIZE rule instead), AUTOSIZE, DOPACITY, the
-  // chart BOX and TITLE, GAUGE, MULTIPLE / DIFFUSE, the post-aggregation
-  // value arithmetic (DIFFERENCE, FRACTION, PERCENT …, field100)
-  const PIE_AGGREGATE_INERT_FLAGS = [/^GRIDSIZE$/, /AUTOSIZE/, /DOPACITY/, /BOX/, /TITLE/, /^GAUGE$/, /^MULTIPLE$/, /^DIFFUSE$/,
+  // grid cell (drawn by the SIZE rule instead), AUTOSIZE, DOPACITY,
+  // GAUGE, MULTIPLE / DIFFUSE, the post-aggregation
+  // value arithmetic (DIFFERENCE, FRACTION, PERCENT …, field100).
+  // The chart BOX and TITLE ARE drawn (see _buildPieLayers)
+  const PIE_AGGREGATE_INERT_FLAGS = [/^GRIDSIZE$/, /AUTOSIZE/, /DOPACITY/, /^GAUGE$/, /^MULTIPLE$/, /^DIFFUSE$/,
     /^DIFFERENCE$/, /^FRACTION$/, /^PERCENT$/, /^PERMILLE$/, /^PRODUCT$/, /^CALCVAL$/, /^RELATIVE$/];
   // flat's BAR / BARS variants with no rendering here (see flatBarLayout):
   // the bar is drawn plain (SMALLARROW as ARROW) — tested as substrings,
@@ -2310,11 +2505,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     /^DIFFERENCE$/, /^FRACTION$/, /^PERCENT$/, /^PERMILLE$/, /^PRODUCT$/, /^CALCVAL$/, /^RELATIVE$/];
   // flat's VECTOR / BEZIER modifiers with no rendering here (see
   // _buildVectorLayers), the word → what happens instead
+  // (DASH IS drawn — the animated flow, see makeFlowPathLayer)
   const VECTOR_INERT_FLAGS = {
     VALUES: 'the value text along the curve is not drawn yet',
     DYNAMICWIDTH: 'not drawn yet (flat widens by the log of the length in its own map units) — the plain width instead',
-    LONG: 'not drawn yet (its bow depends on flat\'s own map units) — the default bow instead',
-    DASH: 'drawn as static dashes — flat\'s dash animation is not ported'
+    LONG: 'not drawn yet (its bow depends on flat\'s own map units) — the default bow instead'
   };
   const _warnedFlags = new Set();
 
@@ -2359,6 +2554,18 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // makes while the map is still building wait for it
   let _resolveMapReady;
   const _mapReady = new Promise(r => { _resolveMapReady = r; });
+  // a map declared with an options name (Map(id, {name})) → the deferred of
+  // ITS build: ixmaps.map("name") calls made while it is still building wait
+  // for that map, not whichever map is built first
+  const _namedMapReady = Object.create(null);
+  function namedMapReady(name) {
+    if (!_namedMapReady[name]) {
+      let resolve;
+      const promise = new Promise(r => { resolve = r; });
+      _namedMapReady[name] = { promise, resolve };
+    }
+    return _namedMapReady[name];
+  }
 
   // flat's ixmaps.require(url) fetches the script and evals it
   // (htmlgui.js 3911-3934); here each one runs globally, in order, before
@@ -2478,7 +2685,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // key wins. Always into a new object — the page's own objects are never
     // mutated. Aliases (geo → position, ...) are resolved in normalizeTheme.
     binding(b) {
-      this._binding = Object.assign({}, this._binding, b);
+      // flat's toString joins an array with '|' (maptheme.js 1014): a
+      // binding given as an ARRAY — .binding({value: ["out","in"]}, the
+      // pendolari page's saldo pie) is a MULTI-FIELD binding, not one
+      // field named "out,in" (which would find no column and draw
+      // nothing). Normalized once, here, for every consumer that
+      // splits binding.value on '|'
+      const norm = {};
+      // (an empty or missing argument keeps what earlier calls set)
+      for (const [k, v] of Object.entries(b || {})) norm[k] = Array.isArray(v) ? v.join('|') : v;
+      this._binding = Object.assign({}, this._binding, norm);
       return this;
     }
     filter(expr) { this._filterExpr = expr; return this; }
@@ -2768,27 +2984,75 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // that kind: the data processing function (data.process /
   // style.dbtableProcess), the broker query (data.query /
   // style.dbtableQuery — without it a data.name still reaches a
-  // provider the PAGE defined as ixmaps[name]) and a colorscheme given
-  // as a string, which resolveColorScheme evaluates as a function
-  // (an array colorscheme is data and stays).
+  // provider the PAGE defined as ixmaps[name]) and a colorscheme
+  // resolveColorScheme would evaluate: a string, or ["byvalue", "<fn>"]
+  // (any other array colorscheme is data and stays). normalizeTheme
+  // merges meta INTO style, so every style key is checked under meta too.
+  const isColorSchemeCode = v => typeof v === 'string'
+    || (Array.isArray(v) && v[0] === 'byvalue' && typeof v[1] === 'string');
   const PROJECT_CODE_KEYS = [
     ['data', 'process', 'data.process function'],
     ['style', 'dbtableProcess', 'data.process function'],
     ['data', 'query', 'data.query function'],
     ['style', 'dbtableQuery', 'data.query function'],
-    ['style', 'colorscheme', 'colorscheme function', v => typeof v === 'string'],
-  ];
+    ['style', 'colorscheme', 'colorscheme function', isColorSchemeCode],
+  ].flatMap(k => (k[0] === 'style' ? [k, ['meta', ...k.slice(1)]] : [k]));
+  // A project's legend texts (title, snippet, description — in style or
+  // meta, normalizeTheme fills meta from either) are shown as HTML, as on
+  // flat: citation links in a description are real. A project's markup is
+  // cleaned to formatting tags and plain attributes so nothing in it runs;
+  // a page's own .meta()/.style() HTML stays as given.
+  const PROJECT_HTML_KEYS = ['title', 'snippet', 'description'];
+  const PROJECT_HTML_DROP = new Set(['SCRIPT', 'STYLE', 'IFRAME', 'FRAME', 'FRAMESET', 'OBJECT', 'EMBED', 'SVG', 'MATH',
+    'TEMPLATE', 'NOSCRIPT', 'LINK', 'META', 'BASE', 'FORM', 'INPUT', 'BUTTON', 'SELECT', 'TEXTAREA', 'AUDIO', 'VIDEO', 'SOURCE']);
+  const PROJECT_HTML_TAGS = new Set(['A', 'B', 'I', 'EM', 'STRONG', 'U', 'S', 'SMALL', 'SUB', 'SUP', 'BR', 'P', 'DIV', 'SPAN',
+    'UL', 'OL', 'LI', 'HR', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'IMG', 'TABLE', 'THEAD', 'TBODY', 'TR', 'TD', 'TH', 'CODE', 'BLOCKQUOTE']);
+  const PROJECT_HTML_ATTRS = new Set(['href', 'src', 'alt', 'title', 'target', 'rel', 'class', 'style', 'width', 'height', 'colspan', 'rowspan']);
+  function sanitizeProjectHtml(html) {
+    const s = String(html);
+    if (!/[<&]/.test(s)) return s;
+    // no DOM to parse with (Node): the text, escaped
+    if (typeof global.DOMParser !== 'function') return escapeHtml(s);
+    // an inert document: nothing in it runs or loads while it is cleaned
+    const body = new global.DOMParser().parseFromString('<!doctype html><body>' + s, 'text/html').body;
+    for (const el of Array.from(body.querySelectorAll('*'))) {
+      if (PROJECT_HTML_DROP.has(el.tagName.toUpperCase())) { el.remove(); continue; }
+      if (!PROJECT_HTML_TAGS.has(el.tagName.toUpperCase())) { el.replaceWith(...el.childNodes); continue; }
+      for (const a of Array.from(el.attributes)) {
+        const name = a.name.toLowerCase();
+        if (!PROJECT_HTML_ATTRS.has(name)
+          || ((name === 'href' || name === 'src') && /^(javascript|vbscript|data):/i.test(a.value.replace(/[\s\u0000-\u001f]/g, '')))) {
+          el.removeAttribute(a.name);
+        }
+      }
+    }
+    return body.innerHTML;
+  }
+
   function withoutProjectCode(t, report) {
     const found = PROJECT_CODE_KEYS.filter(([part, key, , isCode]) =>
       t[part] && t[part][key] != null && (!isCode || isCode(t[part][key])));
-    if (!found.length) return t;
+    const html = [];
+    for (const part of ['style', 'meta']) {
+      for (const key of PROJECT_HTML_KEYS) {
+        const v = t[part] && t[part][key];
+        if (typeof v !== 'string') continue;
+        const clean = sanitizeProjectHtml(v);
+        if (clean !== v) html.push([part, key, clean]);
+      }
+    }
+    if (!found.length && !html.length) return t;
     const copy = Object.assign({}, t);
-    found.forEach(([part, key]) => {
-      if (copy[part] === t[part]) copy[part] = Object.assign({}, t[part]);
-      delete copy[part][key];
-    });
-    const what = [...new Set(found.map(f => f[2]))].join(', ');
-    report.notes.push(`theme "${t.layer}": the project's ${what} is never run by ixmaps-gl`);
+    const own = part => { if (copy[part] === t[part]) copy[part] = Object.assign({}, t[part]); return copy[part]; };
+    found.forEach(([part, key]) => { delete own(part)[key]; });
+    html.forEach(([part, key, clean]) => { own(part)[key] = clean; });
+    if (found.length) {
+      const what = [...new Set(found.map(f => f[2]))].join(', ');
+      report.notes.push(`theme "${t.layer}": the project's ${what} is never run by ixmaps-gl`);
+    }
+    if (html.length) {
+      report.notes.push(`theme "${t.layer}": the project's ${[...new Set(html.map(h => h[1]))].join(', ')} HTML is cleaned to formatting markup by ixmaps-gl`);
+    }
     return copy;
   }
 
@@ -2858,7 +3122,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     'sizepow', 'rangescale', 'minvalue', 'maxvalue', 'markersize', 'boxopacity', 'outlierscale', 'valuescale',
     'brightness', 'fractionscale', 'dopacityscale', 'dopacitypow', 'gridwidthpx', 'textscale', 'rangecentervalue',
     'shadowblur', 'shadowdx', 'shadowdy', 'maxshadow', 'offsetx', 'offsety', 'gridx', 'boxmargin', 'borderwidth',
-    'borderradius', 'maxcharts', 'archeight'];
+    'borderradius', 'maxcharts', 'archeight', 'alignmargin'];
   function toNumberIfNumeric(v) {
     if (typeof v !== 'string' || !v.trim()) return v;
     const n = Number(v);
@@ -3350,6 +3614,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // The ocean of flat's world / orthographic maps is a {type:"Sphere"} feature: the whole map disc,
   // filled with the layer's color. Here it is the surface of the map (the globe, or the flat
   // map): a background layer under everything, in that color and opacity.
+  // the themes are drawn once, as in flat, even where the map repeats its world (the themecopies map option:
+  // true repeats them on every world copy)
+  function applyThemeCopies(map, value) {
+    if (value !== true && value !== 'true') {
+      if (!map.__ixOrigGetRenderWorldCopies) map.__ixOrigGetRenderWorldCopies = map.getRenderWorldCopies;
+      map.getRenderWorldCopies = () => false;
+    } else if (map.__ixOrigGetRenderWorldCopies) {
+      map.getRenderWorldCopies = map.__ixOrigGetRenderWorldCopies;
+      delete map.__ixOrigGetRenderWorldCopies;
+    }
+  }
   const SPHERE_BACKDROP_LAYER_ID = '__ixmaps_gl_sphere_backdrop';
   function applySphereBackdrop(map, style) {
     const cs = style && style.colorscheme;
@@ -3367,7 +3642,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         map.setPaintProperty(id, 'background-opacity', opacity);
       } catch (e) { console.warn('[ixmaps-gl] the {type:"Sphere"} ocean backdrop could not be set:', e); }
     };
-    if (map.isStyleLoaded()) paint(); else map.once('style.load', paint);
+    // isStyleLoaded() is also false AFTER the style loaded while tiles or
+    // images load (every pan/zoom) — 'style.load' never fires again then, so
+    // a Sphere theme defined at such a moment would never get its color
+    if (map.isStyleLoaded() || (map.style && map.style._loaded)) paint(); else map.once('style.load', paint);
   }
 
   function buildBlankBackgroundStyle(color) {
@@ -3386,6 +3664,23 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // basemap credit, bottom right — same line, same pill: white, 12px
   // radius, 12px/20px Helvetica Neue, links rgba(0,0,0,0.75)).
   // ---------------------------------------------------------------
+  // On a dark map (the effective darkness, as the legend and the tooltip use it) the MapLibre control buttons
+  // (zoom, compass) and the page's attribution are dark too: the class ixgl-dark on the map element switches them
+  let _controlLookCss = false;
+  function applyControlLook(el, dark) {
+    if (!_controlLookCss && typeof document !== 'undefined') {
+      _controlLookCss = true;
+      const css = document.createElement('style');
+      css.textContent = '.ixgl-dark .maplibregl-ctrl-group{background:#222!important;box-shadow:0 0 0 1px rgba(255,255,255,.15)!important}'
+        + '.ixgl-dark .maplibregl-ctrl-group button+button{border-top:1px solid #444!important}'
+        + '.ixgl-dark .maplibregl-ctrl-group button:not(:disabled):hover{background-color:#3a3a3a!important}'
+        + '.ixgl-dark .maplibregl-ctrl-group .maplibregl-ctrl-icon{filter:invert(1)}'
+        + '.ixgl-dark .ixmaps-gl-attribution{background:#222!important;color:#aaa!important}'
+        + '.ixgl-dark .ixmaps-gl-attribution a{color:#ddd!important}';
+      document.head.appendChild(css);
+    }
+    if (el && el.classList) el.classList.toggle('ixgl-dark', !!dark);
+  }
   let _attributionCss = false;
   function createAttribution(map) {
     if (!_attributionCss && typeof document !== 'undefined') {
@@ -3516,7 +3811,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // 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;
+      // x/y and the translate are relative to the map container (it clips,
+      // overflow:hidden): its size is the room, not the window's — they
+      // differ on an embedded map
+      const vw = el.clientWidth || global.innerWidth || 1200, vh = el.clientHeight || 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));
@@ -3689,11 +3987,29 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // 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;
     }
+    // flat's click-to-action hook (ui/js/tools/tooltip_to_action.js): ixmaps.onItemAction(szId, item, themeObj) on a
+    // click on an item — item.szSelectionId is the value of the theme's selection field — and onItemAction(null, null)
+    // on a click on the map background
+    function callItemAction(rt, object) {
+      const hook = pageIxmaps() && pageIxmaps().onItemAction;
+      if (typeof hook !== 'function') return;
+      try {
+        if (!rt) { hook.call(global.ixmaps, null, null); return; }
+        const field = selectionFieldOf(rt);
+        const props = object.properties || {};
+        // a single record, or an aggregated item's first one
+        const raw = props.raw || props.firstRaw || props.titleRaw || (props.raws && props.raws[0]) || props;
+        const value = field && raw ? raw[field] : null;
+        if (value == null) return;
+        hook.call(global.ixmaps, themeIdOf(rt) + '::' + value, { szSelectionId: String(value) }, getThemeObj(themeIdOf(rt)));
+      } catch (err) { console.error('[ixmaps-gl] onItemAction failed:', err); }
+    }
     function clickFor(picked) {
         const info = picked && Object.assign({}, picked, { object: pickedFeature(picked.object) });
         if (info && info.object && info.layer) {
           const rt = findRuntimeForLayerId(info.layer.id);
           if (rt) {
+            callItemAction(rt, info.object);
             // Only a Point geometry's own coordinates ARE an
             // [lng,lat] pair (every point/bubble/dot/chart-cluster
             // layer) — a CHOROPLETH polygon's geometry.coordinates is
@@ -3724,6 +4040,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           }
         }
         // clicked empty map space (or a non-tooltippable layer) -> unpin
+        callItemAction(null, null);
         pinned = null;
         pinnedTooltipEl.style.display = 'none';
         return false;
@@ -4116,13 +4433,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           // twin pages)
           const flatUnitLegend = rt._isVectorChart() || rt._isAggregatedPie();
           const rawLegendUnit = rt.style.legendunits || rt.style.units || '';
-          const legendUnit = flatUnitLegend && rawLegendUnit && rawLegendUnit[0] !== '.' && rawLegendUnit[0] !== ' ' ? ' ' + rawLegendUnit : rawLegendUnit;
+          // COUNT: the rows are record counts — flat prints them as whole numbers
+          // with no unit (legend.js 705, 810: __formatValue(count, nDecimals,
+          // "BLANK") + (COUNT ? "" : " " + unit))
+          const countLegend = flatFlag(rt.flags, 'COUNT') && !useSum;
+          const legendUnit = countLegend ? '' : flatUnitLegend && rawLegendUnit && rawLegendUnit[0] !== '.' && rawLegendUnit[0] !== ' ' ? ' ' + rawLegendUnit : rawLegendUnit;
           // a per-item chart over several value fields: the row values as
           // flat's legend prints them (legend.js 610, 810: __formatValue
           // with valuedecimals, else 2, "BLANK" — whole numbers without
           // decimals), a colorscheme "none" part as an outline in linecolor
           const multiFieldLegend = rt._isMultiFieldChart();
-          const legendTotalText = v => ((multiFieldLegend || flatUnitLegend)
+          const legendTotalText = v => ((multiFieldLegend || flatUnitLegend || countLegend)
             ? flatFormatValue(v, legendDecimals(rt.style), 'BLANK')
             : rt._formatTooltipValue(v));
           const outlineRgb = rt.style.linecolor && styleLineColor(rt.style.linecolor) !== 'none' ? hexOrNamedToRgb(styleLineColor(rt.style.linecolor)) : [128, 128, 128];
@@ -4425,7 +4746,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           // same 400ms as the facets sidebar's own onRedraw use), same
           // signal already used elsewhere in this file for "the visible
           // data just changed, recompute".
-          engineApi.onRedraw(() => { computeTotals(); renderRows(); });
+          // a panel replaced (rebuild, legend off) or a removed theme: the
+          // listener goes with it — else one per rebuild piles up, each
+          // recomputing a stale runtime on every redraw
+          const offRedraw = engineApi.onRedraw(() => {
+            if (rt._legendPanel !== panel || !runtimes.includes(rt)) { offRedraw(); return; }
+            computeTotals(); renderRows();
+          });
           }
 
           // rt._triggerRedraw: see its own doc comment on LayerRuntime
@@ -4740,7 +5067,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       }
       return this;
     }
-    options(o) { this._engineOptions = o; return this; }
+    // merged, as flat's options() sets each key on its own (ixmaps.setOptions)
+    // and the live map's options() below does — .options({a}).options({b})
+    // keeps a
+    options(o) { if (o && typeof o === 'object') Object.assign(this._engineOptions, o); return this; }
     local(...args) { this._locals.push(args); return this; }
     // flat's .require(url) (htmlgui.js ixmaps.require): a script the page
     // needs (a chart library, a user chart) — page code, like a <script>
@@ -4793,6 +5123,12 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // the Map(id, opts, map => map.options(...)) callback form worked).
       // One microtask lets the caller's whole synchronous chain land first.
       await null;
+      // the DASH flow animation's repaint loop (see refreshLayers): MapLibre
+      // renders on demand only, so the shader's wall-clock dash (see
+      // makeFlowPathLayer) needs a continuous frame request while any flow
+      // layer is on screen — one handle per map, or another map's refresh
+      // cancels (or blocks) this map's loop
+      let _flowRepaintRAF = null;
       let el = document.getElementById(this.containerId);
       if (!el) {
         // flat's own fallback for a missing target div (htmlgui_flat.js
@@ -4812,7 +5148,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         el = document.createElement('div');
         el.id = this.containerId;
         el.style.width = (this.mapOptions && this.mapOptions.width) ? String(this.mapOptions.width) : '100%';
-        el.style.height = (this.mapOptions && this.mapOptions.height) ? String(this.mapOptions.height) : '100%';
+        // a percentage height would collapse against a body without a
+        // height of its own (the blank-screen case): the window's
+        // innerHeight instead, like flat's fullscreen fallback
+        el.style.height = (this.mapOptions && this.mapOptions.height) ? String(this.mapOptions.height)
+          : (global.innerHeight || 800) + 'px';
         document.body.appendChild(el);
       }
       // flat's init replaces the container's content with its own map page
@@ -4836,13 +5176,22 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         else if (typeof v === 'string' && /^\s*\d+(\.\d+)?\s*%\s*$/.test(v)
           && !(dim === 'width' ? el.clientWidth : el.clientHeight)) el.style[dim] = v.trim();
       }
-      // without width/height flat's map is "fullscreen" (htmlgui_flat.js
+      // without height flat's map is "fullscreen" (htmlgui_flat.js
       // 847-876): it fills the window, whatever the page's CSS gives the
-      // container — a container left without a height gets the window's
-      if (!(this.mapOptions && (this.mapOptions.width || this.mapOptions.height))) {
-        if (!el.clientHeight) el.style.height = '100vh';
-        if (!el.clientWidth) el.style.width = '100%';
+      // container. PER SIDE — also when only a width is given (the World
+      // Dataviz Prize pages: width 100%, no height), where the old
+      // both-sides gate left the container collapsed at 0 (a blank
+      // screen): no height option and no effective CSS height gets the
+      // window's innerHeight, kept current on window resizes (MapLibre
+      // follows its container's own size)
+      if (!(this.mapOptions && this.mapOptions.height) && !el.clientHeight) {
+        this._heightFallbackToWindow = true;
+        el.style.height = (global.innerHeight || 800) + 'px';
+        global.addEventListener('resize', () => {
+          if (this._heightFallbackToWindow) el.style.height = (global.innerHeight || 800) + 'px';
+        });
       }
+      if (!(this.mapOptions && this.mapOptions.width) && !el.clientWidth) el.style.width = '100%';
 
       // shown for the whole build() (library lazy-load + every layer's own
       // data fetch, real-world verified as the two slowest phases) through
@@ -4869,8 +5218,6 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const svgProjection = flatSvgProjectionOf(this.mapOptions.map)
         || (isFlatOrthographicName(this.mapOptions.mapProjection) ? FLAT_ORTHOGRAPHIC_PROJECTION : null);
       if (svgProjection) flatSvgProjectionByOptions.set(this._engineOptions, svgProjection);
-      const planeProjection = flatPlaneProjectionOf(this.mapOptions);
-      if (planeProjection) flatPlaneProjectionByOptions.set(this._engineOptions, planeProjection);
       if (isFlatOrthographicName(this.mapOptions.mapProjection)) {
         flatOrthographicByOptions.set(this._engineOptions, true);
         if (this._viewCenter) flatViewCenterByOptions.set(this._engineOptions, { lat: this._viewCenter[0], lng: this._viewCenter[1] });
@@ -5035,11 +5382,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // world map can't open fully zoomed out. The deck.gl overlay takes
         // its `repeat` from map.getRenderWorldCopies(), so the themes are
         // drawn on every world copy too (flat draws them once; only its
-        // basemap tiles wrap). .options({worldcopies: false}) draws the
+        // basemap tiles wrap) — unless themecopies is off, which is the default
+        // (see applyThemeCopies). .options({worldcopies: false}) draws the
         // world once, at the cost of that zoom limit.
         renderWorldCopies: this._engineOptions.worldcopies !== false
       });
       engineOptionsByMap.set(map, this._engineOptions);
+      // themecopies (default: off): the map keeps its world copies (free panning past the world's edge, empty
+      // space beside it) but the deck.gl overlay, which asks map.getRenderWorldCopies() for its `repeat`, draws the
+      // themes once, as flat does. .options({themecopies: true}) repeats them. MapLibre's own transform does not
+      // use this method.
+      applyThemeCopies(map, this._engineOptions.themecopies);
       sphereBackdrops.forEach(style => applySphereBackdrop(map, style));
       // the live-SVG pane USER charts render into (see chartHostFor) —
       // registered here, keyed by this map's options object, so every
@@ -5168,6 +5521,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // the page's attribution (.attribution(), Map option attribution)
       const attributionBox = createAttribution(map);
       attributionBox.set(this._attributionText != null ? this._attributionText : this.mapOptions.attribution);
+      // dark controls on a dark map; re-read when a style (basemap) loads and when basemapopacity is set
+      const refreshControlLook = () => {
+        const o = parseFloat(this._engineOptions.basemapopacity);
+        const legendBackground = this.mapOptions.legendBackground || this.mapOptions.legendbackground;
+        applyControlLook(el, typeof this.__effectiveDark === 'function'
+          ? this.__effectiveDark(isNaN(o) ? 1 : o, this.mapOptions.mapType, legendBackground) : false);
+      };
+      this._refreshControlLook = refreshControlLook;
+      refreshControlLook();
+      map.on('style.load', refreshControlLook);
       this._setAttribution = text => attributionBox.set(text);
 
       if (this._legendHtml) {
@@ -5175,7 +5538,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // a page legend (map.legend(html)) is positioned by the map's
         // own align option — the same rule that places the native stack
         legendEl.style.cssText = 'position:absolute;' + legendAlignCssFor(this.mapOptions) + 'z-index:5;pointer-events:none';
-        legendEl.innerHTML = this._legendHtml;
+        // flat's legend takes the pane's html OR a URL to it (htmlgui):
+        // a value without a tag is fetched, its html shown
+        if (/<[a-z!]/i.test(this._legendHtml)) legendEl.innerHTML = this._legendHtml;
+        else fetch(this._legendHtml).then(r => r.ok ? r.text() : '').then(t => { legendEl.innerHTML = t; }).catch(() => {});
         // inside the map container, never the page's body (see the pinned
         // tooltip mount) — styling body breaks page-positioned elements
         anchorInside(el);
@@ -5305,18 +5671,19 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         add: (layerBuilder, flag) => {
           layerBuilder = unwrapLayer(layerBuilder);
           _chainedLayers = _chainedLayers.then(() => {
+            let slot = null;
             if (/replace/i.test(flag || '')) {
               const def = layerBuilder.definition();
               const id = (def.style && def.style.name) || (def.meta && def.meta.name);
-              if (id) removeThemeById(id);
+              if (id) { slot = captureSlot(id); removeThemeById(id); }
             }
-            return engineApi.defineLayer(layerBuilder);
+            return engineApi.defineLayer(layerBuilder, slot);
           }).catch(err => console.error('[ixmaps-gl] map.add():', err));
           return engineApi;
         },
         replace: (id, layerBuilder, flag) => {
           layerBuilder = unwrapLayer(layerBuilder);
-          _chainedLayers = _chainedLayers.then(() => { removeThemeById(id); return engineApi.defineLayer(layerBuilder); })
+          _chainedLayers = _chainedLayers.then(() => { const slot = captureSlot(id); removeThemeById(id); return engineApi.defineLayer(layerBuilder, slot); })
             .catch(err => console.error('[ixmaps-gl] map.replace():', err));
           return engineApi;
         },
@@ -5331,11 +5698,12 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           layerBuilder = unwrapLayer(layerBuilder);
           const f = String(flag || '');
           _chainedLayers = _chainedLayers.then(() => {
+            let slot = null;
             if (!/force/i.test(f)) {
               if (/replace/i.test(f)) {
                 const def = layerBuilder.definition();
                 const id = (def.style && def.style.name) || (def.meta && def.meta.name);
-                if (id) removeThemeById(id);
+                if (id) { slot = captureSlot(id); removeThemeById(id); }
               } else if (/clearcharts|clear|clearall/i.test(f)) {
                 const charts = /clearcharts/i.test(f);
                 const doomed = runtimes.filter(rt => !flatFlag(rt.flags, 'LOCKED') && (!charts || rt.flags.has('CHART')));
@@ -5344,7 +5712,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
                 byName.forEach((list, name) => removeRuntimes(name, list));
               }
             }
-            return engineApi.defineLayer(layerBuilder);
+            return engineApi.defineLayer(layerBuilder, slot);
           }).catch(err => console.error('[ixmaps-gl] map.newTheme():', err));
           return engineApi;
         },
@@ -5550,7 +5918,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // called after every redraw (pan/zoom, or any of the setters above)
         // so a page can keep a facets sidebar in sync, mirroring the real
         // engine's htmlgui_onDrawTheme hook
-        onRedraw: (cb) => { redrawListeners.push(cb); },
+        // returns an unsubscribe (the legend drops its listener with its panel)
+        onRedraw: (cb) => {
+          redrawListeners.push(cb);
+          return () => { const i = redrawListeners.indexOf(cb); if (i >= 0) redrawListeners.splice(i, 1); };
+        },
         refresh: () => refresh(),
         // Adds ONE new layer/theme to an ALREADY-BUILT map — build()'s own
         // loop above only ever runs once, at construction, so a caller
@@ -5572,7 +5944,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         // exactly how this engine's own facet-filter/style setters below
         // already push responsibility for "what should happen" to the
         // caller rather than guessing.
-        defineLayer: (layerBuilder) => defineFromDefinition(unwrapLayer(layerBuilder).definition()),
+        defineLayer: (layerBuilder, slot) => defineFromDefinition(unwrapLayer(layerBuilder).definition(), slot),
         // GL-PORT COMPAT: real ixmaps-flat's map handle, as a page gets it
         // from `myMap.then(map => map.view(...).options(...).layer(a)
         // .layer(b))` — the common multi-layer idiom — is chainable on the
@@ -5594,6 +5966,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           if (o && typeof o === 'object') {
             Object.assign(builder._engineOptions, o);
             // read only when the MapLibre map is created — switched here at runtime
+            if ('basemapopacity' in o && builder._refreshControlLook) builder._refreshControlLook();
+            if ('themecopies' in o) { applyThemeCopies(map, o.themecopies); map.triggerRepaint(); }
             if ('worldcopies' in o) map.setRenderWorldCopies(o.worldcopies !== false && o.worldcopies !== 'false');
             refresh();
           }
@@ -5700,7 +6074,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           // layers — leaving its groups mounted keeps the charts on the
           // map after map.remove()/replace() (censimenti's sidebar)
           if (rt._clearUserChartPane) rt._clearUserChartPane();
+          if (rt._chartPaneDefs) { rt._chartPaneDefs.remove(); rt._chartPaneDefs = null; }
           if (rt._chartHost && rt._chartHost.runtimes) rt._chartHost.runtimes.delete(rt);
+          // and its hidden <name>_init group (userChartHost, on the body)
+          if (rt._userChartGroup) { rt._userChartGroup.remove(); rt._userChartGroup = null; }
         });
         const removed = removedRuntimes.length > 0;
         // stale-registry guard: _globalThemeRegistry is a bare name->
@@ -5729,6 +6106,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         if (removed) { refresh(); notifyRedraw(); }
         return removed;
       }
+      // where the theme(s) removeThemeById(id) would remove stand in the stack: the first remaining
+      // theme after them (null = they were on top). Taken BEFORE the removal, handed to defineLayer.
+      function captureSlot(id) {
+        const named = runtimes.filter(r => (r.style && r.style.name === id) || (r.meta && r.meta.name === id));
+        const doomed = named.length ? named : runtimes.filter(r => r.name === id);
+        if (!doomed.length) return null;
+        const last = Math.max(...doomed.map(r => runtimes.indexOf(r)));
+        const anchor = runtimes.slice(last + 1).find(r => !doomed.includes(r) && !doomed.some(d => d._subTheme === r)) || null;
+        return { anchor };
+      }
+
       // flat addresses a theme by its id — style.name / meta.name (several
       // themes may share one layer), else the layer name
       function removeThemeById(id) {
@@ -5899,11 +6287,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // flat itself does ("defining a theme with the same name replaces it
       // in place"; a page's live-refresh loop relies on it, e.g. the NYC
       // status page re-defining its two themes every 10s).
-      async function defineFromDefinition(def) {
+      // `slot` (from captureSlot) is where a replaced theme stood in the stack: the replace paths
+      // remove the old theme first and pass it on, so the new one is not appended on top
+      async function defineFromDefinition(def, slot) {
         if (validation) validation.definition(def);
         const pdef = projectThemeToDefinition(def);
         const replacedId = (pdef.meta && pdef.meta.name) || (pdef.style && pdef.style.name);
-        if (replacedId) removeThemeById(replacedId);
+        if (replacedId) {
+          if (!slot) slot = captureSlot(replacedId);
+          removeThemeById(replacedId);
+        }
         let spec = normalizeTheme(pdef);
         let raw;
         const deferred = deferredFeatureLoad(spec, map.getZoom());
@@ -5930,7 +6323,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         rt._zoomToPending = wantsZoomToExtent(spec.flags);
         rt._dataSourceKey = named ? 'name:' + spec.data.name
           : sourceKey || JSON.stringify({ url: spec.data && spec.data.url, urls: spec.data && spec.data.urls, type: spec.data && spec.data.type, query: spec.data && spec.data.query, obj: !!(spec.data && spec.data.obj) });
-        runtimes.push(rt);
+        // a replacement keeps the stacking position (draw order, legend order) of the theme it replaces:
+        // it goes in front of the theme that followed the old one, still on the map after the await above
+        const slotAt = slot && slot.anchor ? runtimes.indexOf(slot.anchor) : -1;
+        if (slotAt >= 0) runtimes.splice(slotAt, 0, rt); else runtimes.push(rt);
         if (fc._sphere) applySphereBackdrop(map, rt.style);
         _globalThemeRegistry.set(rt.name, rt);
         if (rt.meta && rt.meta.name && rt.meta.name !== rt.name) _globalThemeRegistry.set(rt.meta.name, rt);
@@ -5980,10 +6376,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           for (let i = 0; i < themes.length; i++) {
             const t = themes[i] || {};
             const name = (t.style && t.style.name) || (t.meta && t.meta.name);
-            if (/replace/i.test(f) && name) removeThemesNamed(name);
+            let slot = null;
+            if (/replace/i.test(f) && name) { slot = captureSlot(name); removeThemesNamed(name); }
             else if (i === 0 && !/add/i.test(f)) [...new Set(runtimes.map(r => r.name))].forEach(n => engineApi.removeTheme(n));
             try {
-              report.themes.push(await defineFromDefinition(withoutProjectCode(t, report)));
+              report.themes.push(await defineFromDefinition(withoutProjectCode(t, report), slot));
             } catch (e) {
               report.skipped.push({ layer: t.layer, reason: e.message });
             }
@@ -6002,8 +6399,6 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           const svgProjection = flatSvgProjectionOf(svg) || (/orthographic\.svg$/i.test(svg) ? FLAT_ORTHOGRAPHIC_PROJECTION : null);
           if (svgProjection) flatSvgProjectionByOptions.set(builder._engineOptions, svgProjection);
           else flatSvgProjectionByOptions.delete(builder._engineOptions);
-          if (svgProjection && svgProjection.invert) flatPlaneProjectionByOptions.set(builder._engineOptions, svgProjection);
-          else flatPlaneProjectionByOptions.delete(builder._engineOptions);
           if (/orthographic\.svg$/i.test(svg)) flatOrthographicByOptions.set(builder._engineOptions, true);
           else { flatOrthographicByOptions.delete(builder._engineOptions); flatViewCenterByOptions.delete(builder._engineOptions); }
         }
@@ -6174,6 +6569,22 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           if (order !== refreshLayers._lastOrder) { refreshLayers._lastOrder = order; console.info('[ixmaps-gl debug] draw order (bottom → top): ' + order); }
         }
         overlay.setProps({ layers });
+        // start/stop the flow repaint loop: any layer whose paths carry
+        // dash offsets animates, and only then (a static map renders
+        // nothing new; the loop is one rAF, one triggerRepaint each)
+        const flowOn = layers.some(l => l.constructor.layerName === 'FlowPathLayer'
+          && l.props.data && l.props.data.some(d => d.dash && d.dash[0] + d.dash[1] > 0));
+        if (glDebug()) console.info('[ixmaps-gl debug] flow loop on: ' + flowOn + ' (' + layers.filter(l => l.constructor.layerName === 'FlowPathLayer').length + ' flow layers, '
+          + (layers.find(l => l.constructor.layerName === 'FlowPathLayer') || {props: {data: []}}).props.data.length + ' paths)');
+        if (flowOn) {
+          if (_flowRepaintRAF == null) {
+            const loop = () => { if (map.triggerRepaint) map.triggerRepaint(); _flowRepaintRAF = global.requestAnimationFrame(loop); };
+            _flowRepaintRAF = global.requestAnimationFrame(loop);
+          }
+        } else if (_flowRepaintRAF != null) {
+          global.cancelAnimationFrame(_flowRepaintRAF);
+          _flowRepaintRAF = null;
+        }
         // flat's WMS themes render as native raster layers, not deck.gl —
         // reconcile them with the current runtimes on every rebuild
         syncWmsLayers();
@@ -6334,7 +6745,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         } finally { inDrawThemeHook = false; }
       }
       function notifyRedraw() {
-        redrawListeners.forEach(cb => { try { cb(); } catch (err) { console.error('[ixmaps-gl] onRedraw callback failed:', err); } });
+        redrawListeners.slice().forEach(cb => { try { cb(); } catch (err) { console.error('[ixmaps-gl] onRedraw callback failed:', err); } });
         callDrawThemeHooks();
       }
 
@@ -6516,6 +6927,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         };
       }
       _resolveMapReady(engineApi);
+      if (this.mapOptions && this.mapOptions.name) namedMapReady(this.mapOptions.name).resolve(engineApi);
       resolveBuilt();
       namedLoads.forEach(rt => { listenNamedData(rt); if (!rt._deferredLoad) loadNamedTheme(rt, false); });
       return engineApi;
@@ -6547,6 +6959,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // class used throughout this file — a real bug caught during testing
   // (every `new Map()` below silently resolved to *this* function instead)
   function createMap(containerId, options, mapFn) {
+    if (options && options.name) namedMapReady(options.name);
     const builder = new MapBuilder(containerId, options);
     if (mapFn) mapFn(builder);
     // If build() rejects (bad data URL, misconfigured CHOROPLETH join,
@@ -6614,7 +7027,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // flat's mapApi.setView(center, zoom) (htmlgui_flat.js 1327) — the
       // same live-or-build-time split as .view() above
       promise.setView = (...args) => promise.view(...args);
-      promise.options = (...args) => { builder.options(...args); return promise; };
+      // post-build: the live map's options() (merged into the options
+      // object the running themes hold), as .view() above — the builder's
+      // own is read once, by build()
+      promise.options = (...args) => { if (resolvedApi) resolvedApi.options(...args); else builder.options(...args); return promise; };
       promise.attribution = (...args) => { builder.attribution(...args); return promise; };
       promise.legend = (...args) => { builder.legend(...args); return promise; };
       promise.local = (...args) => { builder.local(...args); return promise; };
@@ -6838,11 +7254,6 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // the flat SVG projection a map's options object belongs to (set by the
   // map's init and loadProject; the runtimes only see the options object)
   const flatSvgProjectionByOptions = new WeakMap();
-  // the projection plane a map's VECTOR / BEZIER flows are drawn in: flat's
-  // map file, or the Map() option mapProjection ("equalearth") — flat computes
-  // the curves in its map's own coordinates, so the same flow bows around the
-  // pole there. (Unlike flatSvgProjectionByOptions it leaves the view framing alone.)
-  const flatPlaneProjectionByOptions = new WeakMap();
   // a map that is flat's orthographic one (drawn as MapLibre's globe): its object scale is
   // flat's (scale × the globe's pixels per degree at its center, measured on flat 2026-10-10
   // on the mechanical-goods globe page, the same at view zooms 2.5 and 3.5: 197.44e6; the
@@ -6885,12 +7296,6 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     const radius = 512 * Math.pow(2, zoom) / (2 * Math.PI * c);
     return Math.log2(globeDiscRadius(radius, height > 0 ? height : 768) * 2 * Math.PI / 512);
   }
-  function flatPlaneProjectionOf(mapOptions) {
-    const byUrl = flatSvgProjectionOf(mapOptions.map);
-    if (byUrl) return byUrl;
-    const named = FLAT_SVG_PROJECTIONS[String(mapOptions.mapProjection || '').trim().toLowerCase()];
-    return named || null;
-  }
   // flat SVG map scale ÷ the Mercator one at the same on-screen size (1
   // without a flat SVG projection)
   function flatMapScaleRatio(mapOptions) {
@@ -7113,7 +7518,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       : 1;
   }
 
-  function valueRadius(value, zoom, style, mapOptions, flags, maxSizeValue) {
+  function valueRadius(value, zoom, style, mapOptions, flags, maxSizeValue, sizeBound) {
     const zoomFactor = objectZoomFactor(zoom, mapOptions);
     // FIXSIZE (a symbol chart; PLOT / GRIDSIZE size their markers
     // themselves): one radius for every item, whatever its value — the
@@ -7156,7 +7561,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     if (flags && flags.has('SYMBOL') && !flags.has('BUBBLE') && !flags.has('USER')
       && !flags.has('FIXSIZE') && !flags.has('PLOT') && !flags.has('GRIDSIZE')
       && flags.has('CATEGORICAL') && !flags.has('AGGREGATE') && !flatFlag(flags, 'GROUP')
-      && !style.sizefield) {
+      && !style.sizefield && !sizeBound) {
       const fixed = NORMAL_RADIUS_PX * (styleNum(style.scale) || 1);
       return Math.max(VALUE_RADIUS_MIN, Math.min(VALUE_RADIUS_MAX, fixed * zoomFactor));
     }
@@ -7529,6 +7934,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     return out;
   }
 
+  // the outline colour of a flat bubble icon: none for NOLINES / linecolor "none", else linecolor, else the
+  // class colour's darker derivate — and none when there is neither (an unfilled "none" class has no colour
+  // to derive from; with a linecolor its outline must still draw)
+  function bubbleStrokeRgb(look, rgb) {
+    return look.noStroke ? null : (look.stroke || (rgb ? flatDerivateRgb(rgb, 0.7) : null));
+  }
+
   // ChartColors.textColor (colorscheme.js 104-116): darker on light colors
   function flatChartTextRgb(rgb) {
     return flatDerivateRgb(rgb, rgb[0] + rgb[1] + rgb[2] > 450 ? 0.6 : 3);
@@ -7678,8 +8090,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     _measureCtx.font = fontPx + 'px arial';
     return _measureCtx.measureText(text).width;
   }
-  function wrapTitleLines(text, fontPx, widthPx) {
-    const width = w => titleTextWidth(w, fontPx);
+  function wrapTitleLines(text, fontPx, widthPx, measure = titleTextWidth) {
+    const width = w => measure(w, fontPx);
     const lines = [];
     for (const word of String(text).split(/\s+/).filter(Boolean)) {
       const last = lines.length ? lines[lines.length - 1] + ' ' + word : null;
@@ -8629,39 +9041,55 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     return { bars, texts, lines, extent: ext[0] <= ext[2] ? ext : [0, 0, 0, 0], width: W, sizer };
   }
 
-  // flat's BOX and TITLE around a chart (maptheme.js 18758-18905), in the
-  // chart's units: `extent` the chart's [x0, y0, x1, y1]; o: { margin
-  // (boxmargin, 2), titleFont, title (text or ''), bottomTitle, alignRight,
-  // measure }. The margin is min(2 m, m · width / 30); the title's first
-  // baseline 0.7 font above the chart (BOTTOMTITLE: one font below), its
-  // lines wrapped to the chart's width and stacked upward; the box encloses
-  // chart and title, its top trimmed by 0.1 font when titled. Returns
-  // { rect: [x0, y0, x1, y1], title: { lines, x, anchor, baseline, font } | null }
-  function flatChartBox(extent, o) {
+  // THE box-and-title layout of every chart type (flat's BOX block,
+  // maptheme.js 18757-18925): single symbol, SEQUENCE, PIE and BAR all call
+  // this. `extent`: the chart's drawn [x0, y0, x1, y1] around its anchor (px;
+  // chart units with unit 1). o: { unit (px per flat unit, default 1), margin
+  // (boxmargin, flat's 2), circular (CIRCULARBOX), radius / center (the
+  // circle's base radius and center; default the extent's half longer side
+  // and its center), titleText (with the titleunits suffix, '' / null: no
+  // title), titleFont (px, or w => px for DTEXT), bottomTitle, alignRight,
+  // wrap, measure }. Returns { rect (rectangular box), boxR / cx / cy (the
+  // circular box: radius, center), w (the extent's width), title { text,
+  // lines, x, anchor, top, baseline, f, extent } }.
+  // The margin is min(2 m u, m w / 30); the title's first baseline 0.7 font
+  // above the box (BOTTOMTITLE: one font below), wrapped to the chart's width
+  // (the circle's diameter); a rectangular box grows to enclose the title,
+  // its top trimmed by 0.1 font. arial: ascent 0.905, descent 0.212.
+  function chartBoxLayout(extent, o) {
     const e = extent.slice();
-    const w = e[2] - e[0];
-    const margin = Math.min(2 * o.margin, o.margin * w / 30);
+    const w = e[2] - e[0], h = e[3] - e[1];
+    const unit = o.unit == null ? 1 : o.unit;
+    const circular = !!o.circular;
+    const margin = Math.min(2 * o.margin * unit, o.margin * w / 30);
+    const center = o.center || [(e[0] + e[2]) / 2, (e[1] + e[3]) / 2];
+    const boxR = circular ? (o.radius != null ? o.radius : Math.max(w, h) / 2) * 1.1 + margin : 0;
     let title = null;
-    if (o.title) {
-      const f = o.titleFont;
-      const measure = o.measure || ((text, font) => text.length * font * 0.55);
-      const lines = [];
-      for (const word of String(o.title).split(/\s+/).filter(Boolean)) {
-        const last = lines.length ? lines[lines.length - 1] + ' ' + word : null;
-        if (last !== null && measure(last, f) <= w) lines[lines.length - 1] = last;
-        else lines.push(word);
-      }
+    if (o.titleText) {
+      const f = typeof o.titleFont === 'function' ? o.titleFont(w) : o.titleFont;
+      const measure = o.measure || titleTextWidth;
+      const lines = wrapTitleLines(o.titleText, f, circular ? boxR * 2 : w, measure).split('\n');
       const width = Math.max(...lines.map(l => measure(l, f)));
-      const baseline = o.bottomTitle ? e[3] + f : e[1] - 0.7 * f - (lines.length - 1) * f;
-      const x = o.alignRight ? e[2] : e[0];
-      const x0 = o.alignRight ? x - width : x;
-      title = { lines, x, anchor: o.alignRight ? 'end' : 'start', baseline, font: f };
-      e[0] = Math.min(e[0], x0);
-      e[1] = Math.min(e[1], baseline - 0.905 * f) + 0.1 * f;
-      e[2] = Math.max(e[2], x0 + width);
-      e[3] = Math.max(e[3], baseline + (lines.length - 1) * f + 0.212 * f);
+      // first baseline; lines go down one font each
+      const base = circular
+        ? (o.bottomTitle ? center[1] + boxR + f : center[1] - boxR - 0.7 * f - (lines.length - 1) * f)
+        : (o.bottomTitle ? e[3] + f : e[1] - 0.7 * f - (lines.length - 1) * f);
+      const x = circular ? center[0] + unit / 2 : (o.alignRight ? e[2] : e[0]);
+      const anchor = circular ? 'middle' : (o.alignRight ? 'end' : 'start');
+      const x0 = anchor === 'middle' ? x - width / 2 : anchor === 'end' ? x - width : x;
+      title = { text: lines.join('\n'), lines, x, anchor, top: base - 0.8 * f, baseline: base, f,
+        extent: [x0, base - 0.905 * f, x0 + width, base + (lines.length - 1) * f + 0.212 * f] };
     }
-    return { rect: [e[0] - margin, e[1] - margin, e[2] + margin, e[3] + margin], title, width: w };
+    let rect = null;
+    if (!circular) {
+      const b = e.slice();
+      if (title) {
+        b[0] = Math.min(b[0], title.extent[0]); b[1] = Math.min(b[1], title.extent[1]) + 0.1 * title.f;
+        b[2] = Math.max(b[2], title.extent[2]); b[3] = Math.max(b[3], title.extent[3]);
+      }
+      rect = [b[0] - margin, b[1] - margin, b[2] + margin, b[3] + margin];
+    }
+    return { rect, boxR, cx: center[0], cy: center[1], w, margin, title };
   }
 
   // CHART|PIE / DONUT: one pie's slices as real ixmaps-flat lays them out —
@@ -8693,10 +9121,38 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   //    centered on 12 o'clock), HALF over 180° from 270° (HALFPLUS10 200°
   //    from 260°, HALFMINUS10 160° from 280°, HALFPLUS20 220° from 250°,
   //    HALFMINUS20 140° from 290°)
+  //  - STARBURST (piechart.js 246, 324-355, 415-420): every part >= 0, the
+  //    angles EQUAL (the value is the ray's radius, not its sweep) and the
+  //    percents NOT normalized — raw values. The FLOWER/RAYS variants
+  //    (XLFLOWER/XLRAYS, LFLOWER/LRAYS, XSFLOWER/XSRAYS, SFLOWER/SRAYS,
+  //    FLOWER/RAYS) cap the ray angle (maxAngle / 4 / 12 / 10 / none) and
+  //    inset a gap (10 / 20 / 40 / 33 / 35 % of it) on both sides of each
+  //    ray. The ray RADIUS is
+  //    computed in _buildPieLayers (it needs the theme's maxValue)
   function pieSliceLayout(values, t, opts = {}) {
     t = String(t || '');
     const has = re => re.test(t);
-    const parts = values.map(v => (isNaN(v) ? 0 : v));
+    // flat's STARBURST (piechart.js realize 246, 324-355, 415-420): the
+    // parts get EQUAL angles — the value is the ray's radius, not its
+    // sweep — and every part is clamped to >= 0. The FLOWER/RAYS
+    // variants (flat maps XLFLOWER to XLRAYS & kin, maptheme.js
+    // 20169-20186) cap the ray angle and leave a gap between the rays.
+    // flat's `nRadInner = max(5, nRadInner)` for the ray variants is 5
+    // units of the chart's INTERNAL coordinate system — measured on the
+    // ISTAT story: 5 of the disc's 197 internal units, 0.28 screen px,
+    // sub-pixel and invisible (the petals go to the center; an inner
+    // radius shows only with DONUT) — so starInner here is 0 for the
+    // ray variants too, and only DONUT+STARBURST starts its rays at
+    // the donut's inner radius (see _buildPieLayers)
+    const star = has(/STARBURST/);
+    const starRay = !star ? null
+      : /XLFLOWER|XLRAYS/.test(t) ? { cap: 4, gap: 0.10 }
+      : /LFLOWER|LRAYS/.test(t) ? { cap: 4, gap: 0.20 }
+      : /XSFLOWER|XSRAYS/.test(t) ? { cap: 12, gap: 0.40 }
+      : /SFLOWER|SRAYS/.test(t) ? { cap: 10, gap: 0.33 }
+      : /FLOWER|RAYS/.test(t) ? { cap: 1, gap: 0.35 }
+      : { cap: 1, gap: 0 };
+    const parts = values.map(v => (isNaN(v) ? 0 : star ? Math.max(0, v) : v));
     const sum = parts.reduce((a, v) => a + v, 0);
     const autocomplete = has(/AUTOCOMPLETE/);
     if (sum === 0 && !autocomplete) return null;
@@ -8749,13 +9205,18 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // flat draws its "Pie error: no values !" circle here
     if (!any && !autocomplete) return null;
     const pctSum = slices.reduce((a, sl) => a + sl.percent, 0);
-    if (pctSum !== 100) {
+    // flat's STARBURST keeps the parts' raw values (piechart.js 246-258:
+    // no 100% normalization, no AUTOCOMPLETE) — the value is the radius
+    if (!star && pctSum !== 100) {
       if (autocomplete && pctSum < 100) slices.push({ i: -1, value: null, percent: Math.floor((100 - pctSum) * 100000) / 100000, complement: true });
       else slices.forEach(sl => { sl.percent = sl.percent / pctSum * 100; });
     }
     let end = 0;
     if (has(/SYMMETRIC/) && slices.length) {
-      if (has(/BIGTOTOP/)) {
+      if (star) {
+        // flat piechart.js 296-299: the first ray centered on 12 o'clock
+        end = 360 - Math.floor(360 / parts.length / 2);
+      } else if (has(/BIGTOTOP/)) {
         end = 360;
         let x = 0;
         for (; x < slices.length && slices[x] !== biggest; x++) end -= slices[x].percent < 100 ? Math.floor(360 / 100 * slices[x].percent) : 0;
@@ -8776,6 +9237,20 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     if (has(/HALFMINUS20/)) maxAngle = 140;
     const out = [];
     slices.forEach((sl, k) => {
+      if (star) {
+        // flat piechart.js 324-355, 395-403: the angles advance by the
+        // FULL equal angle (the ray variants capped), the gap inset on
+        // both sides of a ray; a ray's own sweep is that reduced angle
+        const angle = Math.min(maxAngle / starRay.cap, maxAngle / parts.length);
+        const base = end % 360;
+        end = base + angle;
+        if (end > 360) end = end % 360;
+        const sweep = angle * (1 - 2 * starRay.gap);
+        const start = base + angle * starRay.gap;
+        if (sweep <= 0 || start < 0) return;
+        out.push(Object.assign(sl, { start, sweep, k }));
+        return;
+      }
       const sweep = sl.percent / 100 * maxAngle;
       const start = end % 360;
       end = start + sweep;
@@ -8902,6 +9377,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     const parts = [], zeroNot = [];
     for (let k = 0; k < o.fields.length; k++) {
       let v = parseFloat(raw[o.fields[k]]);
+      // flat's weights multiply every record's per-field value as it is
+      // accumulated (maptheme.js 10506-10508) — the SIZE (nValueSize)
+      // stays raw, exactly as there
+      if (o.weights) v = v * o.weights(k);
       zeroNot[k] = false;
       if (isNaN(v)) {
         if (!r.undefinedOk) return null;
@@ -9111,6 +9590,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     for (let i = 0; i < str.length; i++) { h ^= str.charCodeAt(i); h = Math.imul(h, 16777619); }
     return (h >>> 0) / 4294967296;
   }
+  // a flow's dash phase in [0, 1): flat's random one, the same for the
+  // same arc on every rebuild
+  function flowDashPhase(p1, p2) {
+    return hashUnit('dash:' + p1[0] + ',' + p1[1] + '&' + p2[0] + ',' + p2[1]);
+  }
 
   // points of a cubic Bézier, n segments (n + 1 points)
   function cubicBezierPoints(p0, c1, c2, p3, n) {
@@ -9273,14 +9757,21 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     const up = fl.up;
     const maxR = opts.maxRadius || 0;
     const nStarParts = opts.nParts || counts.length;
-    let angle = 0, starR = null, x = 0;
+    // flat's star radius (nStarRadius, 0 per chart) is set ONLY by the FIRST
+    // part of the sorted order (maptheme.js 22301-22316: `if (i === 0)`), and a
+    // part of value 0 is skipped before it (22222): a chart whose first part
+    // (with SORT|UP the smallest) is 0 keeps star radius 0, so with UP every
+    // part sits on the center — only a chart with ALL parts non-zero spreads
+    // into its star. (A cell of a CATEGORICAL AGGREGATE theme has a zero part
+    // for every category it lacks.)
+    let angle = 0, starR = 0, x = 0;
     order.forEach((p, k) => {
       if (!p.v) return;
       const r = radiusOf(p.v);
       if (!(r > 0)) return;
       let px = 0, py = 0;
       if (star) {
-        if (starR === null) {
+        if (k === 0) {
           starR = r;
           if (fl.expand && fl.sort && up) {
             const big = order[order.length - 1].v, mv = opts.maxValue || big || 1;
@@ -9288,7 +9779,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           }
           if (fl.compress) starR *= fl.compressmax ? 0.25 : 0.5;
         }
-        if (parts.length > 0 || up) {
+        // flat: `(i > 0 || UP) && nRadius` — i the part's index in the sorted order
+        if (k > 0 || up) {
           const c = starR + r;
           const b = Math.sqrt(Math.max(0, c * c - r * r));
           let f = 90 - Math.asin(Math.min(1, b / c)) / Math.PI * 180;
@@ -9837,7 +10329,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // 7740-7801): a value that is no number counts as 0 — unless
   // UNDEFINEDISNOTVALUE —, and 0 is a value — unless ZEROISNOTVALUE
   function flatNumber(v, flags) {
-    let n = parseFloat(v);
+    // flat's own value scan (maptheme.js __scanValue 9265-9272): a
+    // value with a comma is EUROPEAN format — dots stripped as
+    // thousands separators, the comma is the decimal ("78,8" -> 78.8);
+    // a value without one is parsed plain, blanks stripped. Applied
+    // to every theme value in flat, so also here
+    const s = String(v);
+    let n = s.includes(',') ? parseFloat(s.replace(/\./g, '').replace(/,/g, '.')) : parseFloat(s.replace(/ /g, ''));
     if (isNaN(n)) n = flags && flags.has('UNDEFINEDISNOTVALUE') ? NaN : 0;
     if (n === 0 && flags && flags.has('ZEROISNOTVALUE')) return NaN;
     return n;
@@ -9848,6 +10346,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     const bins = [arr.reduce((a, v) => (v < a ? v : a), Infinity), m];
     while (arr.length > 1) {
       arr = arr.filter(d => d > m);
+      // every value left equals the last mean (a tie at the top): there is
+      // no head above it — mean([]) would add a NaN break (flat's own bug)
+      if (!arr.length) break;
       m = mean(arr);
       bins.push(m);
     }
@@ -9898,6 +10399,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // values above the last mean, while more than one is left
     if (flags.has('HEADTAIL')) {
       const b = headTailBreaks(values);
+      // fewer breaks than classes (small or low-variance data): the surplus
+      // classes padded at the top with the last break, as naturalBreaks
+      // does — flat reads past the end (undefined bounds, records in no class)
+      while (b.length < nParts + 1) b.push(b[b.length - 1]);
       parts = new Array(nParts).fill(null).map((_, i) => ({ min: b[i], max: b[i + 1] - 0.000001 }));
     } else if (flags.has('QUANTILE')) parts = quantileBreaks(values, nParts);
     else if (flags.has('NATURAL')) parts = naturalBreaks(values, nParts);
@@ -10010,7 +10515,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   function fieldWeightOf(style, nFields, repeatLast) {
     const w = style && style.weights;
     if (w == null || w === '') return null;
-    const list = (Array.isArray(w) ? w.join('|') : String(w)).split('|').map(v => parseFloat(v));
+    // flat's toArray (maptheme.js 999-1014): split on '|' when the
+    // string has one, else on ',' — "1,10,10" is a THREE-weight list
+    // (the Happy Planet page), not one weight of 1
+    const s = Array.isArray(w) ? w.join('|') : String(w);
+    const list = (s.includes('|') ? s.split('|') : s.split(',')).map(v => parseFloat(v));
     if (!list.some(v => !isNaN(v))) return null;
     if (repeatLast) { const last = list[list.length - 1]; while (list.length < nFields) list.push(last); }
     return i => list[i] || list[0] || 1;
@@ -10019,9 +10528,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // the value fields' own values weighted — the class value and the field100
   // value stay raw, exactly as flat reads them
   function weightedRecord(f, weightOf) {
+    // a pie record's parts were weighted in flatPieRecord, and its size
+    // (nValueSize) stays raw — nothing to do here
+    if (f.properties && f.properties.pie) return f;
     const p = Object.assign({}, f.properties);
     if (p.value !== undefined && !isNaN(p.value)) p.value = p.value * weightOf(0);
     if (Array.isArray(p.series)) p.series = p.series.map((v, i) => (isNaN(v) ? v : v * weightOf(i)));
+    // the multi-field pie's parts — the SAME per-field values as series,
+    // but the grid cell's pie accumulates THESE (flatPieAccumulate's
+    // rec.parts), so they carry the weights too
+    if (Array.isArray(p.parts)) p.parts = p.parts.map((v, i) => (isNaN(v) ? v : v * weightOf(i)));
     return Object.assign({}, f, { properties: p });
   }
   function applyField100(features, binding, flags, style) {
@@ -10044,7 +10560,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     return features.map(f => {
       if (!f || !f.properties) return f;
       const props = Object.assign({}, f.properties);
-      let values = names.map(name => parseFloat(f.properties[name]));
+      let values = names.map(name => flatScanValue(f.properties[name]));
       // the weights run BEFORE the field100 arithmetic, as in flat's
       // addItemValues — the FRACTION of a weighted value is the weighted
       // per-unit value
@@ -10053,7 +10569,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const sum = auto100 ? values.reduce((a, v) => a + (isNaN(v) ? 0 : v), 0) : 0;
         values = values.map((v, i) => {
           if (isNaN(v)) return v;
-          const v100 = auto100 ? sum : parseFloat(f.properties[f100A[Math.min(i, f100A.length - 1)]]);
+          const v100 = auto100 ? sum : flatScanValue(f.properties[f100A[Math.min(i, f100A.length - 1)]]);
           if (v === 0 && !flags.has('ZEROISVALUE')) return 0;
           if (fields[i][0] === '!') return (isNaN(v100) ? 0 : v100) - v;
           if (flags.has('CALCVAL') || flags.has('CALC100')) return v100 ? Math.round(v * v100 / 100) : v;
@@ -10099,7 +10615,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // DIFFERENCE over several value fields: the difference is the value
     const fields = String(binding.value).split('|');
     const valueOf = flags && flags.has('DIFFERENCE') && fields.length > 1
-      ? p => cellAggregatedValues({ sums: fields.map(k => parseFloat(p[k]) || 0), counts: fields.map(() => 1) }, flags, style)[0]
+      // without AGGREGATE applyField100 already differenced every record
+      // (flat's nValuesA, popped): the first field IS the value
+      ? (!flags.has('AGGREGATE') ? p => flatNumber(p[fields[0]], flags)
+        : p => cellAggregatedValues({ sums: fields.map(k => parseFloat(p[k]) || 0), counts: fields.map(() => 1) }, flags, style)[0])
       // "$item$" is flat's record count: 1 per record
       : binding.value === '$item$' ? () => 1
       : p => (p && Object.keys(p).length ? flatNumber(p[binding.value], flags) : NaN);
@@ -10395,13 +10914,18 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         if (cell.titleMax === undefined || (maxAgg ? m > cell.titleMax : m < cell.titleMax)) {
           cell.titleMax = m;
           cell.titleFrom = f;
+          cell.titleX = p.x; cell.titleY = p.y;
         }
       }
     }
     const out = [];
     for (const cell of cells.values()) {
-      const x = relocate ? cell.sumX / cell.n : cell.snapped.x;
-      const y = relocate ? cell.sumY / cell.n : cell.snapped.y;
+      // RELOCATE: at the records' mean position — with MAX / MIN at the
+      // record holding the max (min), the one the cell IS (and its title's);
+      // only the position follows it, never a value
+      const atTitle = relocate && cell.titleFrom;
+      const x = atTitle ? cell.titleX : relocate ? cell.sumX / cell.n : cell.snapped.x;
+      const y = atTitle ? cell.titleY : relocate ? cell.sumY / cell.n : cell.snapped.y;
       const ll = worldPixelToLngLat(x, y, zoom);
       const geometry = { type: 'Point', coordinates: [ll.lng, ll.lat] };
       const hasClass = cell.first.properties.classValue !== undefined;
@@ -10702,17 +11226,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // could ever need it (a plain "px" gridwidth, or an aggregation
       // array with only "px" entries, never reads this field).
       const gridwidthIsMeters = typeof this.style.gridwidth === 'string' ? !/px\s*$/i.test(this.style.gridwidth) : this.style.gridwidth != null;
-      if (gridwidthIsMeters || aggregationHasMetersEntry(this.style.aggregation)) {
-        let minLat = Infinity, maxLat = -Infinity;
-        this.features.forEach(f => {
-          const lat = f.geometry && f.geometry.coordinates && f.geometry.coordinates[1];
-          if (typeof lat === 'number' && !isNaN(lat)) {
-            if (lat < minLat) minLat = lat;
-            if (lat > maxLat) maxLat = lat;
-          }
-        });
-        this._gridRefLat = (minLat <= maxLat) ? (minLat + maxLat) / 2 : 0;
-      }
+      // aggregationscale: flat's alias of aggregation, read the same way in
+      // _ensureClusterIndices
+      if (gridwidthIsMeters || aggregationHasMetersEntry(this.style.aggregation || this.style.aggregationscale)) this._scanGridRefLat();
 
       // a bar chart's parts are a pie's (its value fields or categories)
       if ((this._isPieChart() || this._isBarChart()) && this.binding.value) {
@@ -10799,6 +11315,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         let max = 0;
         for (const f of this.features) for (const field of this._multiFields) { const v = Math.abs(parseFloat(f.properties[field])); if (v > max) max = v; }
         this._multiFieldPartMax = max || 1;
+        // AUTO100's scale, measured on these features by _buildSequenceChartLayers
+        this._seqAuto100Max = null;
       } else if (this.binding.value) {
         // real engine's OTHER coloring mode (maptheme.js distributeValues,
         // partsA): a NUMERIC bound value, not CATEGORICAL, is classed into
@@ -10988,6 +11506,14 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     _resolveAggregateValue(props) { return resolveAggregateValue(this.binding, this.flags, props); }
 
     _buildAggregationIndex(sourceFeatures) {
+      // only records with a point position are drawn: a GeoJSON feature may
+      // have geometry null (RFC 7946 — open-data exports of unlocated
+      // records), or a shape chartAnchoredFeatures could not anchor; they
+      // stay in the data (counts, facets), as on flat, but have no chart
+      sourceFeatures = sourceFeatures.filter(f => {
+        const c = f.geometry && f.geometry.coordinates;
+        return !!c && typeof c[0] === 'number' && isFinite(c[0]) && isFinite(c[1]);
+      });
       // an AGGREGATE / CATEGORICAL pie: one bucket, each record carrying its
       // contribution to its item (flatPieRecord), added up per position or
       // grid cell by aggregateOnGrid (flatPieAccumulate)
@@ -10997,9 +11523,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const rules = flatValueRules(t, fields ? fields.length : 1);
         const sizeField = this.binding.size && this.binding.size !== '$item$' ? this.binding.size : null;
         const feats = [];
+        // flat's per-field weights (maptheme.js 10506-10508), applied to
+        // every record's parts inside flatPieRecord
+        const pieWeightOf = fieldWeightOf(this.style, fields ? fields.length : 1, true);
         for (const f of sourceFeatures) {
-          const c = f.geometry && f.geometry.coordinates;
-          if (!c || typeof c[0] !== 'number' || !isFinite(c[0]) || !isFinite(c[1])) continue;
           const p = f.properties || {};
           let cat;
           if (this._pieCategorical) {
@@ -11007,7 +11534,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
             const i = k == null ? undefined : this._pieCategoryIndex.get(k);
             cat = i == null ? -1 : i;
           }
-          const pie = flatPieRecord(p, { rules, sizeField, cat, fields });
+          const pie = flatPieRecord(p, { rules, sizeField, cat, fields, weights: pieWeightOf });
           if (!pie) continue;
           feats.push({ type: 'Feature', geometry: f.geometry, properties: { value: pie.size, pie, raw: p } });
         }
@@ -11066,7 +11593,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const seriesFields = String(this.binding.value || '').split('|');
         this._seriesDifference = this.flags.has('DIFFERENCE') && seriesFields.length > 1 && !this._aggregateField100;
         const seriesOf = props => seriesFields.map(k => parseFloat(props[k]) || 0);
-        const seriesValue = props => cellAggregatedValues({ sums: seriesOf(props), counts: seriesFields.map(() => 1) }, this.flags, this.style)[0];
+        // without AGGREGATE the records are already differenced (applyField100)
+        const seriesValue = !this.flags.has('AGGREGATE') ? props => parseFloat(props[seriesFields[0]]) || 0 : props => cellAggregatedValues({ sums: seriesOf(props), counts: seriesFields.map(() => 1) }, this.flags, this.style)[0];
         this._featuresByCategory = [sourceFeatures.map(f => ({
           type: 'Feature',
           geometry: f.geometry,
@@ -11424,6 +11952,20 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       });
     }
 
+    // the meters grid's reference latitude: the middle of the data's own
+    // latitude extent (see _prepare)
+    _scanGridRefLat() {
+      let minLat = Infinity, maxLat = -Infinity;
+      this.features.forEach(f => {
+        const lat = f.geometry && f.geometry.coordinates && f.geometry.coordinates[1];
+        if (typeof lat === 'number' && !isNaN(lat)) {
+          if (lat < minLat) minLat = lat;
+          if (lat > maxLat) maxLat = lat;
+        }
+      });
+      this._gridRefLat = (minLat <= maxLat) ? (minLat + maxLat) / 2 : 0;
+    }
+
     // (re)builds the per-category GridAggregateIndex for the grid width
     // resolved at the given zoom, only when that width changed. Grid width,
     // as flat reads it (maptheme.js:1892-1908, 7990-8008): gridwidthpx and
@@ -11434,6 +11976,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // style.aggregation bracket; none → no grid (exact positions).
     _ensureClusterIndices(zoom) {
       let radiusPx;
+      // a meters grid set later by setStyle (gridwidth / aggregation) never
+      // went through _prepare's scan — not the equator, the data's latitude
+      if (this._gridRefLat === undefined) this._scanGridRefLat();
       // GL-PORT COMPAT: a real-ixmaps-flat page's own gridwidth is
       // sometimes a fixed SCREEN-PIXEL size (e.g. style.gridwidth:"3px",
       // confirmed against a real ported page) rather than this engine's
@@ -11480,6 +12025,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         this._clusterUsesFixedZoom = false;
       }
       if (this._clusterIndices && this._clusterRadiusPx === radiusPx && this._clusterField === aggField) return;
+      // new cells (e.g. a runtime gridwidth): the zoom-keyed stats of the
+      // old ones (breaks, NORMALIZE, NOOUTLIER, sizeMax) no longer apply
+      this._aggregateStatsCache = null;
       this._clusterRadiusPx = radiusPx;
       this._clusterField = aggField;
       // after aggregation, on the cell sums: field100 of a value-based
@@ -11671,6 +12219,91 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       return Array.isArray(cs) && cs.length === 1 && String(cs[0]).trim().toLowerCase() === 'none';
     }
 
+    // an external symbol file (.svg/.png/.jpeg) named by `symbols` — flat draws it as an
+    // <image> (maptheme.js 21743, 22168), not as the chart's own shape. null for a shape name
+    _urlSymbolOf(sym) {
+      if (typeof sym !== 'string') return null;
+      const s = sym.trim();
+      // a data: URI is a symbol file too, and the only kind fetch() can read on a file:// page
+      return /\.(svg|png|jpe?g)([?#]|$)/i.test(s) || /^data:image\/(svg\+xml|png|jpe?g)[;,]/i.test(s) ? s : null;
+    }
+
+    // the symbol file as an IconLayer icon descriptor, NOT tinted (flat doesn't recolor an
+    // <image> either); fetched and rasterized once per URL, shared by SEQUENCE and plain symbols
+    _urlSymbolIcon(u) {
+      if (!this._urlIconCache) this._urlIconCache = new Map();
+      if (!this._urlIconCache.has(u)) {
+        // the placeholder is a transparent 1x1 PNG, NOT the raw symbol
+        // URL: deck.gl would immediately try to load that itself, and an
+        // SVG without natural dimensions (a viewBox only, the bus
+        // pictogram of the City-moving page) makes Chrome's
+        // createImageBitmap throw — a console error and a part that
+        // never renders. The real raster replaces it below
+        const entry = { url: TRANSPARENT_1PX_PNG, width: 256, height: 256, anchorX: 128, anchorY: 128, mask: false, id: 'seq-sym-pending:' + u };
+        this._urlIconCache.set(u, entry);
+        // fetch the symbol ONCE and rasterize it into the descriptor's
+        // own 256px cell here: deck then always sees exactly the declared
+        // dimensions, and dimension-less SVGs work like any other. The
+        // redraw lets the next getIcon see the patched descriptor
+        fetch(u).then(r => r.ok ? r.text() : null).then(text => new Promise((resolve, reject) => {
+          if (typeof text !== 'string' || !/<svg[\s>]/i.test(text)) { reject(new Error('not svg')); return; }
+          if (!/\swidth\s*=/i.test(text) || !/\sheight\s*=/i.test(text)) {
+            const vb = text.match(/viewBox\s*=\s*["']([^"']*)["']/i);
+            const p = vb && vb[1].trim().split(/[\s,]+/).map(Number);
+            if (p && p.length === 4 && isFinite(p[2]) && p[2] > 0 && isFinite(p[3]) && p[3] > 0) {
+              text = text.replace(/<svg/i, '<svg width="' + p[2] + '" height="' + p[3] + '"');
+            }
+          }
+          const img = new Image();
+          img.onload = () => resolve(img);
+          img.onerror = () => reject(new Error('svg decode failed'));
+          img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(text);
+        })).then(img => {
+          const size = entry.width;
+          const canvas = document.createElement('canvas');
+          canvas.width = size; canvas.height = size;
+          const ctx = canvas.getContext('2d');
+          const s = Math.min(size / (img.naturalWidth || size), size / (img.naturalHeight || size));
+          const dw = (img.naturalWidth || size) * s, dh = (img.naturalHeight || size) * s;
+          ctx.drawImage(img, (size - dw) / 2, (size - dh) / 2, dw, dh);
+          entry.url = canvas.toDataURL('image/png');
+          entry.id = 'seq-sym-raster:' + u;
+          if (this._triggerRedraw) this._triggerRedraw();
+        }).catch(() => {
+          // a symbol FILE of a file:// page can't be fetched (nor loaded by deck): say so once
+          let onDisk = false;
+          try { onDisk = new URL(u, location.href).protocol === 'file:'; } catch (e) { /* not a URL */ }
+          if (onDisk && !this._warnedFileSymbol) {
+            this._warnedFileSymbol = true;
+            console.warn('[ixmaps-gl] symbol file "' + u + '" cannot be loaded from a file:// page — serve the page over http(s) or give the symbol as a data: URI');
+          }
+          // not an SVG (a PNG/JPEG symbol): deck's own URL loading takes
+          // it from here — and a pre-sized SVG that failed to rasterize
+          // gets that same second chance
+          entry.url = u;
+          entry.id = 'seq-sym-natural:' + u;
+          if (this._triggerRedraw) this._triggerRedraw();
+        });
+      }
+      return this._urlIconCache.get(u);
+    }
+
+    // a size field is bound (flat's szSizeField): .binding({size}) or style.sizefield, live —
+    // setSizeField() rebinds at runtime. '$item$' is not a field
+    _sizeBound() { return !!(this.binding.size && this.binding.size !== '$item$'); }
+
+    // the symbol file of a plain (non-SEQUENCE) item, or null: the same class→symbol /
+    // symbolfield mapping as _resolveSymbolShape, before it folds unknown names to 'circle'
+    _resolveSymbolUrl(props) {
+      const s = this.style.symbols;
+      if (!Array.isArray(s)) return null;
+      if (!this.style.symbolfield) {
+        const cat = props && props.cat != null ? props.cat : 0;
+        return this._urlSymbolOf(s[Math.min(cat, s.length - 1)]);
+      }
+      return this._urlSymbolOf(this._resolveSymbolShape(props));
+    }
+
     _buildSingleIcon(colorRgb, opacity, shape, borderColorRgb, borderWidth, borderOpacity = 1) {
       if (!colorRgb) { colorRgb = [128, 128, 128]; opacity = 0; } // no class colour (["none"]): unfilled
       shape = shape || 'circle';
@@ -12080,7 +12713,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // companion layer) takes the uniform mesh shortcut.
       if (this.flags.has('GRIDSIZE') && this.flags.has('PLOT')) return this._buildPlotLayers(zoom, bbox);
       // PLOT without GRIDSIZE: one line chart per item over its value fields
-      if (this.flags.has('PLOT') && this._isItemPlot()) return this._buildItemPlotLayers(zoom);
+      if (this.flags.has('PLOT') && this._isItemPlot()) return this._buildItemPlotLayers(zoom, liveZoom);
       // a plain grid (one color, no values or glow — the Germany page's
       // companion "grid" layer) as one square per cell; a classed GRIDSIZE
       // chart (the fuel-price page) is a symbol chart sized to the grid,
@@ -12666,16 +13299,20 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       return explicit ? fields.map((f, i) => String(explicit[i] != null ? explicit[i] : f)) : fields;
     }
 
-    _buildItemPlotLayers(zoom) {
+    _buildItemPlotLayers(zoom, liveZoom = zoom) {
       const fields = this._itemPlotFields();
       const items = [];
       let dMin = Infinity, dMax = -Infinity;
+      // facet / runtime WHERE / time frame narrow the drawn charts, as in
+      // every other renderer; the value range stays the full data's (as
+      // the bubbles' _maxSizeValue), so a filter does not rescale them
+      const active = this._activeFeatures ? new Set(this._activeFeatures) : null;
       for (const f of this.features) {
         const pos = itemAnchor(f.geometry);
         if (!pos) continue;
         const values = fields.map(k => parseFloat(f.properties[k]));
         for (const v of values) if (!isNaN(v)) { dMin = Math.min(dMin, v); dMax = Math.max(dMax, v); }
-        items.push({ geometry: { type: 'Point', coordinates: pos }, properties: { values, raw: f.properties } });
+        if (!active || active.has(f)) items.push({ geometry: { type: 'Point', coordinates: pos }, properties: { values, raw: f.properties } });
       }
       if (!items.length) return [];
       const sMin = styleNum(this.style.minvalue), sMaxRaw = this.style.maxvalue;
@@ -12694,7 +13331,18 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const S = 2 * NORMAL_RADIUS_PX * (styleNum(this.style.scale) || 1) * objectZoomFactor(zoom, this.mapOptions);
       const color = parseCssColor(Array.isArray(this.style.colorscheme) ? this.style.colorscheme[0] : this.style.colorscheme) || [0, 102, 204];
       const fillOpacity = styleNum(this.style.fillopacity);
-      return [new IconLayer({
+      // BOX / TITLE: flat's chart-group box around every chart; the chart's
+      // drawn extent is its plot geometry's bounding box (chart units × S px,
+      // y up in the geometry, down on screen)
+      const boxRows = this._boxRows(items, { unit: S / (2 * NORMAL_RADIUS_PX), liveZoom, extentOf: d => {
+        const b = itemPlotGeometry(d.properties.values, rangeFor(d.properties.values), this.style, this.flags, sizeMax).bbox;
+        return [b.x0 * S, -b.y1 * S, b.x1 * S, -b.y0 * S];
+      } });
+      const boxLayers = boxRows ? this._boxTitleLayers(boxRows, {
+        unit: S / (2 * NORMAL_RADIUS_PX), liveZoom, positionOf: b => b.d.geometry.coordinates, offsetOf: () => [0, 0],
+        ids: { circle: `ix-itemplot-box-${this.name}`, icon: `ix-itemplot-box-${this.name}`, polygons: `ix-itemplot-box-polygons-${this.name}`, titles: `ix-itemplot-titles-${this.name}` }
+      }) : { box: [], titles: [] };
+      return [...boxLayers.box, new IconLayer({
         id: `ix-itemplot-${this.name}-g${this._iconGeneration}`,
         data: items, pickable: true,
         getPosition: d => d.geometry.coordinates,
@@ -12704,7 +13352,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         getSize: d => this._buildItemPlotIcon(d.properties.values, rangeFor(d.properties.values), sizeMax, color, fillOpacity).heightUnits * S,
         sizeUnits: 'pixels',
         updateTriggers: { getSize: [S] }
-      })];
+      }), ...boxLayers.titles];
     }
 
     // canvas for one per-item PLOT chart (itemPlotGeometry), RASTER px per
@@ -12842,14 +13490,22 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       datasetMax = datasetMax || 1;
       if (isNaN(normalSizeValue)) normalSizeValue = datasetMax;
 
-      return [new IconLayer({
+      // BOX / TITLE: flat's chart-group box around every chart; the chart is
+      // the iconSize square on the cell's center (flat's chart size is 30 units)
+      const boxRows = this._boxRows(data, { unit: iconSize / 30, liveZoom: zoom,
+        extentOf: () => [-iconSize / 2, -iconSize / 2, iconSize / 2, iconSize / 2] });
+      const boxLayers = boxRows ? this._boxTitleLayers(boxRows, {
+        unit: iconSize / 30, liveZoom: zoom, positionOf: b => b.d.geometry.coordinates, offsetOf: () => [0, 0],
+        ids: { circle: `ix-plot-box-${this.name}`, icon: `ix-plot-box-${this.name}`, polygons: `ix-plot-box-polygons-${this.name}`, titles: `ix-plot-titles-${this.name}` }
+      }) : { box: [], titles: [] };
+      return [...boxLayers.box, new IconLayer({
         id: `ix-plot-${this.name}-g${this._iconGeneration}`,
         data, pickable: true,
         getPosition: d => d.geometry.coordinates,
         getIcon: d => this._buildPlotIcon(d.properties.values, categories, labels, normalSizeValue, datasetMax, datasetMin),
         getSize: iconSize,
         sizeUnits: 'pixels'
-      })];
+      }), ...boxLayers.titles];
     }
 
     // Canvas rendering for one cell's mini-chart — BOX background, AREA
@@ -12967,9 +13623,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       canvas.width = W; canvas.height = H;
       const ctx = canvas.getContext('2d');
 
-      // BOX
+      // BOX (a plot without the BOX flag keeps its own canvas box; with it the
+      // shared box layer draws it — see _buildPlotLayers)
       const boxOpacity = styleNum(this.style.boxopacity);
-      if (!isNaN(boxOpacity) && boxOpacity > 0) {
+      if (!flatFlag(this.flags, 'BOX') && !isNaN(boxOpacity) && boxOpacity > 0) {
         ctx.fillStyle = `rgba(255,255,255,${boxOpacity})`;
         ctx.fillRect(0, 0, W, H);
       }
@@ -13215,13 +13872,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // async image decode, the whole drawing is synchronous
       const items = [];
       const defsSeen = new Set();
+      // this drawing's defs, swapped in for the previous drawing's below —
+      // appended to the shared pane <defs> on every draw they grew without
+      // bound (and getElementById then found a stale earlier copy)
+      const paneDefs = document.createElementNS(SVG_NS, 'g');
       let html = '';
       for (const d of combined) {
         const value = valueOf(d);
         // the item's class (range classes set it for groups too — a negative
         // group total would make dominant() pick the wrong class)
         const cat = d.properties.cat != null ? d.properties.cat : (d.properties.counts ? dominant(d.properties.counts) : 0);
-        const radiusPx = valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue);
+        const radiusPx = valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue, this._sizeBound());
         const size = radiusPx / pxPerUnit;
         const chart = this._userChartSvg(draw, name, theme, flag, d, value, cat, size, sizeValueOf(d));
         if (!chart) continue;
@@ -13231,11 +13892,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         for (const id of chart.ids) {
           if (defsSeen.has(id)) continue;
           defsSeen.add(id);
-          const def = this._userChartGroup.ownerDocument.getElementById(id);
-          if (def) chartHost.defs.appendChild(def.cloneNode(true));
+          // drawn now (fresh), else a cached chart's: the previous drawing's copy
+          const def = this._userChartGroup.querySelector('#' + CSS.escape(id)) || this._userChartGroup.ownerDocument.getElementById(id);
+          if (def) paneDefs.appendChild(def.cloneNode(true));
         }
         items.push({ d, coords: d.geometry.coordinates, ox: chart.ox, oy: chart.oy, s: pxPerUnit,
-          r: Math.max(chart.vw, chart.vh) * pxPerUnit / 2 });
+          r: Math.max(chart.vw, chart.vh) * pxPerUnit / 2,
+          // the chart's measured box (flat's getBox of the chart group) in px
+          // around the map position: the pane draws a chart point at
+          // p + s · (point − origin)
+          ext: [(chart.bb.x - chart.ox) * pxPerUnit, (chart.bb.y - chart.oy) * pxPerUnit,
+            (chart.bb.x + chart.bb.width - chart.ox) * pxPerUnit, (chart.bb.y + chart.bb.height - chart.oy) * pxPerUnit] });
       }
       if (glDebug()) console.info(`[ixmaps-gl debug] ${themeIdOf(this)}: zoom ${mapLibreToFlatZoom(liveZoom).toFixed(2)}, ${combined.length} charts, ${items.length} drawn${this._viewMoving ? ' (moving)' : ''}`);
       if (!items.length) {
@@ -13244,6 +13911,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         this._chartItems = null;
         return (this._userChartLastLayers = []);
       }
+      chartHost.defs.appendChild(paneDefs);
+      if (this._chartPaneDefs) this._chartPaneDefs.remove();
+      this._chartPaneDefs = paneDefs;
       if (this._chartPaneGroup) this._chartPaneGroup.remove();
       this._chartPaneGroup = document.createElementNS(SVG_NS, 'g');
       chartHost.pane.appendChild(this._chartPaneGroup);
@@ -13252,11 +13922,24 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       for (let i = 0; i < items.length; i++) items[i].el = els[i];
       this._chartItems = items;
       chartHost.runtimes.add(this);
+      this._chartHost = chartHost; // removeRuntimes takes it out again
       chartHost.update();
       // picking: a transparent circle per chart — the VISIBLE chart is the
       // live SVG in the pane; this deck layer only serves hover, click and
       // the tooltips (pickedFeature unwraps the {d, icon} entry shape)
-      this._userChartLastLayers = [new ScatterplotLayer({
+      // BOX / TITLE: flat's chart-group box around the chart as the page's
+      // function drew it (its measured box). The chart itself is a live SVG in
+      // the pane above the deck canvas, so the box lies under it and the title
+      // (outside the box) beside it
+      const extOf = new Map(items.map(it => [it.d, it.ext]));
+      const boxRows = this._boxRows(items.map(it => it.d), {
+        unit: objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(this.style.scale) || 1), liveZoom, extentOf: d => extOf.get(d) });
+      const boxLayers = boxRows ? this._boxTitleLayers(boxRows, {
+        unit: objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(this.style.scale) || 1), liveZoom,
+        positionOf: b => b.d.geometry.coordinates, offsetOf: () => [0, 0],
+        ids: { circle: `ix-user-box-${this.name}`, icon: `ix-user-box-${this.name}`, polygons: `ix-user-box-polygons-${this.name}`, titles: `ix-user-titles-${this.name}` }
+      }) : { box: [], titles: [] };
+      this._userChartLastLayers = [...boxLayers.box, new ScatterplotLayer({
         id: `ix-bubbles-${this.name}`,
         data: items.map(it => ({ d: it.d, icon: true, r: it.r })),
         pickable: true,
@@ -13265,7 +13948,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         radiusUnits: 'pixels', radiusMinPixels: 1,
         stroked: false, filled: true, getFillColor: [0, 0, 0, 0],
         parameters: ICON_LAYER_GLOBE_PARAMETERS
-      })];
+      }), ...boxLayers.titles];
       return this._userChartLastLayers;
     }
     // the chart's SVG, cached by its draw parameters — a failing draw
@@ -13320,7 +14003,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           const vx = bb.x - pad, vy = bb.y - pad, vw = bb.width + 2 * pad, vh = bb.height + 2 * pad;
           // the chart's origin (0,0 — or the point flat moves it to, ret) sits at the map position
           const ox = (ret && ret.x) || 0, oy = (ret && ret.y) || 0;
-          chart = { vx, vy, vw, vh, ox, oy, markup, ids: [...ids],
+          chart = { vx, vy, vw, vh, ox, oy, markup, ids: [...ids], bb: { x: bb.x, y: bb.y, width: bb.width, height: bb.height },
             svg: `<svg xmlns="${SVG_NS}" width="__W__" height="__H__" viewBox="${vx} ${vy} ${vw} ${vh}"><defs>${defs}</defs>${markup}</svg>` };
         }
       } catch (e) {
@@ -13333,6 +14016,187 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       return chart;
     }
 
+    // flat's BOX block belongs to the box: the box owns its TITLE — no BOX, no
+    // title — so everything about both is decided here and in _boxRows, for
+    // every chart type (single symbol, SEQUENCE, PIE, BAR): the gates (BOX /
+    // TITLE flags, boxupper / boxlower / titleupper scale), the margin, the
+    // title font (DTEXT follows the chart), BOTTOMTITLE, align, CIRCULARBOX.
+    // null when there is no box at this zoom.
+    _boxSpec(liveZoom) {
+      const st = this.style;
+      if (!(flatFlag(this.flags, 'BOX') && !boxHiddenByScale(st, liveZoom))) return null;
+      const titleUpper = scaleDenom(st.titleupper);
+      const titleScale = styleNum(st.textscale) || styleNum(st.valuescale) || 1;
+      return {
+        circular: flatFlag(this.flags, 'CIRCULAR'),
+        margin: styleNum(st.boxmargin) || 2,
+        bottomTitle: flatFlag(this.flags, 'BOTTOMTITLE'),
+        alignRight: /right/.test(String(st.align || '')),
+        titleShown: flatFlag(this.flags, 'TITLE') && !!this.binding.title
+          && !(titleUpper && scaleDenominatorAt(liveZoom) > titleUpper),
+        // DTEXT: the title font follows the chart, max(0.9u, min(W/5, 14u /
+        // scale)) (18815) — measured on the fire areas page's SIF chart
+        // (W 362 units → font 72.35)
+        titleFontOf: (unit, w) => (flatFlag(this.flags, 'DTEXT')
+          ? Math.max(0.9 * unit, Math.min(w / 5, 14 * unit / (styleNum(st.scale) || 1)))
+          : 5 * unit) * titleScale
+      };
+    }
+
+    // the layout row of every item's box and title (chartBoxLayout + the spec
+    // above); null without a box (items: the array, or a function building it
+    // only when there is a box). o: { unit (px per flat unit), liveZoom,
+    // extentOf (item -> its drawn [x0, y0, x1, y1], px around the anchor),
+    // radiusOf / centerOf (the circular box's base, default the extent's) }.
+    // A row: { d: item, geometry, properties, w (the chart's width — flat's
+    // size measure W, the stroke and corner basis), boxR / cx / cy (circle),
+    // rect (rectangle), title }
+    _boxRows(items, o) {
+      const spec = this._boxSpec(o.liveZoom);
+      if (!spec) return null;
+      // flat appends style.titleunits (its parse adds the leading space,
+      // maptheme.js 1470; szTitle += at 18827)
+      const units = this.style.titleunits ? ' ' + this.style.titleunits : '';
+      return (typeof items === 'function' ? items() : items).map(d => {
+        const itemTitle = spec.titleShown ? this._itemTitle(d.properties) : null;
+        const L = chartBoxLayout(o.extentOf(d), { unit: o.unit, margin: spec.margin, circular: spec.circular,
+          radius: o.radiusOf ? o.radiusOf(d) : undefined, center: o.centerOf ? o.centerOf(d) : undefined,
+          titleText: itemTitle ? itemTitle + units : null, titleFont: w => spec.titleFontOf(o.unit, w),
+          bottomTitle: spec.bottomTitle, alignRight: spec.alignRight });
+        // geometry/properties of the chart's feature on the row: the circular
+        // box is pickable, and the tooltip (buildTooltipHtml, the click-pin)
+        // works on the feature's own properties
+        return { d, geometry: d.geometry, properties: d.properties, w: L.w, boxR: L.boxR, cx: L.cx, cy: L.cy,
+          rect: L.rect, title: L.title };
+      });
+    }
+
+    // THE box-and-title layers of every chart type: rows are _boxRows results.
+    // o: { unit, liveZoom, positionOf (row -> [lng, lat]), offsetOf (row ->
+    // the chart's [dx, dy] px move: align / offsetx / offsety), box (false:
+    // the title layer only — a BAR draws its box as a shader shape), ids:
+    // { circle, icon, polygons, titles } } — the layer ids stay each chart
+    // type's own. Returns { box: [layers], titles: [layers] }: the caller
+    // pushes them where its draw order wants them.
+    _boxTitleLayers(rows, o) {
+      const st = this.style;
+      const { unit, liveZoom, positionOf, offsetOf, ids } = o;
+      const circular = flatFlag(this.flags, 'CIRCULAR');
+      const box = [], titles = [];
+      // 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(st.boxopacity)) ? 1 : styleNum(st.boxopacity);
+      if (o.box === false) {
+        // the title layer only
+      } else if (circular) {
+        const boxNone = isNoneColor(st.boxcolor), borderNone = isNoneColor(st.bordercolor);
+        const boxRgb = hexOrNamedToRgb(boxNone ? '#eeeeee' : st.boxcolor || '#eeeeee');
+        const boxAlpha = boxNone ? 0 : Math.round(255 * boxOpacity);
+        const borderRgb = borderNone ? null : hexOrNamedToRgb(st.bordercolor || '#dddddd');
+        // Always a ScatterplotLayer: its shader circle is smooth at any
+        // size, where an icon — a 48px canvas texture deck.gl scales up —
+        // pixelated with large boxes. ScatterplotLayer has no pixel offset,
+        // so the chart's align/offsetx/offsety move and flat's circular box
+        // position (the chart's bounding-box center, 18793) are baked into
+        // map coordinates (pixelOffsetLngLat). Pickable: flat's box is part
+        // of the chart group, so hovering it fires the chart's tooltip — the
+        // symbols sit above it, so they keep their own
+        box.push(new ScatterplotLayer({
+          id: ids.circle,
+          data: rows, pickable: true,
+          getPosition: b => { const f = offsetOf(b); return pixelOffsetLngLat(positionOf(b), [f[0] + b.cx, f[1] + b.cy], liveZoom); },
+          getRadius: b => b.boxR,
+          radiusUnits: 'pixels',
+          stroked: !borderNone,
+          getFillColor: [...boxRgb.slice(0, 3), boxAlpha],
+          getLineColor: [...(borderRgb || boxRgb).slice(0, 3), 255],
+          getLineWidth: unit / 20,
+          lineWidthUnits: 'pixels',
+          parameters: ICON_LAYER_GLOBE_PARAMETERS
+        }));
+      } else {
+        // flat's rectangular box (the chart and its title plus the margin)
+        const borderStyle = String(st.borderstyle || '');
+        const boxLook = {
+          fill: st.boxcolor || 'white',
+          fillOpacity: boxOpacity,
+          stroke: borderStyle === 'none' || isNoneColor(styleLineColor(st.bordercolor)) ? null : styleLineColor(st.bordercolor) || '#bbbbbb',
+          strokeOpacity: /^(solid|dotted|dashed)$/.test(borderStyle) ? 1 : 0.3,
+        };
+        const borderWidth = styleNum(st.borderwidth) || 1;
+        const borderRadius = styleNum(st.borderradius);
+        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 = rows.filter(b => !bigBox(b)), polygonBoxes = rows.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(unit, b.w / 30),
+            strokeOf(b), boxLook);
+        });
+        if (polygonBoxes.length) {
+          const fillRgb = hexOrNamedToRgb(boxLook.fill);
+          const strokeRgb = boxLook.stroke ? hexOrNamedToRgb(boxLook.stroke) : null;
+          box.push(new GeoJsonLayer({
+            id: ids.polygons,
+            data: polygonBoxes.map(b => {
+              const f = offsetOf(b), c = positionOf(b), r = b.rect;
+              const at = (x, y) => pixelOffsetLngLat(c, [x + f[0], y + f[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) box.push(new IconLayer({
+          // the generation suffix (like every icon-atlas layer id, see
+          // ICON_ATLAS_RESET_AFTER): every zoom creates a new set of box
+          // rasters, and deck.gl's atlas never evicts
+          id: `${ids.icon}-g${this._iconGeneration}`,
+          data: iconBoxes, pickable: false,
+          getPosition: positionOf,
+          getIcon: b => b.icon,
+          // the icon is drawn at 2× with a stroke padding around the box
+          getSize: b => b.icon.height / 2,
+          getPixelOffset: b => { const f = offsetOf(b); return [(b.rect[0] + b.rect[2]) / 2 + f[0], (b.rect[1] + b.rect[3]) / 2 + f[1]]; },
+          sizeUnits: 'pixels',
+          billboard: true,
+          parameters: ICON_LAYER_GLOBE_PARAMETERS
+        }));
+      }
+      const titleData = rows.filter(b => b.title);
+      if (titleData.length) titles.push(new TextLayer({
+        id: ids.titles,
+        data: titleData, pickable: false,
+        getPosition: positionOf,
+        getText: b => b.title.text,
+        getSize: b => b.title.f,
+        sizeUnits: 'pixels',
+        fontFamily: 'arial',
+        characterSet: 'auto',
+        lineHeight: 1,
+        getColor: [...hexOrNamedToRgb(st.textcolor || '#888888').slice(0, 3), 255],
+        fontSettings: { sdf: true },
+        outlineWidth: 1 / 7,
+        outlineColor: [255, 255, 255, 128],
+        getTextAnchor: b => b.title.anchor,
+        // top of the text ≈ first baseline − 0.8 font
+        getAlignmentBaseline: 'top',
+        getPixelOffset: b => { const f = offsetOf(b); return [b.title.x + f[0], b.title.top + f[1]]; },
+        parameters: ICON_LAYER_GLOBE_PARAMETERS
+      }));
+      return { box, titles };
+    }
+
     // BOX (see the BOX block in _buildChartLayers): a rectangle icon
     // w×h px, rounded corners rx, stroke sw px; drawn at twice the size
     _buildBoxIcon(w, h, rx, sw, look) {
@@ -13503,7 +14367,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const groups = doRelocate ? this._groupCoLocated(clusterFeatures, effectiveZoom) : clusterFeatures.map(f => {
         return {
           geometry: f.geometry,
-          properties: { counts: this._oneHot(f.properties.cat, f.properties.point_count), total: f.properties.value,
+          // counts is the summed bound VALUE and recordCounts the record
+          // count, as groupCoLocated builds them (RELOCATE) — RELOCATE
+          // moves the item, it never changes a value
+          properties: { counts: this._oneHot(f.properties.cat, f.properties.value),
+            recordCounts: this._oneHot(f.properties.cat, f.properties.point_count), total: f.properties.value,
             ...(f.properties.classValue !== undefined ? { classTotal: f.properties.classValue } : {}),
             ...(f.properties.titleRaw ? { titleRaw: f.properties.titleRaw } : {}) }
         };
@@ -13654,7 +14522,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // GRIDSIZE: every chart the size of its grid cell, whatever its value
       // (_gridChartRadiusPx); otherwise valueRadius
       const gridR = this._gridChartRadiusPx(zoom, liveZoom);
-      const vRadius = v => (gridR != null ? gridR : valueRadius(v, liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue));
+      const vRadius = v => (gridR != null ? gridR : valueRadius(v, liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue, this._sizeBound()));
       // AGGREGATE sums without a normalsizevalue: flat's default is the
       // largest aggregated value (defaultNormalSizeValue leaves it unset, the
       // sizes depend on the aggregation)
@@ -13922,15 +14790,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // DTEXT: the title font follows the chart, max(0.9u, min(W/5,
       // 14u / scale)) (18815) — measured on the fire areas page's SIF chart
       // (W 362 units → font 72.35).
-      const boxShown = flatFlag(this.flags, 'BOX') && !boxHiddenByScale(this.style, liveZoom);
-      const circular = flatFlag(this.flags, 'CIRCULAR');
       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 titleScale = styleNum(this.style.textscale) || styleNum(this.style.valuescale) || 1;
-      const titleFontOf = W => (flatFlag(this.flags, 'DTEXT')
-        ? Math.max(0.9 * unitPx, Math.min(W / 5, 14 * unitPx / (styleNum(this.style.scale) || 1)))
-        : 5 * unitPx) * titleScale;
       // the chart's value text and label (see VALUES and LABEL below), shared
       // with the box: flat's box encloses whatever the chart group draws
       const valuesShown = this.flags.has('VALUES') && !valuesHiddenByScale(this.style, zoom);
@@ -13938,141 +14798,28 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const labelShown = !!this.style.labelfield && !flatFlag(this.flags, 'NORMSIZE') && !flatFlag(this.flags, 'ZOOM')
         && !labelHiddenByScale(this.style, zoom);
       const labelOf = labelShown ? this._chartLabelFn(unitPx) : null;
-      // 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 || ''));
-      // 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 = vRadius(sizeValueOf(d));
-        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 grow = e => { if (!e) return; chart[0] = Math.min(chart[0], e[0]); chart[1] = Math.min(chart[1], e[1]); chart[2] = Math.max(chart[2], e[2]); chart[3] = Math.max(chart[3], e[3]); };
-        if (valueTextOf && !d.properties.counts) { const v = valueTextOf(d, r); if (v) grow(v.extent); }
-        if (labelOf) { const l = labelOf(d, r); if (l) grow(l.extent); }
-        const w = chart[2] - chart[0];
-        const margin = Math.min(2 * boxMarginU * unitPx, boxMarginU * w / 30);
-        const boxR = circular ? r * 1.1 + margin : r;
-        const titleFontPx = titleFontOf(w);
-        let title = null;
-        if (titleShown) {
-          // flat appends style.titleunits (its parse adds the leading
-          // space, maptheme.js 1470; szTitle += at 18827)
-          const units = this.style.titleunits ? ' ' + this.style.titleunits : '';
-          const text = this._itemTitle(d.properties) ? this._itemTitle(d.properties) + units : null;
-          if (text) {
-            const f = titleFontPx;
-            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 = 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
-            title = { text: lines.join('\n'), x, anchor, top: base - 0.8 * f, f,
-              extent: [x0, base - 0.905 * f, x0 + width, base + (lines.length - 1) * f + 0.212 * f] };
-          }
-        }
-        let rect = null;
-        if (!circular) {
-          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];
+      // with MULTIQUAD only the first item of a position gets its box/title;
+      // the circle sits on the anchor (0, 0), its base radius the symbol's
+      const boxLayout = this._boxRows(() => combined.filter(d => !multi || multi.index.get(d) === 0), {
+        unit: unitPx, liveZoom,
+        radiusOf: d => vRadius(sizeValueOf(d)), centerOf: () => [0, 0],
+        extentOf: d => {
+          const r = vRadius(sizeValueOf(d));
+          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 grow = e => { if (!e) return; chart[0] = Math.min(chart[0], e[0]); chart[1] = Math.min(chart[1], e[1]); chart[2] = Math.max(chart[2], e[2]); chart[3] = Math.max(chart[3], e[3]); };
+          if (valueTextOf && !d.properties.counts) { const v = valueTextOf(d, r); if (v) grow(v.extent); }
+          if (labelOf) { const l = labelOf(d, r); if (l) grow(l.extent); }
+          return chart;
         }
-        return { d, r, w, boxR, rect, title };
+      });
+      // (the title layers are pushed after the symbols, below)
+      const boxLayers = boxLayout ? this._boxTitleLayers(boxLayout, {
+        unit: unitPx, liveZoom,
+        positionOf: b => b.d.geometry.coordinates, offsetOf: b => alignOf(b.d),
+        ids: { circle: `ix-box-${this.name}`, icon: `ix-box-${this.name}`, polygons: `ix-box-polygons-${this.name}`, titles: `ix-titles-${this.name}` }
       }) : null;
-      if (boxShown && circular) {
-        const boxNone = isNoneColor(this.style.boxcolor), borderNone = isNoneColor(this.style.bordercolor);
-        const boxRgb = hexOrNamedToRgb(boxNone ? '#eeeeee' : this.style.boxcolor || '#eeeeee');
-        const boxAlpha = boxNone ? 0 : Math.round(255 * boxOpacity);
-        const borderRgb = borderNone ? null : hexOrNamedToRgb(this.style.bordercolor || '#dddddd');
-        // ScatterplotLayer has no pixel offset: a moved chart (align,
-        // offsetx/offsety) gets its circle as an icon
-        if (alignOf.active) layers.push(new IconLayer({
-          id: `ix-box-${this.name}-g${this._iconGeneration}`,
-          data: boxLayout, pickable: false,
-          getPosition: b => b.d.geometry.coordinates,
-          getIcon: b => this._buildSingleIcon(boxRgb, boxAlpha / 255, 'circle', borderRgb,
-            borderNone ? 0 : Math.round(unitPx / 20 * BUBBLE_ICON_SIZE / Math.max(1, 2 * b.boxR) * 4) / 4),
-          getSize: b => b.boxR * 2,
-          getPixelOffset: b => alignOf(b.d),
-          sizeUnits: 'pixels',
-          billboard: true,
-          parameters: ICON_LAYER_GLOBE_PARAMETERS
-        }));
-        else layers.push(new ScatterplotLayer({
-          id: `ix-box-${this.name}`,
-          data: boxLayout, pickable: false,
-          getPosition: b => b.d.geometry.coordinates,
-          getRadius: b => b.boxR,
-          radiusUnits: 'pixels',
-          stroked: !borderNone,
-          getFillColor: [...boxRgb.slice(0, 3), boxAlpha],
-          getLineColor: [...(borderRgb || boxRgb).slice(0, 3), 255],
-          getLineWidth: unitPx / 20,
-          lineWidthUnits: 'pixels',
-          parameters: ICON_LAYER_GLOBE_PARAMETERS
-        }));
-      } else if (boxShown) {
-        const borderStyle = String(this.style.borderstyle || '');
-        const boxLook = {
-          fill: this.style.boxcolor || 'white',
-          fillOpacity: boxOpacity,
-          stroke: borderStyle === 'none' || isNoneColor(styleLineColor(this.style.bordercolor)) ? 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);
-        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.w / 30),
-            strokeOf(b), boxLook);
-        });
-        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: 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
-          getSize: b => b.icon.height / 2,
-          getPixelOffset: b => { const o = alignOf(b.d); return [(b.rect[0] + b.rect[2]) / 2 + o[0], (b.rect[1] + b.rect[3]) / 2 + o[1]]; },
-          sizeUnits: 'pixels',
-          billboard: true,
-          parameters: ICON_LAYER_GLOBE_PARAMETERS
-        }));
-      }
+      if (boxLayers) layers.push(...boxLayers.box);
 
       // flat's per-part SYMBOL branch (everything but CATEGORICAL without
       // AGGREGATE/GROUP) draws a square or roundrect of side 2r, the other
@@ -14095,7 +14842,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         if (!flatLook) return this._buildSingleIcon(rgb, fillOpacity, shapeOf(d.properties), singleBorderColorRgb, singleBorderWidthPx);
         const look = flatLook(d);
         return this._buildSingleIcon(rgb, look.fillOpacity, shapeOf(d.properties),
-          look.noStroke || !rgb ? null : (look.stroke || flatDerivateRgb(rgb, 0.7)), look.width, look.strokeOpacity);
+          bubbleStrokeRgb(look, rgb), look.width, look.strokeOpacity);
       };
       // flat's symbol outline (maptheme.js 21595-21610 and 21950-21997,
       // drawn 21625-21634 / 21995-22035): every SYMBOL shape is stroked,
@@ -14130,7 +14877,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // routing goes by the final id (layerRuntimeById). A symbol's outline
       // is centered on its radius (flat); BUBBLE's border keeps the
       // icon's look, inside the radius
-      if (combined.length && !alignOf.active && combined.every(d => singleSymbol(d) && shapeOf(d.properties) === 'circle')) {
+      if (combined.length && !alignOf.active && combined.every(d => singleSymbol(d) && shapeOf(d.properties) === 'circle' && !this._resolveSymbolUrl(d.properties))) {
         const radiusPx = d => vRadius(sizeValueOf(d));
         // a CATEGORICAL BUBBLE: flat's look (flatBubbleLook) in screen px,
         // its stroke centered on the radius as flat's SVG circle
@@ -14159,6 +14906,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         getPosition: d => d.geometry.coordinates,
         getIcon: d => {
           if (!singleSymbol(d)) return this._buildBubbleIcon(d.properties.counts, this.categoryColorsRgb, this._groupIsolation(d), Array.isArray(this.style.symbols) ? this.style.symbols : null, flatLook && flatLook(d));
+          const symbolUrl = this._resolveSymbolUrl(d.properties);
+          if (symbolUrl) return this._urlSymbolIcon(symbolUrl);
           if (flatLook) return singleIcon(d);
           const shape = shapeOf(d.properties), rgb = outlineRgb(d);
           if (!symbolOutline || !rgb) return this._buildSingleIcon((this.categoryColorsRgb || [])[d.properties.cat], fillOpacity, shape, rgb, rgb ? singleBorderWidthPx : 0);
@@ -14180,29 +14929,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         parameters: ICON_LAYER_GLOBE_PARAMETERS
       }));
 
-      const titleData = boxLayout ? boxLayout.filter(b => b.title) : [];
-      if (titleData.length) {
-        layers.push(new TextLayer({
-          id: `ix-titles-${this.name}`,
-          data: titleData, pickable: false,
-          getPosition: b => b.d.geometry.coordinates,
-          getText: b => b.title.text,
-          getSize: b => b.title.f,
-          sizeUnits: 'pixels',
-          fontFamily: 'arial',
-          characterSet: 'auto',
-          lineHeight: 1,
-          getColor: [...hexOrNamedToRgb(this.style.textcolor || '#888888').slice(0, 3), 255],
-          fontSettings: { sdf: true },
-          outlineWidth: 1 / 7,
-          outlineColor: [255, 255, 255, 128],
-          getTextAnchor: b => b.title.anchor,
-          // top of the text ≈ first baseline − 0.8 font
-          getAlignmentBaseline: 'top',
-          getPixelOffset: b => { const o = alignOf(b.d); return [b.title.x + o[0], b.title.top + o[1]]; },
-          parameters: ICON_LAYER_GLOBE_PARAMETERS
-        }));
-      }
+      if (boxLayers) layers.push(...boxLayers.titles);
 
       // VALUES: bold value label centered on each bubble (see
       // flatValueText/valuesFontSizePx above). Labels are their own
@@ -14470,63 +15197,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // it itself (its ImageBitmap loader falls back to <img>, which
       // rasterizes SVG) — NOT tinted: these files carry their own colors,
       // and flat doesn't recolor an <image> either
-      const urlSymbolOf = i => {
-        const s = symbols && (symbols[i] || symbols[0]);
-        return typeof s === 'string' && /\.(svg|png|jpe?g)([?#]|$)/i.test(s.trim()) ? s.trim() : null;
-      };
-      if (!this._urlIconCache) this._urlIconCache = new Map();
-      const urlIcon = u => {
-        if (!this._urlIconCache.has(u)) {
-          // the placeholder is a transparent 1x1 PNG, NOT the raw symbol
-          // URL: deck.gl would immediately try to load that itself, and an
-          // SVG without natural dimensions (a viewBox only, the bus
-          // pictogram of the City-moving page) makes Chrome's
-          // createImageBitmap throw — a console error and a part that
-          // never renders. The real raster replaces it below
-          const entry = { url: TRANSPARENT_1PX_PNG, width: 256, height: 256, anchorX: 128, anchorY: 128, mask: false, id: 'seq-sym-pending:' + u };
-          this._urlIconCache.set(u, entry);
-          // fetch the symbol ONCE and rasterize it into the descriptor's
-          // own 256px cell here: deck then always sees exactly the declared
-          // dimensions, and dimension-less SVGs work like any other. The
-          // redraw lets the next getIcon see the patched descriptor
-          fetch(u).then(r => r.ok ? r.text() : null).then(text => new Promise((resolve, reject) => {
-            if (typeof text !== 'string' || !/<svg[\s>]/i.test(text)) { reject(new Error('not svg')); return; }
-            if (!/\swidth\s*=/i.test(text) || !/\sheight\s*=/i.test(text)) {
-              const vb = text.match(/viewBox\s*=\s*["']([^"']*)["']/i);
-              const p = vb && vb[1].trim().split(/[\s,]+/).map(Number);
-              if (p && p.length === 4 && isFinite(p[2]) && p[2] > 0 && isFinite(p[3]) && p[3] > 0) {
-                text = text.replace(/<svg/i, '<svg width="' + p[2] + '" height="' + p[3] + '"');
-              }
-            }
-            const img = new Image();
-            img.onload = () => resolve(img);
-            img.onerror = () => reject(new Error('svg decode failed'));
-            img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(text);
-          })).then(img => {
-            const size = entry.width;
-            const canvas = document.createElement('canvas');
-            canvas.width = size; canvas.height = size;
-            const ctx = canvas.getContext('2d');
-            const s = Math.min(size / (img.naturalWidth || size), size / (img.naturalHeight || size));
-            const dw = (img.naturalWidth || size) * s, dh = (img.naturalHeight || size) * s;
-            ctx.drawImage(img, (size - dw) / 2, (size - dh) / 2, dw, dh);
-            entry.url = canvas.toDataURL('image/png');
-            entry.id = 'seq-sym-raster:' + u;
-            if (this._triggerRedraw) this._triggerRedraw();
-          }).catch(() => {
-            // not an SVG (a PNG/JPEG symbol): deck's own URL loading takes
-            // it from here — and a pre-sized SVG that failed to rasterize
-            // gets that same second chance
-            entry.url = u;
-            entry.id = 'seq-sym-natural:' + u;
-            if (this._triggerRedraw) this._triggerRedraw();
-          });
-        }
-        return this._urlIconCache.get(u);
-      };
+      const urlSymbolOf = i => this._urlSymbolOf(symbols && (symbols[i] || symbols[0]));
+      const urlIcon = u => this._urlSymbolIcon(u);
       const shapeOf = i => { const sh = symbols && (symbols[i] || symbols[0]); return normalizeSymbolShape(sh); };
       const colorOf = i => this.classRgb(i);
-      const parts = [], glows = [];
+      const allParts = [], allGlows = [];
       for (const d of charts) {
         // parts: the record's own field values (a per-item chart, or the
         // single-record cell of an aggregated one); series: a multi-record
@@ -14538,16 +15213,34 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           const sum = counts.reduce((a, v) => a + (v || 0), 0);
           counts = counts.map(v => sum > 0 ? v / (sum / 100) : 0);
         }
+        // flat's aggregated CATEGORICAL item holds a value per category only up
+        // to the highest category it has (measured on flat: the chart's star and
+        // glow follow the categories present as 0..k, 985 of 988 charts of the
+        // concessioni page): trailing zeros are no parts, so with SORT|UP the
+        // smallest part — order index 0, the one that sets the star radius and
+        // carries the glow — is a zero only when a category BELOW the highest
+        // one is missing
+        if (!d.properties.parts && !d.properties.series) {
+          let n = counts.length;
+          while (n > 0 && !counts[n - 1]) n--;
+          if (n < counts.length) counts = counts.slice(0, n);
+        }
         const sizeFactor = itemSizeFactor(d);
         const partRadius = multi
           ? v => Math.max(VALUE_RADIUS_MIN, normalR * Math.pow(Math.abs(v) / seqMax, 1 / sizePow) * sizeFactor)
-          : v => valueRadius(v, liveZoom, st, this.mapOptions, this.flags, seqMax);
+          : v => valueRadius(v, liveZoom, st, this.mapOptions, this.flags, seqMax, this._sizeBound());
         let layout = rings ? ringsLayout(counts, partRadius)
           : sequenceLayout(counts, this.flags, partRadius, { maxRadius: normalR, maxValue: seqMax, nParts: nCats, rangeScale: styleNum(st.rangescale) || 0 });
         if (!layout.length) continue;
         // GLOW belongs to the first part (sorted) or to every part, and
         // hides with it when its class is not marked
-        const glowParts = new Set(sorted ? [layout[0].i] : layout.map(p => p.i));
+        // every chart glows (deliberately NOT flat's rule, which gives the glow to
+        // the part at sorted order index 0 — a zero, skipped, whenever a category
+        // below the highest is missing — so only about a quarter of flat's charts
+        // glow): a sorted chart's glow belongs to its biggest part, an unsorted
+        // one glows with every part as in flat
+        const biggest = layout.reduce((m, p) => (p.v > m.v ? p : m), layout[0]);
+        const glowParts = new Set(sorted ? [biggest.i] : layout.map(p => p.i));
         // the chart's drawn extent (flat: map.Dom.getBox of its shape
         // group) — the parts' star cluster — for BOX / CIRCULARBOX sizing
         let ex0 = Infinity, ey0 = Infinity, ex1 = -Infinity, ey1 = -Infinity;
@@ -14564,12 +15257,12 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         d._seqLast = layout[layout.length - 1].r;
         const items = layout.map(p => {
           const item = { geometry: d.geometry, properties: d.properties, chart: d, part: p };
-          if (glowParts.has(p.i)) glows.push(item);
+          if (glowParts.has(p.i)) allGlows.push(item);
           return item;
         });
         // STAR: the first part (its center) is put on top at the end (23145)
         if (star && items.length > 1) items.push(items.shift());
-        parts.push(...items);
+        allParts.push(...items);
       }
       const alignOf = this._chartAlignFn(liveZoom, d => (d.chart || d)._seqLast || 0);
       const offsetOf = item => { const o = alignOf(item.chart); return [o[0] + item.part.x, o[1] + item.part.y]; };
@@ -14587,287 +15280,227 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       //    max(0.9u, min(w/5, 14u/scale)) · textscale, wrapped to the
       //    circle's width — gated by titleupper (shown while the map
       //    scale is that bound or coarser, 18810) and boxupper/boxlower
-      const boxShown = flatFlag(this.flags, 'BOX') && !boxHiddenByScale(st, liveZoom);
+      // (flat centers the circular box and its title on the chart's
+      // bounding-box CENTER — maptheme.js 18793-18798 — not on its anchor: a
+      // star cluster's satellites spread asymmetrically around it; the
+      // circle's title baselines are measured on the resized box, 18798-18830)
       const circular = flatFlag(this.flags, 'CIRCULAR');
-      const bottomTitle = flatFlag(this.flags, 'BOTTOMTITLE');
-      const titleUpper = scaleDenom(st.titleupper);
-      const titleShown = boxShown && flatFlag(this.flags, 'TITLE') && !!this.binding.title
-        && !(titleUpper && scaleDenominatorAt(liveZoom) > titleUpper);
-      let boxLayout = null;
-      if (boxShown) {
-        const boxMarginU = styleNum(st.boxmargin) || 2;
-        const boxOpacity = isNaN(styleNum(st.boxopacity)) ? 1 : styleNum(st.boxopacity);
-        const titleScale = styleNum(st.textscale) || styleNum(st.valuescale) || 1;
-        const titleFontOf = w => (flatFlag(this.flags, 'DTEXT')
-          ? Math.max(0.9 * unit, Math.min(w / 5, 14 * unit / (styleNum(st.scale) || 1)))
-          : 5 * unit) * titleScale;
-        const alignRight = /right/.test(String(st.align || ''));
-        boxLayout = charts.filter(d => d._seqExtent).map(d => {
-          const [ex0, ey0, ex1, ey1] = d._seqExtent;
-          const w = ex1 - ex0, h = ey1 - ey0;
-          // flat centers the circular box (and its title) on the chart's
-          // bounding-box CENTER (maptheme.js 18793-18798: center =
-          // bBox.x + bBox.width/2, bBox.y + bBox.height/2), not on the
-          // chart's anchor — a star cluster's satellites spread
-          // asymmetrically around it
-          const cx = (ex0 + ex1) / 2, cy = (ey0 + ey1) / 2;
-          const margin = Math.min(2 * boxMarginU * unit, boxMarginU * w / 30);
-          const boxR = circular ? Math.max(w, h) / 2 * 1.1 + margin : 0;
-          let title = null;
-          if (titleShown) {
-            // flat appends style.titleunits to the box title (its parse
-            // gives it the leading space, maptheme.js 1470; szTitle += at
-            // 18827): "27.5" + "km/h" -> "27.5 km/h"
-            const units = st.titleunits ? ' ' + st.titleunits : '';
-            const text = this._itemTitle(d.properties) ? this._itemTitle(d.properties) + units : null;
-            if (text) {
-              const f = titleFontOf(w);
-              const lines = wrapTitleLines(text, f, circular ? boxR * 2 : w).split('\n');
-              const width = Math.max(...lines.map(l => titleTextWidth(l, f)));
-              // flat's title baselines are measured on the resized box
-              // (the circle spans center ± radius, 18798-18830)
-              const base = circular
-                ? (bottomTitle ? cy + boxR + f : cy - boxR - 0.7 * f - (lines.length - 1) * f)
-                : (bottomTitle ? ey1 + f : ey0 - 0.7 * f - (lines.length - 1) * f);
-              const x = circular ? cx + unit / 2 : (alignRight ? ex1 : ex0);
-              const anchor = circular ? 'middle' : (alignRight ? 'end' : 'start');
-              const x0 = anchor === 'middle' ? x - width / 2 : anchor === 'end' ? x - width : x;
-              title = { text: lines.join('\n'), x, anchor, top: base - 0.8 * f, f,
-                extent: [x0, base - 0.905 * f, x0 + width, base + (lines.length - 1) * f + 0.212 * f] };
-            }
-          }
-          let rect = null;
-          if (!circular) {
-            const e = [ex0, ey0, ex1, ey1];
-            if (title) { e[0] = Math.min(e[0], title.extent[0]); e[1] = Math.min(e[1], title.extent[1]) + 0.1 * title.f; 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, w, boxR, rect, title, boxOpacity, cx, cy };
-        });
-        if (circular) {
-          const boxNone = isNoneColor(st.boxcolor), borderNone = isNoneColor(st.bordercolor);
-          const boxRgb = hexOrNamedToRgb(boxNone ? '#eeeeee' : st.boxcolor || '#eeeeee');
-          const borderRgb = borderNone ? null : hexOrNamedToRgb(st.bordercolor || '#dddddd');
-          // ScatterplotLayer has no pixel offset: a moved chart (align,
-          // offsetx/offsety) gets its circle as an icon — at the chart's
-          // bounding-box center, flat's circular box position (18793)
-          if (alignOf.active) layers.push(new IconLayer({
-            id: `ix-seqbox-${this.name}-g${this._iconGeneration}`,
-            data: boxLayout, pickable: false,
-            getPosition: b => b.d.geometry.coordinates,
-            getIcon: b => this._buildSingleIcon(boxRgb, b.boxOpacity, 'circle', borderRgb,
-              borderNone ? 0 : Math.round(unit / 20 * BUBBLE_ICON_SIZE / Math.max(1, 2 * b.boxR) * 4) / 4),
-            getSize: b => b.boxR * 2,
-            getPixelOffset: b => { const o = alignOf(b.d); return [o[0] + b.cx, o[1] + b.cy]; },
-            sizeUnits: 'pixels', billboard: true,
-            parameters: ICON_LAYER_GLOBE_PARAMETERS
-          }));
-          else layers.push(new ScatterplotLayer({
-            id: `ix-seqbox-${this.name}`,
-            data: boxLayout, pickable: false,
-            getPosition: b => {
-              // the circle at the chart's bbox center: with no align
-              // offset it moves in map coordinates
-              const o = pixelOffsetLngLat(b.d.geometry.coordinates, [b.cx, b.cy], liveZoom);
-              return o;
-            },
-            getRadius: b => b.boxR,
-            radiusUnits: 'pixels',
-            stroked: !borderNone,
-            getFillColor: b => [...boxRgb.slice(0, 3), Math.round(255 * b.boxOpacity)],
-            getLineColor: [...(borderRgb || boxRgb).slice(0, 3), 255],
-            getLineWidth: unit / 20,
-            lineWidthUnits: 'pixels',
-            parameters: ICON_LAYER_GLOBE_PARAMETERS
-          }));
-        } else {
-          // flat's rectangular box (the chart and its title plus the
-          // margin), the single-symbol path's own _buildBoxIcon drawing
-          const borderStyle = String(st.borderstyle || '');
-          const boxLook = {
-            fill: st.boxcolor || 'white',
-            fillOpacity: isNaN(styleNum(st.boxopacity)) ? 1 : styleNum(st.boxopacity),
-            stroke: borderStyle === 'none' || isNoneColor(styleLineColor(st.bordercolor)) ? null : styleLineColor(st.bordercolor) || '#bbbbbb',
-            strokeOpacity: /^(solid|dotted|dashed)$/.test(borderStyle) ? 1 : 0.3
-          };
-          const borderWidth = styleNum(st.borderwidth) || 1;
-          const borderRadius = styleNum(st.borderradius);
-          const strokeOf = b => borderWidth * 0.2 * b.w / 30;
-          boxLayout.forEach(b => {
-            b.icon = this._buildBoxIcon(b.rect[2] - b.rect[0], b.rect[3] - b.rect[1],
-              isNaN(borderRadius) ? 0 : borderRadius * Math.min(unit, b.w / 30),
-              strokeOf(b), boxLook);
+      const boxLayoutAll = this._boxRows(() => charts.filter(d => d._seqExtent), { unit, liveZoom, extentOf: d => d._seqExtent });
+      // per-chart overlap bands (see the band computation in the
+      // box block): a Map chart → band index, filled only when
+      // boxes are drawn; empty (single band) otherwise
+      const bandOfChart = new Map();
+      let nBands = 1;
+      if (boxLayoutAll) {
+        // flat draws every chart as ONE group — its box, its symbols,
+        // its title, its values together — and the groups are sorted by
+        // size, so a bigger chart covers a smaller one ENTIRELY
+        // (chartMap's ascending sort, the biggest drawn last). deck.gl
+        // stacks whole layers, so with every box in one layer below
+        // every symbol, a bigger chart's box covered a smaller chart's
+        // box while that chart's symbols floated on top of it (the
+        // City-moving page's overlapping circles). Charts are grouped
+        // into overlap "bands" instead — an interval coloring assigned
+        // biggest-chart-first: within a band no two charts overlap
+        // (their box + title extents, in map pixel space, disjoint),
+        // and a chart is always in a band above every smaller chart it
+        // overlaps. Each band then draws its charts' complete group
+        // (box, title, glow, symbols, values), the smallest band first
+        // — deck.gl draws the first layer at the bottom — so between
+        // two overlapping charts the bigger one is wholly on top, as
+        // flat draws it. Overlap-free themes keep one band and today's
+        // exact single layers
+        const world = 512 * Math.pow(2, liveZoom);
+        const anchorPx = d => {
+          const o = alignOf(d), c = d.geometry.coordinates;
+          const lat = c[1] * Math.PI / 180;
+          return [(c[0] + 180) / 360 * world + o[0],
+            (0.5 - Math.log(Math.tan(Math.PI / 4 + lat / 2)) / (2 * Math.PI)) * world + o[1]];
+        };
+        const sizeOfBand = b => circular ? b.boxR
+          : b.rect ? Math.max(b.rect[2] - b.rect[0], b.rect[3] - b.rect[1]) / 2 : 0;
+        const bandRects = [];
+        for (const b of boxLayoutAll.slice().sort((a, c) => sizeOfBand(c) - sizeOfBand(a))) {
+          // the chart's whole drawn extent: parts cluster, box and
+          // title, as px around the (align-moved) anchor
+          const e = b.d._seqExtent || [0, 0, 0, 0];
+          let x0 = e[0], y0 = e[1], x1 = e[2], y1 = e[3];
+          if (circular) { x0 = Math.min(x0, b.cx - b.boxR); y0 = Math.min(y0, b.cy - b.boxR); x1 = Math.max(x1, b.cx + b.boxR); y1 = Math.max(y1, b.cy + b.boxR); }
+          else if (b.rect) { x0 = Math.min(x0, b.rect[0]); y0 = Math.min(y0, b.rect[1]); x1 = Math.max(x1, b.rect[2]); y1 = Math.max(y1, b.rect[3]); }
+          if (b.title) { x0 = Math.min(x0, b.title.extent[0]); y0 = Math.min(y0, b.title.extent[1]); x1 = Math.max(x1, b.title.extent[2]); y1 = Math.max(y1, b.title.extent[3]); }
+          const p = anchorPx(b.d);
+          const r = [p[0] + x0, p[1] + y0, p[0] + x1, p[1] + y1];
+          let k = 0;
+          while (bandRects[k] && bandRects[k].some(q => r[0] < q[2] && q[0] < r[2] && r[1] < q[3] && q[1] < r[3])) k++;
+          (bandRects[k] = bandRects[k] || []).push(r);
+          bandOfChart.set(b.d, k);
+        }
+        nBands = bandRects.length;
+      }
+      // one band's whole chart group — box, title, glow, symbols and
+      // values of ITS charts only (the closure's boxLayout, glows and
+      // parts are the band's slices) — pushed as one deck.gl layer
+      // sequence, in today's order. bs: the band's id suffix
+      const drawBand = (boxLayout, glows, parts, bs) => {
+        if (boxLayout) {
+          const L = this._boxTitleLayers(boxLayout, {
+            unit, liveZoom,
+            positionOf: b => b.d.geometry.coordinates, offsetOf: b => alignOf(b.d),
+            ids: { circle: `ix-seqbox-${this.name}${bs}`, icon: `ix-seqbox-${this.name}${bs}`,
+              polygons: `ix-seqbox-polygons-${this.name}${bs}`, titles: `ix-seqtitles-${this.name}${bs}` }
           });
-          if (boxLayout.length) layers.push(new IconLayer({
-            id: `ix-seqbox-${this.name}-g${this._iconGeneration}`,
-            data: boxLayout, pickable: false,
-            getPosition: b => b.d.geometry.coordinates,
-            getIcon: b => b.icon,
-            getSize: b => b.icon.height / 2,
-            getPixelOffset: b => { const o = alignOf(b.d); return [(b.rect[0] + b.rect[2]) / 2 + o[0], (b.rect[1] + b.rect[3]) / 2 + o[1]]; },
+          layers.push(...L.box, ...L.titles);
+        }
+        if (glows.length && this.flags.has('GLOW') && !glowHiddenByScale(st, liveZoom)) {
+          layers.push(new IconLayer({
+            id: `ix-glow-${this.name}${bs}-g${this._iconGeneration}`,
+            data: glows, pickable: false,
+            getPosition: d => d.geometry.coordinates,
+            getIcon: d => this._getGlowIcon(colorOf(d.part.i)),
+            getSize: d => d.part.r * 11,
+            getPixelOffset: offsetOf,
+            getColor: d => [255, 255, 255, alphaOf(d)],
             sizeUnits: 'pixels', billboard: true,
             parameters: ICON_LAYER_GLOBE_PARAMETERS
           }));
-        }
-        if (titleShown) {
-          const titleData = boxLayout.filter(b => b.title);
-          if (titleData.length) layers.push(new TextLayer({
-            id: `ix-seqtitles-${this.name}`,
-            data: titleData, pickable: false,
-            getPosition: b => b.d.geometry.coordinates,
-            getText: b => b.title.text,
-            getSize: b => b.title.f,
-            sizeUnits: 'pixels', fontFamily: 'arial',
-            characterSet: 'auto',
-            lineHeight: 1,
-            getColor: [...hexOrNamedToRgb(st.textcolor || '#888888').slice(0, 3), 255],
-            fontSettings: { sdf: true },
-            outlineWidth: 1 / 7,
-            outlineColor: [255, 255, 255, 128],
-            getTextAnchor: b => b.title.anchor,
-            getAlignmentBaseline: 'top',
-            getPixelOffset: b => { const o = alignOf(b.d); return [b.title.x + o[0], b.title.top + o[1]]; },
+        } else if (glows.length && this.flags.has('AURA') && !glowHiddenByScale(st, liveZoom)) {
+          layers.push(new IconLayer({
+            id: `ix-aura-${this.name}${bs}-g${this._iconGeneration}`,
+            data: glows, pickable: false,
+            getPosition: d => d.geometry.coordinates,
+            getIcon: d => this._buildSingleIcon(borderRgb || colorOf(d.part.i), 0.3, 'circle', null, 0),
+            getSize: d => d.part.r * 2 * 1.3,
+            getPixelOffset: offsetOf,
+            getColor: d => [255, 255, 255, alphaOf(d)],
+            sizeUnits: 'pixels', billboard: true,
             parameters: ICON_LAYER_GLOBE_PARAMETERS
           }));
         }
-      }
-      if (glows.length && this.flags.has('GLOW') && !glowHiddenByScale(st, liveZoom)) {
         layers.push(new IconLayer({
-          id: `ix-glow-${this.name}-g${this._iconGeneration}`,
-          data: glows, pickable: false,
+          id: `ix-bubbles-${this.name}${bs}-g${this._iconGeneration}`,
+          data: parts, pickable: true,
           getPosition: d => d.geometry.coordinates,
-          getIcon: d => this._getGlowIcon(colorOf(d.part.i)),
-          getSize: d => d.part.r * 11,
-          getPixelOffset: offsetOf,
-          getColor: d => [255, 255, 255, alphaOf(d)],
-          sizeUnits: 'pixels', billboard: true,
-          parameters: ICON_LAYER_GLOBE_PARAMETERS
-        }));
-      } else if (glows.length && this.flags.has('AURA') && !glowHiddenByScale(st, liveZoom)) {
-        layers.push(new IconLayer({
-          id: `ix-aura-${this.name}-g${this._iconGeneration}`,
-          data: glows, pickable: false,
-          getPosition: d => d.geometry.coordinates,
-          getIcon: d => this._buildSingleIcon(borderRgb || colorOf(d.part.i), 0.3, 'circle', null, 0),
-          getSize: d => d.part.r * 2 * 1.3,
+          // the stroke, in the icon raster's pixels (the icon is drawn at 2r)
+          getIcon: d => {
+            // an external symbol file: the URL icon as flat's <image> (see
+            // urlSymbolOf above), scaled to the part's diameter like flat's
+            // fu.scale(nRadius / nMaxRadius) on a nChartSize image
+            const u = urlSymbolOf(d.part.i);
+            if (u) return urlIcon(u);
+            return this._buildSingleIcon(colorOf(d.part.i), noFill.has(d.part.i) ? 0 : fillOpacity, shapeOf(d.part.i), borderRgb,
+              borderRgb ? Math.round(lineWidth * unit * Math.min(2 * d.part.r / normalR, 0.2) * BUBBLE_ICON_SIZE / Math.max(1, 2 * d.part.r) * 4) / 4 : 0);
+          },
+          getSize: d => d.part.r * 2,
           getPixelOffset: offsetOf,
           getColor: d => [255, 255, 255, alphaOf(d)],
           sizeUnits: 'pixels', billboard: true,
           parameters: ICON_LAYER_GLOBE_PARAMETERS
         }));
-      }
-      layers.push(new IconLayer({
-        id: `ix-bubbles-${this.name}-g${this._iconGeneration}`,
-        data: parts, pickable: true,
-        getPosition: d => d.geometry.coordinates,
-        // the stroke, in the icon raster's pixels (the icon is drawn at 2r)
-        getIcon: d => {
-          // an external symbol file: the URL icon as flat's <image> (see
-          // urlSymbolOf above), scaled to the part's diameter like flat's
-          // fu.scale(nRadius / nMaxRadius) on a nChartSize image
-          const u = urlSymbolOf(d.part.i);
-          if (u) return urlIcon(u);
-          return this._buildSingleIcon(colorOf(d.part.i), noFill.has(d.part.i) ? 0 : fillOpacity, shapeOf(d.part.i), borderRgb,
-            borderRgb ? Math.round(lineWidth * unit * Math.min(2 * d.part.r / normalR, 0.2) * BUBBLE_ICON_SIZE / Math.max(1, 2 * d.part.r) * 4) / 4 : 0);
-        },
-        getSize: d => d.part.r * 2,
-        getPixelOffset: offsetOf,
-        getColor: d => [255, 255, 255, alphaOf(d)],
-        sizeUnits: 'pixels', billboard: true,
-        parameters: ICON_LAYER_GLOBE_PARAMETERS
-      }));
-      // VALUES on each part (maptheme.js 22188-22260): the part's value — with
-      // COUNT its record count, with valuefield on the categorical field the
-      // class name — formatted with valuedecimals (else none) plus the unit.
-      //  - a SHAPE part (circle & kin): font min(1, 3.2 / L) · r · valuescale,
-      //    L the length of the theme's biggest value text (szMaxText), normal
-      //    weight, in valuecolor / textcolor, else ChartColors.textColor of
-      //    the part color
-      //  - an IMAGE-symbol part (an external .svg, the TELRAAM pictograms):
-      //    flat's own other branch (22253-22256) — font max(r · 0.8, 1) ·
-      //    valuescale, the text over createTextLabel's background box (white,
-      //    its rgba(…,0.3) fill × the 0.5 fill-opacity) and in
-      //    ChartColors.lowColor — the 0.7 derivate of the part color —
-      //    regardless of valuecolor/textcolor (flat passes cColor.lowColor
-      //    straight into createTextLabel)
-      // CENTERVALUES: only on the first part (class 0), its own value
-      if ((this.flags.has('VALUES') || centerValues) && !valuesHiddenByScale(st, zoom)) {
-        const valueScale = styleNum(st.valuescale) || 1;
-        const { noBreaks } = this._valueTextOpts();
-        const units = st.units ? String(st.units) : '';
-        const unit = units ? (units[0] === '.' ? '' : ' ') + units : '';
-        const unitText = unit.length <= 5 ? unit : '';
-        const dec = explicitValueDecimals(st) || 0;
-        const fmt = v => flatGroupedValue(v, dec, noBreaks) + unitText;
-        const maxLen = fmt(seqMax).length;
-        const textOverride = st.valuecolor || st.textcolor;
-        const counting = flatFlag(this.flags, 'COUNT');
-        const labels = [];
-        parts.forEach(d => {
-          if (centerValues && d.part.i !== 0) return;
-          const rec = this._categoryValueRecord(d.part.i);
-          const name = rec ? String(rec[st.valuefield]) : null;
-          const t = counting && d.properties.recordCounts ? d.properties.recordCounts[d.part.i] : d.part.v;
-          const text = name != null ? name : fmt(t);
-          const image = !!urlSymbolOf(d.part.i);
-          const L = Math.max((name != null ? name.length : 0) + 1, maxLen);
-          const fontSize = image
-            ? Math.max(d.part.r * 0.8, 1) * valueScale
-            : Math.min(1, 3.2 / L) * d.part.r * valueScale;
-          if (fontSize > VALUES_MIN_FONT_PX) {
-            labels.push({ geometry: d.geometry, text, fontSize, pixelOffset: offsetOf(d), alpha: alphaOf(d),
-              image,
-              color: image ? flatDerivateRgb(colorOf(d.part.i), 0.7)
-                : textOverride ? hexOrNamedToRgb(textOverride) : flatChartTextRgb(colorOf(d.part.i)) });
-          }
-        });
-        if (labels.length) {
-          // VALUEBACKGROUND on URL-symbol parts: a fading white border
-          // around the value's own CHARACTER SHAPES — the glyphs
-          // re-drawn in white on rings of pixel offsets (a stroke of
-          // copies, no box): the width is a fraction of the font size,
-          // so the halo scales with every label; the shape-part values
-          // keep flat's plain text (no outline)
-          if (flatFlag(this.flags, 'VALUEBACKGROUND')) {
-            const haloLabels = labels.filter(l => l.image);
-            const plainLabels = labels.filter(l => !l.image);
-            if (haloLabels.length) {
-              // a real outline around the characters: the label's own
-              // glyphs re-drawn in white on rings of pixel offsets — a
-              // stroke of copies that hugs the character shapes (deck's
-              // SDF outline is only a faint, buffer-clipped rim). The
-              // base radius is a small fraction of the font size (the
-              // 1px floor keeps it tiny until labels get big), and the
-              // ring alphas fall off, so the border fades to nothing
-              const DIRS = 16, RINGS = [[1, 210], [2, 120], [3.2, 65]];
-              const haloCopies = [];
-              for (const l of haloLabels) {
-                const rb = Math.max(0.75, l.fontSize * 0.015);
-                for (let ring = 0; ring < RINGS.length; ring++) {
-                  for (let dir = 0; dir < DIRS; dir++) {
-                    const a = (dir / DIRS) * 2 * Math.PI;
-                    haloCopies.push({ ...l,
-                      dx: Math.cos(a), dy: Math.sin(a),
-                      radius: rb * RINGS[ring][0],
-                      haloAlpha: Math.round(RINGS[ring][1] * l.alpha / 255) });
+        // VALUES on each part (maptheme.js 22188-22260): the part's value — with
+        // COUNT its record count, with valuefield on the categorical field the
+        // class name — formatted with valuedecimals (else none) plus the unit.
+        //  - a SHAPE part (circle & kin): font min(1, 3.2 / L) · r · valuescale,
+        //    L the length of the theme's biggest value text (szMaxText), normal
+        //    weight, in valuecolor / textcolor, else ChartColors.textColor of
+        //    the part color
+        //  - an IMAGE-symbol part (an external .svg, the TELRAAM pictograms):
+        //    flat's own other branch (22253-22256) — font max(r · 0.8, 1) ·
+        //    valuescale, the text over createTextLabel's background box (white,
+        //    its rgba(…,0.3) fill × the 0.5 fill-opacity) and in
+        //    ChartColors.lowColor — the 0.7 derivate of the part color —
+        //    regardless of valuecolor/textcolor (flat passes cColor.lowColor
+        //    straight into createTextLabel)
+        // CENTERVALUES: only on the first part (class 0), its own value
+        if ((this.flags.has('VALUES') || centerValues) && !valuesHiddenByScale(st, zoom)) {
+          const valueScale = styleNum(st.valuescale) || 1;
+          const { noBreaks } = this._valueTextOpts();
+          const units = st.units ? String(st.units) : '';
+          const unit = units ? (units[0] === '.' ? '' : ' ') + units : '';
+          const unitText = unit.length <= 5 ? unit : '';
+          const dec = explicitValueDecimals(st) || 0;
+          const fmt = v => flatGroupedValue(v, dec, noBreaks) + unitText;
+          const maxLen = fmt(seqMax).length;
+          const textOverride = st.valuecolor || st.textcolor;
+          const counting = flatFlag(this.flags, 'COUNT');
+          const labels = [];
+          parts.forEach(d => {
+            if (centerValues && d.part.i !== 0) return;
+            const rec = this._categoryValueRecord(d.part.i);
+            const name = rec ? String(rec[st.valuefield]) : null;
+            const t = counting && d.properties.recordCounts ? d.properties.recordCounts[d.part.i] : d.part.v;
+            const text = name != null ? name : fmt(t);
+            const image = !!urlSymbolOf(d.part.i);
+            const L = Math.max((name != null ? name.length : 0) + 1, maxLen);
+            const fontSize = image
+              ? Math.max(d.part.r * 0.8, 1) * valueScale
+              : Math.min(1, 3.2 / L) * d.part.r * valueScale;
+            if (fontSize > VALUES_MIN_FONT_PX) {
+              labels.push({ geometry: d.geometry, text, fontSize, pixelOffset: offsetOf(d), alpha: alphaOf(d),
+                image,
+                color: image ? flatDerivateRgb(colorOf(d.part.i), 0.7)
+                  : textOverride ? hexOrNamedToRgb(textOverride) : flatChartTextRgb(colorOf(d.part.i)) });
+            }
+          });
+          if (labels.length) {
+            // VALUEBACKGROUND on URL-symbol parts: a fading white border
+            // around the value's own CHARACTER SHAPES — the glyphs
+            // re-drawn in white on rings of pixel offsets (a stroke of
+            // copies, no box): the width is a fraction of the font size,
+            // so the halo scales with every label; the shape-part values
+            // keep flat's plain text (no outline)
+            if (flatFlag(this.flags, 'VALUEBACKGROUND')) {
+              const haloLabels = labels.filter(l => l.image);
+              const plainLabels = labels.filter(l => !l.image);
+              if (haloLabels.length) {
+                // a real outline around the characters: the label's own
+                // glyphs re-drawn in white on rings of pixel offsets — a
+                // stroke of copies that hugs the character shapes (deck's
+                // SDF outline is only a faint, buffer-clipped rim). The
+                // base radius is a small fraction of the font size (the
+                // 1px floor keeps it tiny until labels get big), and the
+                // ring alphas fall off, so the border fades to nothing
+                const DIRS = 16, RINGS = [[1, 210], [2, 120], [3.2, 65]];
+                const haloCopies = [];
+                for (const l of haloLabels) {
+                  const rb = Math.max(0.75, l.fontSize * 0.015);
+                  for (let ring = 0; ring < RINGS.length; ring++) {
+                    for (let dir = 0; dir < DIRS; dir++) {
+                      const a = (dir / DIRS) * 2 * Math.PI;
+                      haloCopies.push({ ...l,
+                        dx: Math.cos(a), dy: Math.sin(a),
+                        radius: rb * RINGS[ring][0],
+                        haloAlpha: Math.round(RINGS[ring][1] * l.alpha / 255) });
+                    }
                   }
                 }
+                layers.push(new TextLayer({
+                  id: `ix-cluster-values-halo-${this.name}${bs}`,
+                  data: haloCopies, pickable: false,
+                  getPosition: d => d.geometry.coordinates,
+                  getText: d => d.text,
+                  getSize: d => d.fontSize,
+                  getColor: d => [255, 255, 255, d.haloAlpha],
+                  getPixelOffset: d => [d.pixelOffset[0] + d.dx * d.radius, d.pixelOffset[1] + d.dy * d.radius],
+                  sizeUnits: 'pixels', fontFamily: 'arial', fontWeight: 'normal',
+                  characterSet: 'auto',
+                  getTextAnchor: 'middle', getAlignmentBaseline: 'center'
+                }));
+                layers.push(new TextLayer({
+                  id: `ix-cluster-values-${this.name}${bs}`,
+                  data: haloLabels, pickable: false,
+                  getPosition: d => d.geometry.coordinates,
+                  getText: d => d.text,
+                  getSize: d => d.fontSize,
+                  getColor: d => [...d.color.slice(0, 3), d.alpha],
+                  getPixelOffset: d => d.pixelOffset,
+                  sizeUnits: 'pixels', fontFamily: 'arial', fontWeight: 'normal',
+                  characterSet: 'auto',
+                  getTextAnchor: 'middle', getAlignmentBaseline: 'center'
+                }));
               }
-              layers.push(new TextLayer({
-                id: `ix-cluster-values-halo-${this.name}`,
-                data: haloCopies, pickable: false,
-                getPosition: d => d.geometry.coordinates,
-                getText: d => d.text,
-                getSize: d => d.fontSize,
-                getColor: d => [255, 255, 255, d.haloAlpha],
-                getPixelOffset: d => [d.pixelOffset[0] + d.dx * d.radius, d.pixelOffset[1] + d.dy * d.radius],
-                sizeUnits: 'pixels', fontFamily: 'arial', fontWeight: 'normal',
-                characterSet: 'auto',
-                getTextAnchor: 'middle', getAlignmentBaseline: 'center'
-              }));
-              layers.push(new TextLayer({
-                id: `ix-cluster-values-${this.name}`,
-                data: haloLabels, pickable: false,
+              if (plainLabels.length) layers.push(new TextLayer({
+                id: `ix-cluster-values-plain-${this.name}${bs}`,
+                data: plainLabels, pickable: false,
                 getPosition: d => d.geometry.coordinates,
                 getText: d => d.text,
                 getSize: d => d.fontSize,
@@ -14877,10 +15510,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
                 characterSet: 'auto',
                 getTextAnchor: 'middle', getAlignmentBaseline: 'center'
               }));
-            }
-            if (plainLabels.length) layers.push(new TextLayer({
-              id: `ix-cluster-values-plain-${this.name}`,
-              data: plainLabels, pickable: false,
+            } else {
+            layers.push(new TextLayer({
+              id: `ix-cluster-values-${this.name}${bs}`,
+              data: labels, pickable: false,
               getPosition: d => d.geometry.coordinates,
               getText: d => d.text,
               getSize: d => d.fontSize,
@@ -14890,21 +15523,20 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
               characterSet: 'auto',
               getTextAnchor: 'middle', getAlignmentBaseline: 'center'
             }));
-          } else {
-          layers.push(new TextLayer({
-            id: `ix-cluster-values-${this.name}`,
-            data: labels, pickable: false,
-            getPosition: d => d.geometry.coordinates,
-            getText: d => d.text,
-            getSize: d => d.fontSize,
-            getColor: d => [...d.color.slice(0, 3), d.alpha],
-            getPixelOffset: d => d.pixelOffset,
-            sizeUnits: 'pixels', fontFamily: 'arial', fontWeight: 'normal',
-            characterSet: 'auto',
-            getTextAnchor: 'middle', getAlignmentBaseline: 'center'
-          }));
+            }
           }
         }
+      };
+      const chartBand = c => bandOfChart.get(c) || 0;
+      if (nBands > 1) {
+        // deck.gl draws the FIRST layer at the bottom: the smallest
+        // charts' band first, the biggest (band 0) last, on top
+        for (let k = nBands - 1; k >= 0; k--) drawBand(
+          boxLayoutAll ? boxLayoutAll.filter(b => chartBand(b.d) === k) : null,
+          allGlows.filter(g => chartBand(g.chart) === k),
+          allParts.filter(p => chartBand(p.chart) === k), '-b' + k);
+      } else {
+        drawBand(boxLayoutAll, allGlows, allParts, '');
       }
       return layers;
     }
@@ -14964,8 +15596,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     //    CENTERVALUE the item's record count
     // Not drawn here (a console note at type parsing, PIE_INERT_FLAGS,
     // PIE_AGGREGATE_INERT_FLAGS):
-    // 3D, VOLUME, HEIGHT, STARBURST, FLOWER/RAYS, BOW, ZOOM, DIRECTION /
-    // DIRECTED, POLAR — the pie is drawn flat and plain instead. Nor
+    // 3D, VOLUME, HEIGHT, BOW, ZOOM, DIRECTION / DIRECTED — the pie is
+    // drawn flat and plain instead; POLAR without STARBURST has no
+    // effect in flat either. STARBURST (with the FLOWER/RAYS angle/gap
+    // variants) and its POLAR circles ARE drawn (pieSliceLayout). Nor
     // style.clipparts, showparts, gridx (flat's several pies per item).
     // Known divergence: flat draws a chart's value labels in the chart's
     // own group, so a bigger pie drawn later covers a smaller neighbour's
@@ -15029,6 +15663,17 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const lineRgb = line === 'none' ? null : hexOrNamedToRgb(line);
       const lineWidthOf = r => (lineRgb ? (styleNum(st.linewidth) || 0.1) * r / 15 : 0);
       const lineRgba = lineRgb ? [...lineRgb.slice(0, 3), Math.round(255 * lineAlpha)] : [0, 0, 0, 0];
+      // flat's STARBURST (maptheme.js 20262-20275, piechart.js 281-287,
+      // 415-420): the parts get equal angles and a ray's radius carries
+      // its value — inner + span · sqrt(v / maxValue) · scale, scale =
+      // maxValue / (normalsizevalue || maxValue) · 2.14 (with SIZE flat
+      // sets only maxValue, so a part at the reference value reaches
+      // 2.14 R). maxValue: style.maxvalue (the reference — the ISTAT
+      // story's national mean), else the biggest part value over the
+      // items (flat's max of the per-part maxima nMaxA). The star's
+      // inner px (the ray variants' 5px) comes off the layout
+      const star = has(/STARBURST/);
+      let starMaxPart = 0;
 
       const charts = [];
       if (agg) {
@@ -15043,6 +15688,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           if (!layout) continue;
           if (cat) layout.slices.forEach(sl => { sl.single = values.length === 1; });
           const sum = values.reduce((a, v) => a + (isNaN(v) ? 0 : v), 0);
+          if (star) for (const v of values) if (v > starMaxPart) starMaxPart = v;
           const r = nSizeOf(sum, size) * unit;
           if (!(r > 0) || !isFinite(r)) continue;
           // flat's draw-order key (maptheme.js 16812-16860): with a size
@@ -15067,6 +15713,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const layout = pieSliceLayout(values, t, { centerPart: st.centerpart });
         if (!layout) continue;
         const sum = values.reduce((a, v) => a + v, 0);
+        if (star) for (const v of values) if (v > starMaxPart) starMaxPart = v;
         const size = this.binding.size ? parseFloat(raw[this.binding.size]) : undefined;
         const r = nSizeOf(sum, size) * unit;
         if (!(r > 0) || !isFinite(r)) continue;
@@ -15099,14 +15746,80 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       });
 
       const TAU = 2 * Math.PI;
-      const slices = [], centers = [], glows = [];
+      const slices = [], centers = [], glows = [], polar = [], polarDashes = [];
       const glowOn = has(/GLOW/) && !has(/ZOOM/) && !glowHiddenByScale(st, liveZoom);
+      // the STARBURST ray scale (see the star comment above): style
+      // maxvalue, else the biggest part value over the items — flat's
+      // `this.nMaxValue || max(nMaxA)`. Without SIZE flat also sets the
+      // donut's normalSizeValue (normalsizevalue, else maxValue), which
+      // dampens the scale
+      const starMax = styleNum(st.maxvalue);
+      const starRef = !isNaN(starMax) && starMax > 0 ? starMax : (starMaxPart > 0 ? starMaxPart : 1);
+      const starNsv = has(/\bSIZE\b/) ? starRef : (nsv || starRef);
+      const starScale = starRef / starNsv * 2.14;
+      // a chart's rays start at the CENTER — flat's `max(5, nRadInner)`
+      // for the ray variants is 5 units of the chart's internal
+      // coordinate system, sub-pixel and invisible on screen (see
+      // pieSliceLayout) — and only with DONUT at the donut's inner
+      // radius (flat piechart.js 326-327: nRadOuter += nRadInner, the
+      // span stays R)
+      const starInnerOf = ch => (ch.layout.inner || 0) * ch.r;
+      const starRadius = (v, R, inner) => Math.max(1, inner + (R - inner) * Math.sqrt(Math.max(0, v) / starRef) * starScale);
       for (const ch of charts) {
+        const starInner = star ? starInnerOf(ch) : 0;
+        if (star && has(/POLAR/)) {
+          // flat piechart.js 435-452: the STARBURST's reference circles —
+          // a white disc at the reference value (fill-opacity 0.25,
+          // #444444 border, solid) and range rings at 75 / 50 / 25 % of
+          // it, the 75% and 25% rings DASHED (stroke-dasharray 50 50 in
+          // the chart group's units, on for half of each cycle). All of
+          // them under every ray. The stroke widths are flat's 1px /
+          // 3px — in the CHART GROUP's coordinate system, whose scale
+          // is ~0.017 of the screen, so on screen they are sub-pixel
+          // hairlines (measured on the ISTAT story: the disc's 197
+          // group-units radius is 11.2px on screen); 1px ≈ 1.1% and
+          // 3px ≈ 3.2% of the base radius R, taken here as fractions
+          // of ch.r so they stay hairlines at every zoom, as in flat
+          const lw1 = ch.r * 0.0108, lw3 = ch.r * 0.0325;
+          const w = ch.r - starInner;
+          polar.push({ position: ch.c, r: starInner + w * starScale, off: ch.off,
+            fill: [255, 255, 255, 64], line: [68, 68, 68, 255], lw: lw1 });
+          polar.push({ position: ch.c, r: starInner + w * Math.sqrt(0.5) * starScale, off: ch.off,
+            fill: [0, 0, 0, 0], line: [68, 68, 68, 255], lw: lw1 });
+          // the dashed rings: one chord per dash — flat's own arcs are
+          // octant polylines, so straight chords are as faithful. The
+          // dash count is flat's geometry: a 50-unit dash on the ring's
+          // group radius — the ring in group units is ~17.7 × its
+          // screen radius (the chart group scale measured on the
+          // story), so a cycle is 100 group units = 100/(17.7 · 2π ·
+          // ringR_screen) of the circle: ~11 dashes around the 75%,
+          // ~6 around the 25% ring, at every zoom
+          for (const q of [0.75, 0.25]) {
+            const rr = starInner + w * Math.sqrt(q) * starScale;
+            const cycles = Math.max(q > 0.5 ? 4 : 3, Math.round((q > 0.5 ? 2.06 : 1.19) * ch.r));
+            const seg = 2 * Math.PI / cycles;
+            for (let i = 0; i < cycles; i++) {
+              const a0 = i * seg, a1 = a0 + seg / 2;
+              // 0 at 12 o'clock, clockwise (pieSliceLayout's convention);
+              // pixelOffsetLngLat's y grows down
+              polarDashes.push({
+                path: [
+                  pixelOffsetLngLat(ch.c, [Math.sin(a0) * rr, -Math.cos(a0) * rr], liveZoom),
+                  pixelOffsetLngLat(ch.c, [Math.sin(a1) * rr, -Math.cos(a1) * rr], liveZoom)
+                ], lw: lw3
+              });
+            }
+          }
+        }
         for (const sl of ch.layout.slices) {
           const rgb = sliceRgb(sl);
+          // STARBURST: this ray's own radius (the value), its inner the
+          // px starInner as a fraction of that radius — the shader takes
+          // a fraction of the instance radius, which varies per ray here
+          const rayR = star ? starRadius(sl.value, ch.r, starInner) : ch.r;
           slices.push({
-            position: ch.c, r: ch.r, off: ch.off, properties: ch.properties, chart: ch, part: sl,
-            slice: [sl.start * Math.PI / 180, sl.sweep >= 360 ? TAU : sl.sweep * Math.PI / 180, ch.layout.inner],
+            position: ch.c, r: rayR, off: ch.off, properties: ch.properties, chart: ch, part: sl,
+            slice: [sl.start * Math.PI / 180, sl.sweep >= 360 ? TAU : sl.sweep * Math.PI / 180, star ? starInner / rayR : ch.layout.inner],
             fill: [...rgb.slice(0, 3), !sl.complement && noFill.has(sl.i) ? 0 : Math.round(255 * fillAlpha)]
           });
         }
@@ -15130,13 +15843,80 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         radiusUnits: 'pixels', billboard: true, stroked: false, filled: true, antialiasing: true,
         parameters: ICON_LAYER_GLOBE_PARAMETERS
       };
-      const layers = [new PieSliceLayer(Object.assign({}, discProps, {
+      // flat's BOX / TITLE for a pie (maptheme.js 18446-18925, the same
+      // block the sequence builder draws): a rectangle around the
+      // chart's drawn extent — on a STARBURST the longest ray, the
+      // disc otherwise — plus, with TITLE, the item's title (an
+      // aggregated grid cell of more than 3 records without its own:
+      // "(n)", see _itemTitle) at the chart's left edge, wrapped to
+      // the chart's width, in textcolor (#888888) over a half-opaque
+      // white halo, its first baseline 0.7 font above the box — the
+      // box grows to enclose it, its top trimmed by 0.1 font. The
+      // box: white at boxopacity, #bbbbbb border at 0.3 opacity
+      // (borderstyle solid/dotted/dashed: 1, none: no border),
+      // borderwidth · 0.2 · width/chartSize px wide. Both are removed
+      // outside boxupper / titleupper (maptheme.js 18758-18760, the
+      // TITLE gate 18809-18811)
+      // the chart's drawn extent, px around the anchor (flat's getBox of the
+      // shape group — the longest ray on a STARBURST)
+      const boxRows = this._boxRows(charts, { unit, liveZoom, extentOf: ch => {
+        let e = ch.r;
+        if (star) { const in0 = starInnerOf(ch); for (const sl of ch.layout.slices) e = Math.max(e, starRadius(sl.value, ch.r, in0)); }
+        return [-e, -e, e, e];
+      } });
+      const layers = [];
+      if (boxRows && boxRows.length) {
+        const L = this._boxTitleLayers(boxRows, {
+          unit, liveZoom,
+          positionOf: b => b.d.c, offsetOf: b => b.d.off,
+          ids: { circle: `ix-pie-box-${this.name}`, icon: `ix-pie-box-${this.name}`, polygons: `ix-pie-box-polygons-${this.name}`, titles: `ix-pie-titles-${this.name}` }
+        });
+        layers.push(...L.box, ...L.titles);
+      }
+      if (polar.length) {
+        layers.push(new ScatterplotLayer({
+          id: `ix-pie-polar-${this.name}`,
+          data: polar, pickable: false,
+          getPosition: d => d.position,
+          getRadius: d => d.r,
+          getPixelOffset: d => d.off,
+          radiusUnits: 'pixels', billboard: true,
+          filled: true, stroked: true,
+          getFillColor: d => d.fill,
+          getLineColor: d => d.line,
+          getLineWidth: d => d.lw,
+          lineWidthUnits: 'pixels',
+          parameters: ICON_LAYER_GLOBE_PARAMETERS
+        }));
+        // flat's dashed range rings (see the polar block): one chord per
+        // dash, drawn in map coordinates at the current zoom — the
+        // chart anchors move on zoom, and the layers rebuild with them
+        if (polarDashes.length) {
+          layers.push(new PathLayer({
+            id: `ix-pie-polar-dashes-${this.name}`,
+            data: polarDashes, pickable: false,
+            getPath: d => d.path,
+            getColor: [68, 68, 68, 255],
+            getWidth: d => d.lw,
+            widthUnits: 'pixels',
+            parameters: ICON_LAYER_GLOBE_PARAMETERS
+          }));
+        }
+      }
+      layers.push(new PieSliceLayer(Object.assign({}, discProps, {
         id: `ix-pie-${this.name}`,
         data: slices, pickable: true,
         getLineColor: lineRgba,
         getSlice: d => d.slice,
-        getSliceLineWidth: d => lineWidthOf(d.r)
-      }))];
+        // flat's pie outline (piechart.js: normalX(linewidth) · R / 300)
+        // is 2% of the radius — sub-pixel for every small chart, and the
+        // browser rasterizes it as a HAIRLINE: one device pixel at full
+        // opacity (Skia's stroke floor). The 1 device-px floor here
+        // matches that: the width is in the shader's device-pixel
+        // space (pieAA = fwidth), so the CSS width is scaled by the
+        // device pixel ratio first
+        getSliceLineWidth: d => (lineWidthOf(d.r) > 0 ? Math.max(lineWidthOf(d.r) * (global.devicePixelRatio || 1), 1) : 0)
+      })));
       if (centers.length) {
         layers.push(new PieSliceLayer(Object.assign({}, discProps, { id: `ix-pie-center-${this.name}`, data: centers, pickable: true })));
       }
@@ -15350,7 +16130,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     //    STACKED beside the column on leader lines; flat's values color
     //    #798697 (textcolor), negative red (valuecolor); DTEXT and a sized
     //    POINTER fade small values
-    //  - BOX / TITLE (flatChartBox): a box around chart and title, the
+    //  - BOX / TITLE (chartBoxLayout): a box around chart and title, the
     //    item's title above it — boxcolor (white) at boxopacity, bordercolor
     //    (#bbbbbb) at 0.3, borderwidth · 0.2 · w / 30; title 5 u ·
     //    textscale in textcolor (#888888) over a white halo
@@ -15446,9 +16226,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       }
       applyFlatMaxCharts(charts, st);
 
-      const boxShown = flatFlag(this.flags, 'BOX') && !boxHiddenByScale(st, liveZoom);
-      const titleShown = boxShown && flatFlag(this.flags, 'TITLE') && !!this.binding.title;
-      const titleFont = 5 * (num(st.textscale) || num(st.valuescale) || 1);
+      // a BAR draws its box as a shader shape (rectangle only, no CIRCULARBOX):
+      // the gates, margin, title font and placement are the box's, shared with
+      // every chart type (_boxSpec / chartBoxLayout, here in chart units)
+      const boxSpec = this._boxSpec(liveZoom);
+      const boxUnits = st.titleunits ? ' ' + st.titleunits : '';
       const boxOpacity = isNaN(styleNum(st.boxopacity)) ? 1 : styleNum(st.boxopacity);
       const borderStyle = String(st.borderstyle || '');
       const boxFill = [...hexOrNamedToRgb(isNoneColor(st.boxcolor) ? 'white' : st.boxcolor || 'white').slice(0, 3), isNoneColor(st.boxcolor) ? 0 : Math.round(255 * boxOpacity)];
@@ -15477,10 +16259,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       for (const ch of charts) {
         const L = ch.layout;
         let box = null;
-        if (boxShown) {
-          const title = titleShown ? this._itemTitle(ch.properties) : '';
-          box = flatChartBox(L.extent, { margin: num(st.boxmargin) || 2, titleFont, title: title ? title + (st.titleunits || '') : '',
-            bottomTitle: flatFlag(this.flags, 'BOTTOMTITLE'), alignRight: /right/.test(String(st.align || '')), measure });
+        if (boxSpec) {
+          const title = boxSpec.titleShown ? this._itemTitle(ch.properties) : '';
+          box = chartBoxLayout(L.extent, { unit: 1, margin: boxSpec.margin, titleText: title ? title + boxUnits : '',
+            titleFont: w => boxSpec.titleFontOf(1, w), bottomTitle: boxSpec.bottomTitle, alignRight: boxSpec.alignRight, measure });
         }
         const ext = box ? box.rect : L.extent;
         // align / offsetx / offsety (flatChartAlignOffset), the chart's
@@ -15489,9 +16271,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         if (box) {
           const r = box.rect;
           shape(ch, { base: [(r[0] + r[2]) / 2, r[3]], dir: 0, len: r[3] - r[1], w2: (r[2] - r[0]) / 2, sw: (r[2] - r[0]) / 2, band: 0, head: 0 },
-            boxFill, boxLine, borderWidth * 0.2 * box.width / 30, null, true);
-          if (box.title) titles.push({ position: ch.c, text: box.title.lines.join('\n'), font: box.title.font * unit, anchor: box.title.anchor,
-            off: [box.title.x * unit + ch.off[0], (box.title.baseline - 0.8 * box.title.font) * unit + ch.off[1]] });
+            boxFill, boxLine, borderWidth * 0.2 * box.w / 30, null, true);
+          // the title in px, rendered by the shared title layer
+          if (box.title) titles.push({ d: ch, title: { text: box.title.text, x: box.title.x * unit, anchor: box.title.anchor,
+            top: box.title.top * unit, f: box.title.f * unit } });
         }
         for (const b of L.bars) {
           const rgb = this.classRgb(b.cls);
@@ -15559,18 +16342,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           backgroundPadding: [0.3, 0, 0.4, 0.1].map(k => k * boxed.reduce((a, d) => a + d.font, 0) / boxed.length)
         })));
       }
-      if (titles.length) {
-        layers.push(new TextLayer({
-          id: `ix-bar-titles-${this.name}`, data: titles, pickable: false,
-          getPosition: d => d.position, getText: d => d.text, getSize: d => d.font,
-          sizeUnits: 'pixels', fontFamily: 'arial', characterSet: 'auto', lineHeight: 1,
-          getColor: [...hexOrNamedToRgb(st.textcolor || '#888888').slice(0, 3), 255],
-          fontSettings: { sdf: true }, outlineWidth: 1 / 7, outlineColor: [255, 255, 255, 128],
-          getTextAnchor: d => d.anchor, getAlignmentBaseline: 'top',
-          getPixelOffset: d => d.off,
-          parameters: ICON_LAYER_GLOBE_PARAMETERS
-        }));
-      }
+      if (titles.length) layers.push(...this._boxTitleLayers(titles, {
+        box: false, unit, liveZoom, positionOf: b => b.d.c, offsetOf: b => b.d.off,
+        ids: { titles: `ix-bar-titles-${this.name}` }
+      }).titles);
       return layers;
     }
 
@@ -15757,22 +16532,28 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         return [(lng + 180) / 360 * world, (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * world];
       };
       const mercToLngLat = ([x, y]) => [x / world * 360 - 180, (2 * Math.atan(Math.exp((0.5 - y / world) * 2 * Math.PI)) - Math.PI / 2) * 180 / Math.PI];
-      // the curves are computed in the plane of flat's map (Equal Earth), at the screen
-      // size of this map's degree of longitude on the equator, then mapped back: the
-      // flow bows around the pole as on flat. Mercator's plane stays the default.
-      // On the globe (flat's orthographic map) the plane is the one of the view center,
-      // for the flows whose two ends face the viewer; the others keep Mercator's.
+      // the curves are computed in the plane the map is DISPLAYED in: Web
+      // Mercator under MapLibre's mercator projection; on the globe (flat's
+      // orthographic map) the orthographic plane of the view center, for
+      // the flows whose two ends face the viewer (the others keep
+      // Mercator's). flat's own Equal Earth / Winkel plane (e1cb264) is NOT
+      // used: this engine displays those maps in Web Mercator too (a flat
+      // SVG map in another projection is reported "not available — mercator
+      // used"), and a curve bowed in the Equal Earth plane swings far
+      // toward the pole once Mercator renders it — measured on
+      // mechanical_goods_flows.html: Japan→USA at 82°N, its bow almost half
+      // the chord, where the Mercator curve stays at 63°N — the "deviated
+      // near the north pole" vectors. Flat bows its curves in the plane of
+      // ITS map; here the plane of the display.
       const planeFns = (proj, k) => ({
         toPx: ([lng, lat]) => { const q = proj.project(lat, lng); return [q[0] * k, -q[1] * k]; },
         toLngLat: ([x, y]) => { const q = proj.invert(x / k, -y / k); return [q[1], q[0]]; }
       });
       const mercFns = { toPx: mercToPx, toLngLat: mercToLngLat };
-      const fixedPlane = flatPlaneProjectionByOptions.get(this.mapOptions);
-      const fixedFns = fixedPlane && fixedPlane.invert ? planeFns(fixedPlane, (world / 360) / fixedPlane.project(0, 1)[0]) : null;
       const planeCenter = flatViewCenterByOptions.get(this.mapOptions) || globeCenter;
-      const ortho = !fixedFns && globeCenter ? orthographicPlane(planeCenter.lat, planeCenter.lng) : null;
+      const ortho = globeCenter ? orthographicPlane(planeCenter.lat, planeCenter.lng) : null;
       const orthoFns = ortho ? planeFns(ortho, world / (2 * Math.PI)) : null;
-      const fnsOf = it => (fixedFns || (orthoFns && ortho.inFront(it.p1) && ortho.inFront(it.p2) ? orthoFns : mercFns));
+      const fnsOf = it => (orthoFns && ortho.inFront(it.p1) && ortho.inFront(it.p2) ? orthoFns : mercFns);
       const inBox = c => c && c[0] >= bbox[0] && c[0] <= bbox[2] && c[1] >= bbox[1] && c[1] <= bbox[3];
 
       const sizePow = resolveSizePow(st, this.flags);
@@ -15871,7 +16652,6 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           // — every size equal — SVG ignores: the opacity stays)
           if (dop || dopMin) { const d = dopacity(it); if (isFinite(d)) { lineAlpha = d; headAlpha = d; } }
           if (gradient) stops = fadeGradientStops(pts, lay.vx, lay.vy, fade);
-          if (dash) dashArr = [50 * oz, 5 * oz + sw];
           pts = pts.map(p => [p[0] + a[0], p[1] + a[1]]);
           end = [end[0] + a[0], end[1] + a[1]];
         } else {
@@ -15885,7 +16665,25 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           headS = 4; refX = 4; refY = 2;
           lineAlpha = fo || 0.3;
           headAlpha = Math.min(1, (fo || 0.3) * 2);
-          if (dash) dashArr = [50 * oz, 15 * oz];
+        }
+        if (dash) {
+          // flat's dash pattern: one long dash (50 px at the object scale)
+          // and a small gap, its phase walking toward the target — a flow
+          // of any length gets its own count of dashes that way: long ones
+          // many, short ones none at all (a solid line). style.dashcount
+          // instead divides the flow into that many dash+gap periods:
+          // every flow, long or short, shows the same pattern and moves at
+          // the same relative speed (one full dash cycle every 2s), the
+          // arrows as on the region-migration page
+          const nDashes = Math.round(styleNum(st.dashcount) || 0);
+          if (nDashes >= 1) {
+            let flowPx = 0;
+            for (let i = 1; i < pts.length; i++) flowPx += Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]);
+            const period = flowPx / nDashes;
+            dashArr = [period * 0.85, period * 0.15];
+          } else {
+            dashArr = bezier ? [50 * oz, 5 * oz + sw] : [50 * oz, 15 * oz];
+          }
         }
         // a line under a pixel: one pixel at its width as opacity
         const drawW = Math.max(1, sw);
@@ -15911,7 +16709,11 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         let run = [], runColors = [];
         const flush = () => {
           if (run.length > 1) {
-            const dash = dashArr ? [dashArr[0] / drawW, dashArr[1] / drawW] : [0, 0];
+            // the flow triple: [dash, gap] in px (the shader's path
+            // distance unit) + flat's random per-arc dashoffset phase
+            // (maptheme.js 18249), fixed per arc: the layers are rebuilt on
+            // every pan/zoom, a new random phase each time made dashes jump
+            const dash = dashArr ? [dashArr[0], dashArr[1], flowDashPhase(p1, p2)] : [0, 0, 0];
             if (globeCenter && !dashArr) {
               // on the globe deck.gl draws only the first three quarters of a path that has a
               // color per vertex (also an equal one): one color per path, a gradient as one
@@ -15946,12 +16748,22 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
             fill: [...rgb.slice(0, 3), Math.round(255 * Math.min(1, headAlpha) * groupAlpha)] });
         }
       }
-      const layers = [new PathLayer({
+      // always FlowPathLayer: without dash offsets its flow hook no-ops
+      // (solid lines), with them the pattern walks toward the target
+      // (see makeFlowPathLayer). The dash triple is px; deck's path
+      // shader measures along-path positions in HALF-STROKE-WIDTH
+      // units (see makeFlowPathLayer), so the accessors convert:
+      // getDashArray carries the pattern period (its gap stays 0 — the
+      // extension renders solid, the moving gap is the flow hook),
+      // getFlowPhase the solid length and flat's random per-arc phase
+      const layers = [new FlowPathLayer({
         id: `ix-vector-${this.name}`, data: paths, pickable: true,
         getPath: d => d.path, getColor: d => d.colors, getWidth: d => d.width,
+        getDashArray: d => [(d.dash[0] + d.dash[1]) * 2 / Math.max(d.width, 1), 0],
+        getFlowPhase: d => [d.dash[0] * 2 / Math.max(d.width, 1), d.dash[2]],
         widthUnits: 'pixels', capRounded: dash && bezier, jointRounded: false, billboard: false,
-        parameters: ICON_LAYER_GLOBE_PARAMETERS,
-        ...(dash ? { getDashArray: d => d.dash, extensions: [new PathStyleExtension({ dash: true })] } : {})
+        extensions: [new PathStyleExtension({ dash: true, dashMode: 'path' })],
+        parameters: ICON_LAYER_GLOBE_PARAMETERS
       })];
       if (heads.length) {
         // the head count in the id: deck kept a same-id polygon layer's
@@ -15970,7 +16782,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     // flat's chart position for this build (flatChartAlignOffset): a
     // function item → pixel offset, the same for every part of one chart
     // (symbol, glow, shadow, box, title, value text). unit is flat's
-    // normalX(1) on screen, the object zoom × style.scale.
+    // normalX(1) on screen, the object zoom × style.scale. flat keeps a margin of 5 units between the
+    // position and the chart's facing edge for left/right/top/bottom; the gl-only style.alignmargin
+    // changes it (0: the edge touches the position, so a left and a right chart touch each other)
     _chartAlignFn(liveZoom, radiusOf, textOnly = false) {
       const st = this.style;
       const none = () => [0, 0];
@@ -15979,12 +16793,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const unit = objectZoomFactor(liveZoom, this.mapOptions) * (styleNum(st.scale) || 1);
       const symbol = flatChartBranch(this.flags) === 'symbol';
       const normalR = NORMAL_RADIUS_PX * unit; // flat's normalX(chart size / 2)
+      const margin = Number.isFinite(styleNum(st.alignmargin)) ? styleNum(st.alignmargin) : 5;
       const cache = new Map();
       const fn = d => {
         let v = cache.get(d);
         if (v) return v;
         const r = radiusOf(d);
-        v = flatChartAlignOffset(st, { unit, symbolScale: symbol ? r / (2 * normalR) : 1, half: symbol ? normalR : r, orig: r + (textOnly ? 0 : 5 * unit) });
+        v = flatChartAlignOffset(st, { unit, symbolScale: symbol ? r / (2 * normalR) : 1, half: symbol ? normalR : r, orig: r + (textOnly ? 0 : margin * unit) });
         cache.set(d, v);
         return v;
       };
@@ -16051,7 +16866,8 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const v = raw && raw[this.style.labelfield];
         let text = v == null || v === '' ? '' : String(v);
         if (!text) return null;
-        const num = parseFloat(text.replace(',', '.'));
+        // flat reads it with __scanValue: "1.234,5", "12 500"
+        const num = flatScanValue(text);
         text = (!isNaN(num) ? flatGroupedValue(num, dec != null ? dec : 2, noBreaks) : text) + units;
         const width = Math.max(titleTextWidth(text, f), (text.length + 2) * f * 0.5);
         const x = width / 3, y = f / 3 + r + 5 * unitPx;
@@ -16162,7 +16978,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       const textOnly = this.flags.has('TEXTONLY');
       const showValues = this.flags.has('VALUES') && !valuesHiddenByScale(this.style, zoom);
       if (textOnly && !showValues) return [];
-      const radiusOf = d => valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue);
+      const radiusOf = d => valueRadius(sizeValueOf(d), liveZoom, this.style, this.mapOptions, this.flags, this._maxSizeValue, this._sizeBound());
       const alignOf = this._chartAlignFn(liveZoom, radiusOf, textOnly);
       const valueScale = styleNum(this.style.valuescale) || 1;
       const textOverride = this.style.valuecolor || this.style.textcolor;
@@ -16223,6 +17039,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // the box is sized by the value's own text, not the valuefield's
       const boxStyle = Object.assign({}, this.style, { valuefield: undefined });
       const boxes = [], texts = [];
+      // the label's drawn extent for the chart-group BOX (below): x from -r
+      // to 1.05r, y from -0.83f to 0.77f around the chart origin
+      const labelExtent = new Map();
       for (const d of combined) {
         const r = radiusOf(d);
         if (!(r > 0)) continue;
@@ -16237,6 +17056,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         const o = alignOf(d);
         // the box's center relative to the chart's: x from −r to 1.05r, y from −0.83f to 0.77f
         boxes.push({ ...d, icon, pixelOffset: [o[0] + 0.025 * r, o[1] - 0.03 * f] });
+        labelExtent.set(d, [-r, -0.83 * f, 1.05 * r, 0.77 * f]);
         if (showValues) {
           const text = textOf(props);
           const fontSize = Math.min(r * 0.8, r * 3.3 / Math.max(1, text.length)) * valueScale;
@@ -16244,7 +17064,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           if (fontSize > 0) texts.push({ ...d, text, fontSize, color, pixelOffset: o });
         }
       }
-      const layers = [];
+      // BOX / TITLE: flat's chart-group box around the label chart
+      const boxRows = this._boxRows(() => combined.filter(d => labelExtent.has(d)), { unit, liveZoom, extentOf: d => labelExtent.get(d) });
+      const boxLayers = boxRows ? this._boxTitleLayers(boxRows, {
+        unit, liveZoom, positionOf: b => b.d.geometry.coordinates, offsetOf: b => alignOf(b.d),
+        ids: { circle: `ix-label-box-${this.name}`, icon: `ix-label-box-${this.name}`, polygons: `ix-label-box-polygons-${this.name}`, titles: `ix-label-titles-${this.name}` }
+      }) : null;
+      const layers = boxLayers ? [...boxLayers.box] : [];
       if (boxes.length) {
         layers.push(new IconLayer({
           id: `ix-bubbles-${this.name}-g${this._iconGeneration}`,
@@ -16278,6 +17104,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
           parameters: ICON_LAYER_GLOBE_PARAMETERS
         }));
       }
+      if (boxLayers) layers.push(...boxLayers.titles);
       return layers;
     }
 
@@ -16535,12 +17362,16 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   const _mapHandles = Object.create(null);
   function makeMapHandle(szMap) {
     const h = {};
-    const api = () => (szMap && _mapApis[szMap]) || _lastMapApi;
+    // a name a Map() declared waits for that map; any other name (or none)
+    // is the last built map, as before
+    const declared = () => szMap && _namedMapReady[szMap];
+    const api = () => (szMap && _mapApis[szMap]) || (declared() ? null : _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));
+        (declared() ? declared().promise : _mapReady).then(ready => ready[m](...args))
+          .catch(err => console.error(`[ixmaps-gl] map(${szMap ? '"' + szMap + '"' : ''}).${m}:`, err));
         return h;
       };
     }
@@ -16708,6 +17539,9 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // several themes of a page
       szId: themeIdOf(rt),
       szName: rt.name,
+      // flat's szSelectionField: the field a click on an item selects by (the id binding, else the field the
+      // item is positioned by)
+      szSelectionField: selectionFieldOf(rt),
       // the filter in force: a runtime one (changeThemeStyle "filter")
       // replaces the definition's
       szFilter: rt._runtimeFilterExpr || rt._filterExpr || '',
@@ -16744,6 +17578,13 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       get itemA() { return onMap().itemA; }
     };
   }
+  // the field whose value identifies an item on a click (flat's szSelectionField): binding.id, else the position field
+  // (which a join to a geometry layer turns into binding.lookup)
+  function selectionFieldOf(rt) {
+    const b = rt.binding || {};
+    const f = b.id || b.position || b.lookup;
+    return typeof f === 'string' && f && f !== 'geometry' && !/^geometry$/i.test(f) ? f : null;
+  }
   const _warnedOnce = new Set();
   function warnOnce(key, msg) { if (!_warnedOnce.has(key)) { _warnedOnce.add(key); console.info(msg); } }
   // the theme's records as flat's dbFields/dbRecords (cached per data)
@@ -17005,9 +17846,14 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
       // their own comments) are still real, directly-callable globals a
       // page's OWN custom UI can use too — only THIS generated markup
       // happens to reach them via delegation instead of inline HTML.
+      // the handlers below outlive this call: they read the theme id of
+      // the LATEST call into this container (a theme switch re-renders
+      // the same div for another theme)
+      container._ixFacetsId = szId;
       if (!container.dataset.ixFacetsWired) {
         container.dataset.ixFacetsWired = '1';
         container.addEventListener('click', e => {
+          const szId = container._ixFacetsId;
           const moreBtn = e.target.closest('[data-role="more"]');
           if (moreBtn) { moreBtn.hidden = true; moreBtn.nextElementSibling.hidden = false; return; }
 
@@ -17033,7 +17879,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         container.addEventListener('keyup', e => {
           if (e.key !== 'Enter') return;
           const input = e.target.closest('[data-role="search"]');
-          if (input) global.__setFilter(szId, input.closest('[data-field]').dataset.field, input.value);
+          if (input) global.__setFilter(container._ixFacetsId, input.closest('[data-field]').dataset.field, input.value);
         });
       }
     }
@@ -17123,11 +17969,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // known real page's globe toggle actually uses (see
   // example-world-bubble-projection-toggle.md) — so `ixmaps.szResourceBase`
   // only needs to be SOME string, not a real, working resource base URL.
-  // It is the flat release CDN anyway: flat's own tool scripts required by a
-  // page (tooltip_mustache.js) resolve their dependencies through it —
-  // $.getScript(ixmaps.szResourceBase + "ui/js/tools/format.js") — which
-  // with the empty string 404s against the page's own directory
-  const ixmapsSzResourceBase = 'https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-flat@1/';
+  const ixmapsSzResourceBase = '';
   function getProjectString() {
     if (!_lastMapApi || !_lastMapApi.map) return JSON.stringify({ map: {} });
     const map = _lastMapApi.map;
@@ -17174,6 +18016,10 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   function compatRemoveTheme(...a) {
     return _mapHandle.remove(a.length >= 2 ? a[1] : a[0]);
   }
+  // flat's ixmaps.toggleTheme(szMap, szTheme) (htmlgui.js): show / hide a theme by its id, e.g. a page's on / off buttons
+  function compatToggleTheme(...a) {
+    new themeApi(null, a.length >= 2 ? a[1] : a[0]).toggle();
+  }
   function compatSetBasemapOpacity(...a) {
     if (a.length >= 3) {
       const api = (a[0] && _mapApis[a[0]]) || _lastMapApi;
@@ -17209,6 +18055,7 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     htmlgui_getAttributionString: () => (_lastMapApi && _lastMapApi.getAttribution ? _lastMapApi.getAttribution() : ''),
     changeThemeStyle: compatChangeThemeStyle,
     removeTheme: compatRemoveTheme,
+    toggleTheme: compatToggleTheme,
     // flat's ixmaps.setLocalString(orig, local) (htmlgui.js 3814 →
     // Api.setLocalString → Dictionary.replace): a page-wide translation,
     // e.g. the migration page's ISO code → country name; usable before
@@ -17247,19 +18094,19 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
   // 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, applyFlatMaxCharts, youtubeClickToPlay, symbolsFlagCompat, tooltipTable, legendRowLabels, scaleDenom, cssColorAlpha, aggregatedCategoricalClass, dominantDopacityAlpha, isAggregatedCategoricalChoropleth, computeBubblePackLayout, isolatedBubblePackLayout, sequenceLayout, ringsLayout, pieSliceLayout, pieValueLabelLayout, isBarChart, flatBarLayout, flatChartBox, flatValueRules, flatPieRecord, flatPieAccumulate, flatPieItemValues, flatVectorItems, orthographicPlane, vectorArcHeight, pathBackIndex, greatCircleMeters, cameraOptions, bezierVectorLayout, cubicBezierPoints, arrowMarkerTriangle, fadeGradientStops, flatToArray, hashUnit, multiQuadOffsets, pixelOffsetLngLat, chartTextTransmittance, insideSymbolShape,
-    choroplethOutlineColor, normalizeTheme, projectThemeToDefinition, withoutProjectCode, groupRecordCount, resolveBasemapStyleUrl, resolveMapTypeColor, LayerBuilder, LayerRuntime, MapBuilder, typeStyleNumbers, styleNum,
+    IXMAPS_GL_VERSION, applyFlatMaxCharts, youtubeClickToPlay, symbolsFlagCompat, tooltipTable, legendRowLabels, scaleDenom, cssColorAlpha, aggregatedCategoricalClass, dominantDopacityAlpha, isAggregatedCategoricalChoropleth, computeBubblePackLayout, isolatedBubblePackLayout, sequenceLayout, ringsLayout, pieSliceLayout, pieValueLabelLayout, isBarChart, flatBarLayout, flatValueRules, flatPieRecord, flatPieAccumulate, flatPieItemValues, flatVectorItems, orthographicPlane, vectorArcHeight, pathBackIndex, greatCircleMeters, cameraOptions, bezierVectorLayout, cubicBezierPoints, arrowMarkerTriangle, fadeGradientStops, flatToArray, hashUnit, flowDashPhase, multiQuadOffsets, pixelOffsetLngLat, chartTextTransmittance, insideSymbolShape,
+    chartBoxLayout, choroplethOutlineColor, 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,
     resolveComposedColor, computeRangeClasses, colorSchemeClassCount, resolveDopacityAlpha,
     flatColorSweep, applyClassesToColorScheme, resolveClassColors, flatOutlierStats, parseCssColor, flatLegendLook,
     flatToMapLibreZoom, mapLibreToFlatZoom, flatViewToMapLibreZoom, mapLibreToFlatViewZoom, flatSvgProjectionOf, flatSvgProjectionByOptions, normalSizeScaleOf, scaleDenominatorAt, resolveZoomReference, resolveAggregationPx, valuesHiddenByScale,
-    fetchLayerData, parseCsvText, dataTableRows, geometryRowsToFeatureCollection, filterFlatValues, applyField100, field100Binding, rangeClassLegendTotals, resolveAggregateValue, classValueSeparate, cellAggregatedValues, oneHot, groupCoLocated, aggregateOnGrid, GridAggregateIndex, flatRangeParts, explicitRangeBreaks, explicitRangeParts, resolvePartsClass, isNoneColor, aggregateField100, valueRadius, itemPlotGeometry, itemAnchor, objectZoomFactor, resolveZoomReference, defaultNormalSizeValue,
-    applyWhereFilter, joinChartPositions, flatLookupKey, flatShapeCenter, chartHiddenByScale, glowHiddenByScale, isSymbolChart, flatChartAlignOffset, flatChartBranch, flatValueText, categoryValueRecord, flatDerivateRgb, flatBubbleLook, bubbleIconLook, flatChartTextRgb, flatGroupedValue, flatNoBreaks, featuresHiddenByScale, boxHiddenByScale, flatShadowOn, snapToAggregationGrid,
-    drawSymbolPath, normalizeSymbolShape,
+    fetchLayerData, QUERY_HANDOFF, parseCsvText, dataTableRows, geometryRowsToFeatureCollection, filterFlatValues, applyField100, field100Binding, rangeClassLegendTotals, resolveAggregateValue, classValueSeparate, cellAggregatedValues, oneHot, groupCoLocated, aggregateOnGrid, GridAggregateIndex, flatRangeParts, explicitRangeBreaks, explicitRangeParts, resolvePartsClass, isNoneColor, aggregateField100, valueRadius, itemPlotGeometry, itemAnchor, objectZoomFactor, resolveZoomReference, defaultNormalSizeValue,
+    applyWhereFilter, joinChartPositions, joinChoroplethFeatures, flatLookupKey, flatShapeCenter, chartHiddenByScale, glowHiddenByScale, isSymbolChart, flatChartAlignOffset, flatChartBranch, flatValueText, categoryValueRecord, flatDerivateRgb, flatBubbleLook, bubbleIconLook, flatChartTextRgb, flatGroupedValue, flatNoBreaks, featuresHiddenByScale, boxHiddenByScale, flatShadowOn, snapToAggregationGrid,
+    drawSymbolPath, normalizeSymbolShape, bubbleStrokeRgb,
     flatFormatValue, themeStyleArgs, flatChangedStyleValue, explicitValueDecimals, legendDecimals,
-    dataCacheKey, dataCacheDisabled, cachedLayerData, featuresBounds, wantsZoomToExtent, legendIsOn,
+    dataCacheKey, dataCacheDisabled, cachedLayerData, featuresBounds, wantsZoomToExtent, legendIsOn, applySphereBackdrop,
   };
   global.__setFilter = __setFilter;
   global.__removeFacets = __removeFacets;