ixmaps-gl 0.2.31 → 0.2.34

package/README.md

@@ -114,10 +114,10 @@ page. It currently implements:
   `window.__setFacetFilter`) for building filterable sidebars
 - Globe (orthographic) projection alongside flat Mercator
 
-Not yet implemented: plain (non-AGGREGATE) `CATEGORICAL` choropleths, and the `QUAD`/
-`WAFFLE` base types, and SYMBOL shape variants beyond
-circle/square/diamond/triangle. See the top-of-file comment in
-[`ixmaps-gl.js`](./ixmaps-gl.js) for the exact, currently-accurate scope note.
+Not yet implemented: the `QUAD`/`WAFFLE` base types. SYMBOL shapes: the built-in ones and image-URL
+symbols are described under [Symbols](#symbols).
+The top-of-file comment in [`ixmaps-gl.js`](./ixmaps-gl.js) is the single source of truth
+for scope; this list only summarises it.
 
 ### Page scripts, named data and the runtime API
 
@@ -230,6 +230,38 @@ space beside it. `.options({themecopies: true})` (also at runtime) repeats the t
 copy. `.options({worldcopies: false})` draws the world once for the map itself, but MapLibre then
 also stops the zoom-out where the world gets narrower than the window.
 
+### Map events, bounds and the MapLibre map
+
+`map.on("zoomend moveend", fn)` (flat's `mapApi.on`; on the builder chain, the callback object or
+`ixmaps.map()`) fires:
+
+| event | when | handler receives |
+|---|---|---|
+| `ready` | the map has loaded (called at once if it already has) | `{type, szMap}` |
+| `viewchange` (`zoompan`) | after every pan or zoom | `{type, szMap, nZoom, zoomChanged, panChanged}` |
+| `zoomend` / `moveend` | the zoom changed / the centre moved without a zoom change | as `viewchange` |
+| `click` (`itemclick`) | an item was clicked — every item, also of a theme bound by geometry only | `{type, szMap, szId, id, theme, record, lngLat, point}` |
+| `mapclick` | any click on the map, background included (gl addition) | `{type, szMap, lngLat: {lng, lat}, point: {x, y}}` |
+| `layerdraw` (`drawtheme`) | after every redraw, once per theme | `{type, szMap, szId, id}` |
+
+`szId` is `theme::key` and `id` the key: the theme's selection field value (the `id`, position or lookup
+field), else the feature's `id`, else its position `"lng,lat"`; `record` is the item's data record (gl
+addition). `szMap` is the map's `name` option, or `null`. flat's `frozenDynamic` is not provided.
+`map.off("click", fn)` removes a handler, as in flat; several event names may be given, separated by
+spaces, and the names in brackets are flat's aliases.
+
+Differences from flat: `layerdraw` fires for every theme on every redraw, panning included (flat: once per
+theme as it is drawn); `ready` means the MapLibre map has loaded, themes may still be loading; view events
+fire when a movement ends, not during it. The other flat event names (`mouseover`/`itemover`,
+`mouseout`/`itemout`, `resize`, `layeradd`/`newtheme`, `layerremove`/`removetheme`) are accepted but never
+fire; the console says so once. `ixmaps.onItemAction(null, null, {lngLat, point})` gets the click position on
+a background click as a third argument; it is still called for items only when the theme has a selection
+field.
+
+`ixmaps.map().getBounds()` returns flat's `[swLat, swLng, neLat, neLng]` (`ixmaps.getBoundingBox()`
+the same box as `[{lat, lng} SW, {lat, lng} NE]`); `ixmaps.map().getMapLibre()` returns the MapLibre
+map itself, or `undefined` until it is built.
+
 ### Click to action
 
 flat's click-to-action (`ui/js/tools/tooltip_to_action.js`, e.g. a click on a country filters every
@@ -297,12 +329,152 @@ so zoom-dependent page state (e.g. a basemap opacity ramp) changes in step with
 hooks) aren't supported. `test/project-report.mjs` shows which themes
 of your own project files gl can render.
 
+### Symbols
+
+`CHART|SYMBOL` draws one symbol per item (per category with `CATEGORICAL`, per part with `SEQUENCE`).
+`style.symbols` names them, by color class: class `i` (the `i`-th entry of `values`, else the range
+class) takes `symbols[i]`, and the last entry repeats when the array is shorter than the classes.
+
+- **Built-in shapes:** `circle` (default), `square`, `diamond` (= `carot`), `triangle`, `roundrect`,
+  `hexagon`, `cross`, `label`, `empty`. An unknown name draws a circle.
+- **Image symbols:** a URL ending in `.svg`, `.png`, `.jpg` or `.jpeg` (a query or `#` may follow), or a
+  `data:image/svg+xml|png|jpeg` URI. The image is drawn as is, not tinted by the class color. An SVG is
+  fetched and rasterized once per URL (a `viewBox` is enough, it needs no width/height); a PNG/JPEG is
+  loaded by deck.gl. A page opened from `file://` cannot fetch symbol files: serve it over http(s) or use
+  `data:` URIs.
+- **By record field:** `symbolfield: "type"` with `symbolvalues: ["a", "b"]` maps the value of that field
+  to `symbols[i]` by position, independent of the color class (for individual items, not aggregated cells).
+
+```js
+.type("CHART|SYMBOL|CATEGORICAL")
+.style({ values: ["school", "shop"], colorscheme: ["#d9534f", "#428bca"],
+         symbols: ["icons/school.svg", "icons/shop.svg"] })
+```
+
+### Zoom gates: `chartupper` and `chartlower`
+
+`style.chartupper` / `style.chartlower` (`layerupper` / `layerlower` when unset) take a scale `"1:N"`. The
+theme is **hidden when zoomed out beyond `chartupper`** (the scale denominator is above N) and **hidden when
+zoomed in to `chartlower` or closer** (the scale denominator is at or below N). So `chartlower: "1:20000"`
+shows the layer only while the view is zoomed out past 1:20000, and `chartupper: "1:20000"` only from there on
+in. The scale is flat's, about `442913385 / 2^z` for the zoom `z` you give `.view()` on a Mercator map:
+
+| zoom | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 |
+|---|---|---|---|---|---|---|---|---|
+| scale 1: | 432533 | 216266 | 108133 | 54067 | 27033 | 13517 | 6758 | 3379 |
+
+`featureupper`/`featurelower` gate FEATURE themes the same way, `glowupper`/`glowlower` the glow halo.
+
+### Aggregation grid and symbol size
+
+`AGGREGATE` groups items into grid cells. The cell size is read, first match wins, from:
+
+1. `aggregation` (flat's alias `aggregationscale`): scale/width pairs, e.g. `["1:1", "3px", "1:500000", "1px"]`,
+   the width of the last pair for which the view is zoomed out past `1:N` (the example gives 3 px, and 1 px once
+   the view is zoomed out past 1:500000); `"Npx"` is screen pixels, a bare number meters
+2. `gridwidthpx`: screen pixels, constant over zoom (the recommended spelling for a fixed cell)
+3. `gridwidth: "Npx"`: the same, as a string
+4. `gridwidth: N` (a bare number): meters, the same cells at every zoom
+5. none of them: no grid, items stay at their positions
+
+With `CATEGORICAL|COUNT` and no size field the size of a symbol follows the number of records in its cell:
+radius = `15 px × scale × (count / normalsizevalue)^(1/sizepow)`, scaled with the zoom (`objectscaling`) and
+clamped to a minimum and maximum radius.
+`normalsizevalue` is the count drawn at normal size, the dataset's maximum when unset. A `normalsizevalue` of
+`30` therefore draws a single-record cell at 1/30 of the normal radius: pick it near the biggest cell you expect.
+
+### Basemaps (`mapType`)
+
+`mapType` is resolved in this order; a name that matches nothing falls back to the last two rules, so an
+unknown flat name such as `VT_TONER_LITE` draws CARTO Positron:
+
+| `mapType` | style |
+|---|---|
+| `ArcGIS - Topo` (`terrain`), `ArcGIS - Light Gray Base`, `ArcGIS - Ocean Basemap`, `ArcGIS - Hillshade` | Esri raster tiles |
+| `CARTO - Voyager` (`VT_VOYAGER`), `CARTO - Voyager (no labels)` (`VT_VOYAGER_LIGHT`), `CARTO - Positron (no labels)`, `CARTO - Dark Matter (no labels)` | CARTO vector styles |
+| `OpenFreeMap - Liberty`, `OpenFreeMap - Bright`, `OpenFreeMap - Positron` | OpenFreeMap vector styles |
+| any name containing `dark`, `black`, `night` or `matter` | CARTO Dark Matter |
+| everything else | CARTO Positron |
+
+### Adding and replacing themes at runtime
+
+`ixmaps.map().add(theme, "replace")` adds the theme the first time and swaps it on later calls, matched by
+the theme id, `style.name` or `meta.name`. Give the theme a `name` in `.meta()`: the name passed to
+`ixmaps.layer("name", …)` is not the id, and without one `"replace"` cannot find the old theme and adds a second. `ixmaps.map().remove(id)` removes it.
+
+### Text on labels
+
+`CHART|LABEL` (with `TEXTONLY` for the text alone) writes the item's value. A text field bound as the *value*
+reads as 0, as in flat, and shows nothing visible; the console says so once. To show a text, as in flat, keep a
+numeric `value` (or `size`) binding and name the text field in `style.valuefield`, or `"$title$"` for the
+`title` binding:
+
+```js
+.binding({ geo: "geometry", value: "count" })
+.type("CHART|LABEL|TEXTONLY|VALUES")
+.style({ valuefield: "name" })
+```
+
+With `CATEGORICAL` the value field holds the categories and `valuefield` names the text. The text is drawn as a
+single-color glyph with a halo, so an emoji comes out as a monochrome silhouette (seen in a headless Chromium
+test): use image symbols (see Symbols) for colored icons.
+
+### Runtime filtering
+
+A theme's records can be filtered in place, without redefining it, with flat's `changeThemeStyle`:
+
+```js
+ixmaps.changeThemeStyle("mytheme", 'filter:WHERE "type" = "school"', "set");
+ixmaps.changeThemeStyle("mytheme", "filter", "remove");
+```
+
+The same through the handles, `ixmaps.map().changeThemeStyle(id, style, flag)` and
+`ixmaps.map().theme(id).changeStyle(style, flag)`; with `null` as the id every theme but the FEATURE ones is
+changed. The expression is flat's filter grammar: `WHERE field op value` clauses joined by `AND` with `=`, `!=`,
+`<>`, `<`, `>`, `<=`, `>=`, `BETWEEN … AND …`, `IN (…)`, `LIKE` and `NOT` (see `test/unit/filter.test.mjs`).
+(`npm run runtime` in `test/` checks these calls in a browser.)
+
+### Porting a flat page
+
+How the calls of a flat page map to gl; "tested" means `test/runtime.mjs` runs it in a browser.
+
+| flat | gl |
+|---|---|
+| `ixmaps.Map(div, opts, function (map) { … })` | the same; the callback gets the map builder (`view`, `options`, `layer`, `on`, …) |
+| `var myMap = ixmaps.Map(div, opts).view(…)`, `myMap.then(map => …)` | the same, `myMap` is the builder and a thenable |
+| `myMap.layer("name").data(…)…define()` | the same, before and after the map is built (tested) |
+| `myMap.layer(theme)`, `myMap.layer(theme, "direct")` after the map is built | the same (tested); up to v0.2.33 these silently added nothing |
+| `ixmaps.map().layer(theme)`, `ixmaps.map().add(theme, "replace")` | the same (tested) |
+| `ixmaps.changeThemeStyle(id, 'filter:…', "set")` | the same (tested), see Runtime filtering |
+| `map.getBounds()` | `ixmaps.map().getBounds()`, from v0.2.33 |
+| `map.on(event, fn)` | `map.on` / `map.off`, see Map events |
+| `ixmaps.hideTheme(id)` / `ixmaps.showTheme(id)` | not provided: `ixmaps.map().theme(id).hide()` / `.show()` or `ixmaps.map().setThemeVisible(id, bool)` |
+| `ixmaps.flyTo(…)` | not provided: `ixmaps.map().view([lat, lng], zoom)` |
+
+### `CHART|USER` draw function
+
+`style.userdraw` names a function (`ixmaps[name]`, or a dotted path on `window`). It is called as
+`fn(document, opt)` for each chart, after an optional `name_init(document, {target, theme})` once per draw.
+`opt` holds `target` (the SVG group to draw into), `theme`, `value`, `values`, `size`, `maxSize`, `color`,
+`class`, `flag`, `ccolor`, `item` (`{szColor, szLabel, szTitle, nCount, nSize}`) and `dbRecord` (the item's data
+record, also the place to read the category). `size` is in flat's chart units, `maxSize` (300) being the
+normal radius: one unit is `15 px × scale × zoom factor / 300`. The chart is drawn around 0,0.
+
+### Headless, CI and offline
+
+A headless Chromium has no GPU: start it with `--use-gl=swiftshader --enable-unsafe-swiftshader
+--ignore-gpu-blocklist`. deck.gl then logs "GPU stall due to ReadPixels", which is harmless. The engine loads
+`maplibre-gl@6.11.2` (module and css) and `deck.gl@9.4.0` and `mustache@4.2.0` from unpkg, `data.js` from
+jsDelivr (`gh/gjrichter/data.js`), and on demand `d3-array@3.2.4` and `d3-contour@4.0.2` (jsDelivr) and the
+`ixmaps-grammar` validator; mirror these to run offline. Page-level script and data URLs are not
+configurable yet.
+
 ## Quick start
 
 Load the engine from jsDelivr, pinned to a release tag (or `@main` for the latest commit):
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.31/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.34/ixmaps-gl.js"></script>
 ```
 
 or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmaps-gl)
@@ -310,13 +482,13 @@ or from unpkg, the npm package [`ixmaps-gl`](https://www.npmjs.com/package/ixmap
 browser script, which defines the global `ixmaps`):
 
 ```html
-<script src="https://unpkg.com/ixmaps-gl@0.2.31/ixmaps-gl.js"></script>
+<script src="https://unpkg.com/ixmaps-gl@0.2.34/ixmaps-gl.js"></script>
 ```
 
 or use a local copy (`<script src="ixmaps-gl.js"></script>`). A minimal page:
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.31/ixmaps-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-gl@v0.2.34/ixmaps-gl.js"></script>
 <div id="map_div" style="position:absolute;inset:0;"></div>
 
 <script>

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.31';
+  const IXMAPS_GL_VERSION = '0.2.34';
 
   const LIB_URLS = {
     // Bumped 3.6.2 -> 5.x (2026-09-21, globe-projection compat fix): native
@@ -614,6 +614,19 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
         [...document.styleSheets].some(s => s.href === LIB_URLS.maplibreCss) ? Promise.resolve() : loadStylesheet(LIB_URLS.maplibreCss)
       ]).then(() => {
         ({ IconLayer, ScatterplotLayer, GeoJsonLayer, MapLibreOverlay, TextLayer, PathLayer, PathStyleExtension, HeatmapLayer } = global.deck);
+        // deck.gl 9 gamma-encodes the layer-level `opacity` prop in its `layer` shader module
+        // (Math.pow(opacity, 1/2.2); deck 8 and flat's SVG fill-opacity are linear), so a declared
+        // fillopacity 0.2 would draw as 0.48. Hand deck opacity ** 2.2: it draws exactly the declared alpha.
+        // Alpha inside a color array (getFillColor [r,g,b,a]) is linear and stays as it is.
+        const linearOpacity = Cls => new Proxy(Cls, {
+          construct(target, args, newTarget) {
+            const fixed = args.map(p => (p && typeof p === 'object' && typeof p.opacity === 'number' && p.opacity >= 0 && p.opacity < 1)
+              ? Object.assign({}, p, { opacity: Math.pow(p.opacity, 2.2) }) : p);
+            return Reflect.construct(target, fixed, newTarget);
+          }
+        });
+        [IconLayer, ScatterplotLayer, GeoJsonLayer, TextLayer, PathLayer, HeatmapLayer] =
+          [IconLayer, ScatterplotLayer, GeoJsonLayer, TextLayer, PathLayer, HeatmapLayer].map(linearOpacity);
         PieSliceLayer = makePieSliceLayer(ScatterplotLayer);
         BarShapeLayer = makeBarShapeLayer(ScatterplotLayer);
         FlowPathLayer = makeFlowPathLayer(PathLayer);
@@ -1861,12 +1874,31 @@ float barSegDist(vec2 p, vec2 a, vec2 b) {
     })(g && g.coordinates);
     return minX <= maxX ? [(minX + maxX) / 2, (minY + maxY) / 2] : null;
   }
+  // flat finds a geometry id field whatever its letter case (the comuni topojson has "pro_com_t", the page
+  // binds id "pro_com_T"): the property name of a FEATURE runtime's shapes that matches the binding, else
+  // the binding as written. Cached per runtime and name
+  function geometryIdField(rt, name) {
+    if (!name || !rt) return name;
+    const cache = rt._idFieldCache || (rt._idFieldCache = {});
+    if (cache[name] !== undefined) return cache[name];
+    const feats = rt.features || [];
+    let found = name;
+    const has = f => f.properties && Object.prototype.hasOwnProperty.call(f.properties, name);
+    if (!feats.slice(0, 50).some(has)) {
+      const low = String(name).toLowerCase();
+      for (const f of feats.slice(0, 50)) {
+        const k = f.properties && Object.keys(f.properties).find(key => key.toLowerCase() === low);
+        if (k) { found = k; break; }
+      }
+    }
+    return (cache[name] = found);
+  }
   // id → position of one FEATURE runtime's shapes (flat's getNodePosition,
   // maptheme.js 24702-24784): its shape (flatShapeWins) at flat's shape
   // center (flatShapeCenter)
   function featurePositionIndex(rt) {
     if (rt._positionIndex && rt._positionIndexOf === rt.features) return rt._positionIndex;
-    const idField = rt.binding && rt.binding.id;
+    const idField = geometryIdField(rt, rt.binding && rt.binding.id);
     const best = new Map();
     if (idField) {
       for (const f of rt.features) {
@@ -2450,7 +2482,7 @@ self.onmessage = e => {
     // the donor's own style (outline) — the layer registry is keyed by name,
     // so the same-named CHOROPLETH replaces the donor there and can't find it
     Object.defineProperty(spec, '_donorStyle', { value: geomRt.style, configurable: true });
-    const idField = geomRt.binding.id;
+    const idField = geometryIdField(geomRt, geomRt.binding.id);
     const lookupField = spec.binding.lookup;
     if (!idField || !lookupField) {
       throw new Error(`[ixmaps-gl] CHOROPLETH layer "${spec.name}" needs .binding({lookup}), and its FEATURE base needs .binding({id})`);
@@ -3174,6 +3206,13 @@ self.onmessage = e => {
       if (this._filterExpr != null) style.filter = this._filterExpr;
       if (this._titleField != null) style.title = this._titleField;
       if (this._lookupfield != null) style.lookupfield = this._lookupfield;
+      // flat's .data() (htmlgui_flat.js ~1827): a geojson/topojson layer with no type of its own is
+      // a FEATURES base layer ("FEATURES|NOLEGEND", lookup on its geometry) — the base a CHOROPLETH
+      // of the same name needs. Only when neither .type() nor style.type says otherwise
+      if (!style.type && this._data && /geojson|topojson/i.test(String(this._data.type || ''))) {
+        style.type = 'FEATURES|NOLEGEND';
+        if (style.lookupfield == null) style.lookupfield = 'geometry';
+      }
       let data = this._data;
       if (this._query != null || this._process != null) {
         data = Object.assign({}, this._data);
@@ -3237,7 +3276,7 @@ self.onmessage = e => {
   // edit it by hand; `npm run unit` fails when it drifts.
   // ---------------------------------------------------------------
   // <grammar:binding-aliases>
-  // generated from ixmaps-grammar 0.1.29 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
+  // generated from ixmaps-grammar 0.1.30 (ixmaps-flat 1.0.42, 2b978d5 2026-10-02) — 52 aliases
   const FLAT_BINDING_ALIASES = {
     "aggregation": "style.aggregationfield",
     "aggregationfield": "style.aggregationfield",
@@ -3299,7 +3338,7 @@ self.onmessage = e => {
   // both — so .style({tooltip}) is a tooltip and .meta({fillopacity}) a style
   // property. GENERATED by test/sync-grammar.mjs — do not edit.
   // <grammar:meta-keys>
-  // generated from ixmaps-grammar 0.1.29 — 5 meta keys
+  // generated from ixmaps-grammar 0.1.30 — 5 meta keys
   const FLAT_META_KEYS = ["description","name","snippet","title","tooltip"];
   // </grammar:meta-keys>
 
@@ -3541,7 +3580,7 @@ self.onmessage = e => {
     'shadowblur', 'shadowdx', 'shadowdy', 'maxshadow', 'offsetx', 'offsety', 'gridx', 'boxmargin', 'borderwidth',
     'borderradius', 'maxcharts', 'archeight', 'alignmargin',
     // HEATMAP / MLHEATMAP / KDE (a project JSON writes them as strings)
-    'radiuspx', 'intensity', 'threshold', 'weightmax', 'bandwidth'];
+    'radiuspx', 'intensity', 'threshold', 'weightmax', 'bandwidth', 'bandwidthscale', 'bandwidthzoompow', 'bandwidthzoomref'];
   function toNumberIfNumeric(v) {
     if (typeof v !== 'string' || !v.trim()) return v;
     const n = Number(v);
@@ -3925,9 +3964,23 @@ self.onmessage = e => {
       if (t === entry.name || (entry.aliases || []).includes(t)) return entry;
     }
   }
+  // keyless vector styles by NAME (exact match, before the dark/light rule): flat's own VT_VOYAGER names
+  // resolve to the CARTO Voyager style they are made from; the rest are further keyless MapLibre styles
+  const KEYLESS_VECTOR_BASEMAPS = [
+    { name: 'CARTO - Voyager', aliases: ['VT_VOYAGER'], url: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json' },
+    { name: 'CARTO - Voyager (no labels)', aliases: ['VT_VOYAGER_LIGHT'], url: 'https://basemaps.cartocdn.com/gl/voyager-nolabels-gl-style/style.json' },
+    { name: 'CARTO - Positron (no labels)', url: 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json' },
+    { name: 'CARTO - Dark Matter (no labels)', url: 'https://basemaps.cartocdn.com/gl/dark-matter-nolabels-gl-style/style.json' },
+    { name: 'OpenFreeMap - Liberty', url: 'https://tiles.openfreemap.org/styles/liberty' },
+    { name: 'OpenFreeMap - Bright', url: 'https://tiles.openfreemap.org/styles/bright' },
+    { name: 'OpenFreeMap - Positron', url: 'https://tiles.openfreemap.org/styles/positron' },
+  ];
   function resolveBasemapStyleUrl(mapType) {
     const raster = flatRasterBasemap(mapType);
     if (raster) return buildRasterBasemapStyle(raster);
+    const typeName = typeof mapType === 'string' ? mapType.trim() : '';
+    const vector = KEYLESS_VECTOR_BASEMAPS.find(e => e.name === typeName || (e.aliases || []).includes(typeName));
+    if (vector) return vector.url;
     return typeof mapType === 'string' && /dark|black|night|matter/i.test(mapType) ? BASEMAP_STYLE_URLS.dark : BASEMAP_STYLE_URLS.light;
   }
   // Real ixmaps-flat's legend look (tools/legend.js 3773-3845, via
@@ -4414,18 +4467,34 @@ self.onmessage = e => {
     }
     // 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) {
+    // on a click on the map background — gl adds the click position as third argument there:
+    // onItemAction(null, null, { lngLat: {lng, lat}, point: {x, y} }) (flat passes none)
+    function clickPosition(info) {
+      const c = info && info.coordinate;
+      if (!c || !isFinite(c[0]) || !isFinite(c[1])) return undefined;
+      return { lngLat: { lng: c[0], lat: c[1] }, point: { x: info.x, y: info.y } };
+    }
+    function callItemAction(rt, object, info) {
       const hook = pageIxmaps() && pageIxmaps().onItemAction;
-      if (typeof hook !== 'function') return;
       try {
-        if (!rt) { hook.call(global.ixmaps, null, null); return; }
+        const pos = clickPosition(info);
+        if (!rt) { if (typeof hook === 'function') hook.call(global.ixmaps, null, null, pos); 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;
+        // the map's "click" event, for EVERY item as in flat (szId = theme::itemKey): the key is the selection
+        // field's value, else the feature's id, else its position "lng,lat" — a theme bound by geometry only
+        // (no id/lookup field) has no selection value. gl adds the record and the click position.
+        if (builder.__emitItemClick) {
+          const g = object.geometry, a = anchorCoordOf(g) || (g && Array.isArray(g.coordinates) && g.coordinates[0]);
+          const key = value != null ? String(value)
+            : (object.id != null ? String(object.id) : (a && typeof a[0] === 'number' ? a[0] + ',' + a[1] : ''));
+          builder.__emitItemClick(Object.assign({ szId: themeIdOf(rt) + '::' + key, id: key, theme: themeIdOf(rt), record: raw }, pos));
+        }
+        // flat's onItemAction needs the theme's selection value
+        if (value == null || typeof hook !== 'function') return;
         hook.call(global.ixmaps, themeIdOf(rt) + '::' + value, { szSelectionId: String(value) }, getThemeObj(themeIdOf(rt)));
       } catch (err) { console.error('[ixmaps-gl] onItemAction failed:', err); }
     }
@@ -4434,7 +4503,7 @@ self.onmessage = e => {
         if (info && info.object && info.layer) {
           const rt = findRuntimeForLayerId(info.layer.id);
           if (rt) {
-            callItemAction(rt, info.object);
+            callItemAction(rt, info.object, info);
             // 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
@@ -4465,7 +4534,7 @@ self.onmessage = e => {
           }
         }
         // clicked empty map space (or a non-tooltippable layer) -> unpin
-        callItemAction(null, null);
+        callItemAction(null, null, picked);
         pinned = null;
         pinnedTooltipEl.style.display = 'none';
         return false;
@@ -5472,6 +5541,23 @@ self.onmessage = e => {
     return { addLegendPanel, setLegendOption, updateSubTheme, layoutLegends };
   }
 
+  // flat's map event names (htmlgui_flat.js mapApi.on, with its aliases) and the ones this engine fires:
+  //  viewchange (every view change end), zoomend / moveend ({ nZoom, zoomChanged, panChanged }, as flat),
+  //  ready (the map has loaded), click (an item: { szId, id, theme } + lngLat/point), layerdraw ({ id }) and,
+  //  as a gl addition, mapclick (every click on the map, background included: { lngLat, point })
+  const MAP_EVENT_ALIAS = { zoompan: 'viewchange', itemover: 'mouseover', itemclick: 'click', itemout: 'mouseout', mapready: 'ready',
+    drawtheme: 'layerdraw', newtheme: 'layeradd', removetheme: 'layerremove' };
+  const MAP_EVENTS_WIRED = new Set(['viewchange', 'zoomend', 'moveend', 'ready', 'click', 'mapclick', 'layerdraw']);
+  function splitMapEvents(events) {
+    return String(events == null ? '' : events).trim().toLowerCase().split(/\s+/).filter(Boolean).map(e => MAP_EVENT_ALIAS[e] || e);
+  }
+  const _warnedMapEvents = new Set();
+  function warnUnwiredMapEvent(ev) {
+    if (MAP_EVENTS_WIRED.has(ev) || _warnedMapEvents.has(ev)) return;
+    _warnedMapEvents.add(ev);
+    console.warn(`[ixmaps-gl] map event "${ev}" is not implemented — the handler is accepted but never fires (supported: ${[...MAP_EVENTS_WIRED].join(', ')})`);
+  }
+
   class MapBuilder {
     constructor(containerId, options) {
       this.containerId = containerId;
@@ -5536,15 +5622,21 @@ self.onmessage = e => {
     }
     // .Layer() — alias of .layer()
     Layer(nameOrBuilder) { return this.layer(nameOrBuilder); }
-    // GL-PORT COMPAT: real ixmaps-flat's map.on("layerdraw", cb) — only
-    // "layerdraw" is actually wired up (see build()'s own note on how
-    // it's translated into onRedraw + a synthetic per-runtime event); any
-    // OTHER event name is accepted and stored but never fired —
-    // recognized rather than throwing, the same "known but inert" pattern
-    // KNOWN_INERT_FLAGS already uses for unimplemented type flags.
+    // flat's mapApi.on(events, cb) (htmlgui_flat.js 1631), "a b" for several names; see MAP_EVENTS for the
+    // ones wired here. Any other name is accepted (never throws) but never fires, and says so once on the console.
+    // Registered before the map is built, they are attached by build().
     on(event, cb) {
       this._pendingEvents = this._pendingEvents || [];
-      this._pendingEvents.push([event, cb]);
+      for (const ev of splitMapEvents(event)) {
+        warnUnwiredMapEvent(ev);
+        this._pendingEvents.push([ev, cb]);
+      }
+      return this;
+    }
+    // flat's mapApi.off(events, cb), before the map is built (after it: the handle's off)
+    off(event, cb) {
+      const names = new Set(splitMapEvents(event));
+      this._pendingEvents = (this._pendingEvents || []).filter(([ev, f]) => !(names.has(ev) && f === cb));
       return this;
     }
 
@@ -5966,20 +6058,29 @@ self.onmessage = e => {
       map.on('style.load', refreshControlLook);
       this._setAttribution = text => attributionBox.set(text);
 
-      if (this._legendHtml) {
+      // the page legend (map.legend(html)), or the legend a loaded project
+      // carries in its map part (applyProjectMap) — flat shows the project's
+      // legend in the same pane, so the project's replaces the page's
+      let pageLegendEl = null;
+      const showPageLegend = html => {
+        if (pageLegendEl) { pageLegendEl.remove(); pageLegendEl = null; }
+        this._legendHtml = html;
+        if (!html) return;
         const legendEl = document.createElement('div');
         // 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';
         // 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(() => {});
+        if (/<[a-z!]/i.test(html)) legendEl.innerHTML = html;
+        else fetch(html).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);
         el.appendChild(legendEl);
-      }
+        pageLegendEl = legendEl;
+      };
+      if (this._legendHtml) showPageLegend(this._legendHtml);
 
       // themes are addressed by either the layer()'s own name (e.g. "AREU")
       // or style.name (e.g. "chart") — the real engine's changeThemeStyle
@@ -6865,6 +6966,12 @@ self.onmessage = e => {
           Object.assign(builder._engineOptions, o);
         }
         if (m.scaleParam && m.scaleParam.normalSizeScale != null) builder._engineOptions.normalSizeScale = m.scaleParam.normalSizeScale;
+        // the project's own legend (map.legend: html or a URL to it) replaces the page's, as in flat;
+        // like a page legend it takes the place of the theme-generated legend panels
+        if (typeof m.legend === 'string' && m.legend.trim()) {
+          showPageLegend(m.legend);
+          setLegendOption(builder.mapOptions.legend);
+        }
         if (m.basemap) report.notes.push(`basemap "${m.basemap}" not switched (ixmaps-gl keeps the map's own basemap)`);
       }
 
@@ -7208,8 +7315,61 @@ self.onmessage = e => {
       }
       map.on('moveend', loadDeferredThemes);
 
+      // map events (flat's mapApi.on): see MAP_EVENTS_WIRED. "layerdraw" is approximated below.
+      const mapListeners = Object.create(null);
+      const drawHooks = new Map();      // layerdraw handler -> its onRedraw unsubscribe functions
+      const mapName = (this.mapOptions && this.mapOptions.name) || null;   // flat's szMap
+      let mapReady = false;
+      const emitMapEvent = (type, detail) => (mapListeners[type] || []).slice().forEach(cb => {
+        try { cb(Object.assign({ type, szMap: mapName }, detail)); } catch (err) { console.error(`[ixmaps-gl] "${type}" callback failed:`, err); }
+      });
+      engineApi.on = (events, cb) => {
+        if (typeof cb !== 'function') return engineApi;
+        for (const ev of splitMapEvents(events)) {
+          warnUnwiredMapEvent(ev);
+          if (ev === 'layerdraw') {
+            // flat fires "layerdraw" once per theme as it finishes drawing; here onRedraw fires once per refresh of
+            // the whole map, so the callback is called once per current theme every time — a page that re-reads
+            // that theme's state (getThemeObj/getFacets) gets fresh numbers after every redraw
+            const off = engineApi.onRedraw(() => runtimes.forEach(rt => {
+              const id = themeIdOf(rt);
+              try { cb({ type: 'layerdraw', szId: id, id, szMap: mapName }); } catch (err) { console.error('[ixmaps-gl] "layerdraw" callback failed:', err); }
+            }));
+            drawHooks.set(cb, (drawHooks.get(cb) || []).concat(off));
+          } else {
+            (mapListeners[ev] = mapListeners[ev] || []).push(cb);
+            if (ev === 'ready' && mapReady) setTimeout(() => { try { cb({ type: 'ready', szMap: mapName }); } catch (err) { console.error('[ixmaps-gl] "ready" callback failed:', err); } }, 0);
+          }
+        }
+        return engineApi;
+      };
+      // flat's mapApi.off(events, cb): removes the handler(s) given to on()
+      engineApi.off = (events, cb) => {
+        if (typeof cb !== 'function') return engineApi;
+        for (const ev of splitMapEvents(events)) {
+          if (ev === 'layerdraw') { (drawHooks.get(cb) || []).forEach(off => off()); drawHooks.delete(cb); continue; }
+          const list = mapListeners[ev];
+          if (list) mapListeners[ev] = list.filter(f => f !== cb);
+        }
+        return engineApi;
+      };
+      let lastViewZoom = map.getZoom(), lastViewCenter = map.getCenter();
+      map.on('moveend', () => {
+        const z = map.getZoom(), c = map.getCenter();
+        const zoomChanged = z !== lastViewZoom, panChanged = c.lng !== lastViewCenter.lng || c.lat !== lastViewCenter.lat;
+        lastViewZoom = z; lastViewCenter = c;
+        const detail = { nZoom: flatViewZoomOf(map), zoomChanged, panChanged };
+        emitMapEvent('viewchange', detail);
+        if (zoomChanged) emitMapEvent('zoomend', detail);
+        if (panChanged && !zoomChanged) emitMapEvent('moveend', detail);
+      });
+      map.on('click', e => emitMapEvent('mapclick', { lngLat: { lng: e.lngLat.lng, lat: e.lngLat.lat }, point: { x: e.point.x, y: e.point.y } }));
+      this.__emitItemClick = detail => emitMapEvent('click', detail);
+
       map.on('load', () => {
         mapHasLoaded = true;
+        mapReady = true;
+        emitMapEvent('ready');
         loadDeferredThemes();
         refresh();
         runtimes.forEach(maybeZoomToTheme);
@@ -7275,18 +7435,7 @@ self.onmessage = e => {
       // gets the same practical effect: fresh numbers after every redraw,
       // for every theme, without needing the page rewritten around a
       // finer-grained event this engine doesn't produce.
-      const layerdrawCbs = (this._pendingEvents || [])
-        .filter(([event]) => event === 'layerdraw')
-        .map(([, cb]) => cb);
-      if (layerdrawCbs.length) {
-        engineApi.onRedraw(() => {
-          runtimes.forEach(rt => {
-            layerdrawCbs.forEach(cb => {
-              try { cb({ id: rt.name }); } catch (err) { console.error('[ixmaps-gl] "layerdraw" callback failed:', err); }
-            });
-          });
-        });
-      }
+      (this._pendingEvents || []).forEach(([event, cb]) => engineApi.on(event, cb));
 
       // the native legend: createLegend (its four hooks are what the rest
       // of the map calls — panels, the legend option, sub-themes, layout)
@@ -7470,13 +7619,21 @@ self.onmessage = e => {
       promise.legend = (...args) => { builder.legend(...args); return promise; };
       promise.local = (...args) => { builder.local(...args); return promise; };
       promise.require = (url) => { if (resolvedApi) resolvedApi.require(url); else builder.require(url); return promise; };
-      promise.on = (...args) => { builder.on(...args); return promise; };
+      promise.on = (...args) => { if (resolvedApi) resolvedApi.on(...args); else builder.on(...args); return promise; };
+      promise.off = (...args) => { if (resolvedApi) resolvedApi.off(...args); else builder.off(...args); return promise; };
+      promise.getBounds = () => getBounds();
+      promise.getMapLibre = () => (resolvedApi ? resolvedApi.map : undefined);
       promise.layer = (nameOrBuilder) => {
         if (typeof nameOrBuilder !== 'string') {
           // object form (a pre-built LayerBuilder, e.g. from the global
           // ixmaps.layer(name, cb) factory): existing semantics, chain
           // back on the MAP for further .layer(a).layer(b) calls.
-          builder.layer(nameOrBuilder);
+          // Once the map is built build() has consumed its queue, so queuing
+          // here would add nothing, silently: define the theme on the live
+          // map instead (flat's runtime overlay: myMap.layer(theme, "direct"),
+          // the second argument is accepted and not needed)
+          if (resolvedApi) resolvedApi.layer(nameOrBuilder);
+          else builder.layer(nameOrBuilder);
           return promise;
         }
         const lb = new LayerBuilder(nameOrBuilder);
@@ -11913,7 +12070,19 @@ self.onmessage = e => {
     // flat's nValueSum is the RAW weighted sum, whatever the flags.
     // (RELATIVE/INVERT subtract after the multiply — not reconstructable
     // from the parts; flat's own composed branch never pairs them.)
-    _composedDopacityAlpha(props) {
+    // With binding.alpha the opacity follows the alpha field instead of the value sum — flat's
+    // `if (this.szAlphaField)` branch of the same DOPACITY block (maptheme.js 13476-13482):
+    // dopacityscale / nAlphaMax^(1/pow) · nAlpha^(1/pow), nAlpha as _prepareAlphaField made it
+    // (alpha100 "$density$": alpha / the shape's area, the FEATURE base's size field when it binds one);
+    // a shape with no alpha is 0. Not capped at 0.9 and not times fillopacity, as flat
+    _composedDopacityAlpha(props, feature) {
+      if (this.binding && this.binding.alpha) {
+        const nAlpha = this._alphaByFeature && feature ? this._alphaByFeature.get(feature) : undefined;
+        if (nAlpha == null) return 0;
+        const pow = 1 / (styleNum(this.style.dopacitypow) || 1);
+        const o = (styleNum(this.style.dopacityscale) || 1) / Math.pow(this._alphaMax || 1, pow) * Math.pow(nAlpha, pow);
+        return isFinite(o) ? Math.max(0, Math.min(1, o)) : 0;
+      }
       const fields = this._multiFields || [];
       const f100A = this.binding && this.binding.field100 ? String(this.binding.field100).split('|') : null;
       const multiplier = this.flags.has('FRACTION') ? (styleNum(this.style.fractionscale) || 1)
@@ -12932,7 +13101,10 @@ self.onmessage = e => {
         const labels = this.categoryDisplayLabels || this.categoryLabels || [];
         return tooltipTable(props.parts.map((v, i) => (v > 0 ? { rgb: this.categoryColorsRgb[i], label: labels[i] || '(n/d)', value: this._formatTooltipValue(v) + unitOf } : null)).filter(Boolean));
       }
-      if (this.flags.has('CHOROPLETH') && (this.flags.has('DOMINANT') || this.flags.has('COMPOSECOLOR')) && props.raw) {
+      // (a USER chart over several value fields — the pinnacle peaks of a COMPOSECOLOR theme — lists its fields
+      // the same way: its single item row would show the first class with the size total)
+      const multiFieldUser = this.flags.has('USER') && String(this.binding.value || '').includes('|');
+      if ((this.flags.has('CHOROPLETH') || multiFieldUser) && (this.flags.has('DOMINANT') || this.flags.has('COMPOSECOLOR')) && props.raw) {
         return this._renderMultiFieldBarsHtml(props.raw);
       }
       const unit = unitOf;
@@ -13148,7 +13320,7 @@ self.onmessage = e => {
       // early return here must also unmount its groups, or the pane keeps
       // showing the last drawing after the theme went out of scale (or was
       // hidden via setThemeVisible)
-      if (this._hidden) { this._clearUserChartPane(); return []; }
+      if (this._hidden) { this._kdeShowGate = true; this._clearUserChartPane(); return []; }
       if (!this.flags.has('FEATURE') && !this.flags.has('FEATURES') && chartHiddenByScale(this.style, liveZoom)) { this._clearUserChartPane(); return []; }
       // DOT is checked FIRST, matching the real engine's own precedence
       // (its DOT branch is a loop-level fast-path that bypasses the whole
@@ -13451,7 +13623,7 @@ self.onmessage = e => {
                 // sum over (field100/100), against the same nMax the color
                 // blend normalizes by. The raw weighted sum is reconstructed
                 // from the fractioned part values (raw = part × its field100)
-                dopacityAlpha: dopacityActive ? this._composedDopacityAlpha(f.properties) : null
+                dopacityAlpha: dopacityActive ? this._composedDopacityAlpha(f.properties, f) : null
               }
             };
           }
@@ -14468,8 +14640,9 @@ self.onmessage = e => {
           // 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));
+          else if (chart.defsById && chart.defsById[id]) paneDefs.insertAdjacentHTML('beforeend', chart.defsById[id]);
         }
-        items.push({ d, coords: d.geometry.coordinates, ox: chart.ox, oy: chart.oy, s: pxPerUnit,
+        items.push({ d, coords: d.geometry.coordinates, ox: chart.ox, oy: chart.oy, s: pxPerUnit, pick: chart.pick,
           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
@@ -14512,14 +14685,31 @@ self.onmessage = e => {
         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({
+      // each chart answers to its own outline: the polygons sampled from its drawing (else its box), in px
+      // around the map position, here as lng/lat at this zoom (a px is 360/(512·2^z) degrees across,
+      // times cos(lat) up); a few px of transparent stroke keep a thin peak easy to hit
+      const degPerPx = 360 / (512 * Math.pow(2, liveZoom));
+      const pickFeatures = items.map(it => {
+        const [lng, lat] = it.coords;
+        const kx = it.s * degPerPx, ky = it.s * degPerPx * Math.cos(lat * Math.PI / 180);
+        const rings = it.pick && it.pick.length ? it.pick
+          : [[[it.ext[0] / it.s, it.ext[1] / it.s], [it.ext[2] / it.s, it.ext[1] / it.s], [it.ext[2] / it.s, it.ext[3] / it.s], [it.ext[0] / it.s, it.ext[3] / it.s]]];
+        const polys = rings.map(r => {
+          const ring = r.map(([x, y]) => [lng + x * kx, lat - y * ky]);
+          ring.push(ring[0]);
+          return [ring];
+        });
+        // icon + d: what pickedFeature unwraps to the item
+        return { type: 'Feature', geometry: { type: 'MultiPolygon', coordinates: polys }, properties: {}, icon: true, d: it.d };
+      });
+      this._userChartLastLayers = [...boxLayers.box, new GeoJsonLayer({
         id: `ix-bubbles-${this.name}`,
-        data: items.map(it => ({ d: it.d, icon: true, r: it.r })),
+        data: { type: 'FeatureCollection', features: pickFeatures },
         pickable: true,
-        getPosition: e => e.d.geometry.coordinates,
-        getRadius: e => Math.max(2, e.r),
-        radiusUnits: 'pixels', radiusMinPixels: 1,
-        stroked: false, filled: true, getFillColor: [0, 0, 0, 0],
+        filled: true, stroked: true,
+        // alpha 1/255: invisible, but never a fully transparent fragment a renderer might skip
+        getFillColor: [0, 0, 0, 1], getLineColor: [0, 0, 0, 1],
+        lineWidthUnits: 'pixels', getLineWidth: 4,
         parameters: ICON_LAYER_GLOBE_PARAMETERS
       }), ...boxLayers.titles];
       return this._userChartLastLayers;
@@ -14532,11 +14722,40 @@ self.onmessage = e => {
       const raw = d.properties.raw || d.properties;
       const titleField = this.style.titlefield || this.binding.title;
       const title = titleField && raw && raw[titleField] != null ? String(raw[titleField]) : undefined;
-      const base = `user|${name}|${cat}|${Math.round(value * 100) / 100}|${Math.round(size * 2) / 2}|${flag}|${title || ''}`;
+      // flat hands the chart the item's value fields: values = every field of binding.value (after the
+      // field100 arithmetic — the record already carries it) and value = the first of them
+      // (maptheme.js 19667, nValuesA[0]); a theme with one value field keeps the item's value
+      let values = [value];
+      const fieldNames = this.binding.value && !d.properties.counts ? String(this.binding.value).split('|') : [];
+      if (fieldNames.length > 1) {
+        const parts = fieldNames.map(f => scanValue(raw && raw[f[0] === '!' ? f.slice(1) : f]));
+        if (parts.some(v => !isNaN(v))) {
+          values = parts.map(v => (isNaN(v) ? 0 : v));
+          // COMPOSECOLOR blends all the fields into one colour, so the chart's value is the one that wins it —
+          // the highest field (flat itself would hand over the first field here: a deliberate departure,
+          // so a "party with the highest result" map prints that party's share)
+          value = this.flags.has('COMPOSECOLOR') ? Math.max(...values) : values[0];
+        }
+      }
+      // DOMINANT: the chart is the dominant field's — its class colour and its value (flat's USER branch,
+      // maptheme.js ~19700-19770: nClass = the dominant index, nValue = nValuesA[nIndex]); the relevance
+      // (plain value, PERCENTOFMEAN, DEVIATION) is the one the DOMINANT choropleth uses
+      if (this.flags.has('DOMINANT') && !this.flags.has('COMPOSECOLOR') && this._multiFields && this._dominantMins && raw && fieldNames.length > 1) {
+        const dominant = this._resolveDominantClass(raw);
+        if (dominant) { value = dominant.value; cat = dominant.index; }
+      }
+      // COMPOSECOLOR: the chart takes the item's blended colour (flat's itemA[a].szColor, the same
+      // blend the choropleth uses) instead of one class colour
+      let composed;
+      if (this.flags.has('COMPOSECOLOR') && this._multiFields && raw) {
+        const c = this._resolveComposedColor(raw);
+        composed = `rgb(${c[0]},${c[1]},${c[2]})`;
+      }
+      const base = `user|${name}|${cat}|${Math.round(value * 100) / 100}|${values.length > 1 ? values.join(',') : ''}|${composed || ''}|${Math.round(size * 2) / 2}|${flag}|${title || ''}`;
       if (!this._userChartSvgs) this._userChartSvgs = new Map();
       let chart = this._userChartSvgs.get(base);
       if (chart === undefined) {
-        chart = this._drawUserChartSvg(draw, name, theme, flag, d, value, cat, size, nSize);
+        chart = this._drawUserChartSvg(draw, name, theme, flag, d, value, cat, size, nSize, values, composed);
         if (chart === undefined) return null;
         if (this._userChartSvgs.size >= ICON_CACHE_MAX) this._userChartSvgs.delete(this._userChartSvgs.keys().next().value);
         this._userChartSvgs.set(base, chart);
@@ -14546,10 +14765,10 @@ self.onmessage = e => {
     // the page's chart function draws one chart into the hidden SVG: its
     // markup and box (chart units), null when it draws nothing, undefined
     // when it fails
-    _drawUserChartSvg(draw, name, theme, flag, d, value, cat, size, nSize) {
+    _drawUserChartSvg(draw, name, theme, flag, d, value, cat, size, nSize, values, composedColor) {
       const g = document.createElementNS(SVG_NS, 'g');
       this._userChartGroup.appendChild(g);
-      const color = this._userChartColor(cat);
+      const color = composedColor || this._userChartColor(cat);
       const raw = d.properties.raw || d.properties;
       const label = this.binding.title && raw && raw[this.binding.title] != null ? String(raw[this.binding.title]) : undefined;
       // flat's chart title (style.titlefield, maptheme's item.szTitle) —
@@ -14559,7 +14778,7 @@ self.onmessage = e => {
       let chart = null;
       try {
         const ret = draw.call(global.ixmaps, document, {
-          target: g, theme, value, values: [value], size, maxSize: USER_CHART_MAX_SIZE, color, class: cat, flag,
+          target: g, theme, value, values: values || [value], size, maxSize: USER_CHART_MAX_SIZE, color, class: cat, flag,
           // flat hands the chart the item's color CLASS object (maptheme's
           // ColorScheme entry) — pinnacleChart reads ccolor.lowColor for its
           // VALUES label fill (usercharts/d3/chart.js 199)
@@ -14570,13 +14789,51 @@ self.onmessage = e => {
         if (bb && bb.width > 0 && bb.height > 0) {
           const markup = new XMLSerializer().serializeToString(g);
           const ids = new Set([...markup.matchAll(/url\(#([^)"']+)\)/g)].map(m => m[1]));
-          const defs = [...ids].map(id => { const el = this._userChartGroup.ownerDocument.getElementById(id); return el ? new XMLSerializer().serializeToString(el) : ''; }).join('');
+          // the gradients the chart uses, kept WITH the chart: a cached chart that was not on the screen in the
+          // last drawing finds no copy of them in the document any more (they are one per colour, and only the
+          // theme's own colours are defined again by _init), and would lose its fill
+          const defsById = {};
+          for (const id of ids) {
+            const el = this._userChartGroup.ownerDocument.getElementById(id);
+            if (el) defsById[id] = new XMLSerializer().serializeToString(el);
+          }
+          const defs = Object.values(defsById).join('');
           // strokes and text halos reach past the geometric box
           const pad = Math.max(bb.width, bb.height) * 0.06 + 10;
           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], bb: { x: bb.x, y: bb.y, width: bb.width, height: bb.height },
+          // the chart's own outline for hover and click: its shapes (the peak's triangle, a pie's circle ...)
+          // sampled into polygons, in chart units around the origin — not the box around them (a tall peak
+          // would otherwise answer to a rectangle, or a circle, far wider than the peak itself)
+          const pick = [];
+          try {
+            const inv = g.getCTM().inverse();
+            const at = (el, x, y) => { const p = new DOMPoint(x, y).matrixTransform(inv.multiply(el.getCTM())); return [p.x - ox, p.y - oy]; };
+            g.querySelectorAll('path,rect,circle,ellipse,polygon').forEach(el => {
+              if (el.closest('defs,clipPath,mask')) return;
+              let ring = null;
+              if (el.tagName === 'path') {
+                const len = el.getTotalLength();
+                if (!(len > 0)) return;
+                const n = Math.max(8, Math.min(40, Math.ceil(len / 50)));
+                ring = [];
+                for (let i = 0; i <= n; i++) { const q = el.getPointAtLength(len * i / n); ring.push(at(el, q.x, q.y)); }
+              } else if (el.tagName === 'rect') {
+                const x = el.x.baseVal.value, y = el.y.baseVal.value, w = el.width.baseVal.value, h = el.height.baseVal.value;
+                ring = [at(el, x, y), at(el, x + w, y), at(el, x + w, y + h), at(el, x, y + h)];
+              } else if (el.tagName === 'polygon') {
+                ring = [...el.points].map(q => at(el, q.x, q.y));
+              } else {
+                const cx = el.cx.baseVal.value, cy = el.cy.baseVal.value;
+                const rx = el.tagName === 'circle' ? el.r.baseVal.value : el.rx.baseVal.value, ry = el.tagName === 'circle' ? rx : el.ry.baseVal.value;
+                ring = [];
+                for (let i = 0; i < 12; i++) ring.push(at(el, cx + rx * Math.cos(i * Math.PI / 6), cy + ry * Math.sin(i * Math.PI / 6)));
+              }
+              if (ring && ring.length >= 3 && ring.every(q => isFinite(q[0]) && isFinite(q[1]))) pick.push(ring);
+            });
+          } catch (e) { /* the box below stands in */ }
+          chart = { vx, vy, vw, vh, ox, oy, markup, ids: [...ids], defsById, pick, 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) {
@@ -14852,7 +15109,8 @@ self.onmessage = e => {
     // to kdeGrid in a worker, d3-contour cuts the bands at fractions of the maximum (style.kdelevels,
     // default 0.15 / 0.30 / 0.50 / 0.70), each band the area at or above its threshold, so they
     // stack, colored from style.colorscheme, drawn with style.fillopacity. The bandwidth is
-    // style.bandwidth (km) or, without it, follows the zoom (kdeBandwidthKm).
+    // style.bandwidth (km) or, without it, follows the zoom (kdeBandwidthKm); style.bandwidthscale
+    // (default 1) multiplies either, style.bandwidthzoompow (default 1) flattens the zoom dependence, so a radius control can stay zoom-aware without lagging a redraw.
     // The result belongs to a view: while the map moves the last bands stay, and once it stands still
     // (and the view, the records, the binding or the bandwidth changed) the new ones are computed
     // after a short pause and drawn by a redraw — never more than one computation wanted at a time.
@@ -14869,7 +15127,18 @@ self.onmessage = e => {
       const source = this._activeFeatures || this.features;
       if (this._kdeSource !== source) { this._kdeSource = source; this._kdeSourceId = (this._kdeSourceId || 0) + 1; }
       const flatZoom = mapLibreToFlatZoom(zoom);
-      const bwKm = styleNum(this.style.bandwidth) > 0 ? styleNum(this.style.bandwidth) : kdeBandwidthKm(flatZoom);
+      const bwScale = styleNum(this.style.bandwidthscale) > 0 ? styleNum(this.style.bandwidthscale) : 1;
+      // style.bandwidthzoompow (0..1) flattens the zoom dependence: the radius is the table's ratio to its
+      // value at the reference flat zoom (style.bandwidthzoomref, default 12), raised to this power
+      // (0 = constant). Without style.bandwidth the radius is the table's, default power 1 (as the fire
+      // pages); WITH style.bandwidth (km) that is the radius AT the reference zoom, default power 0 (fixed).
+      const explicitKm = styleNum(this.style.bandwidth) > 0 ? styleNum(this.style.bandwidth) : 0;
+      const powStyle = styleNum(this.style.bandwidthzoompow);
+      const zoomPow = powStyle >= 0 ? Math.min(1, powStyle) : (explicitKm ? 0 : 1);
+      const refZoom = styleNum(this.style.bandwidthzoomref) > 0 ? styleNum(this.style.bandwidthzoomref) : 12;
+      const tableKm = kdeBandwidthKm(flatZoom), refKm = kdeBandwidthKm(refZoom);
+      const zoomRatio = zoomPow === 1 ? tableKm / refKm : Math.pow(tableKm / refKm, zoomPow);
+      const bwKm = (explicitKm ? explicitKm * zoomRatio : (zoomPow === 1 ? tableKm : refKm * zoomRatio)) * bwScale;
       const maxCells = kdeMaxCells(flatZoom);
       const levels = kdeLevels(this.style);
       const key = JSON.stringify([this._dataGen, this._kdeSourceId, this.binding, bwKm, maxCells, levels, bbox.map(v => Math.round(v * 1e4) / 1e4)]);
@@ -14886,6 +15155,7 @@ self.onmessage = e => {
             this._kdeBands = kdeBands(grid, levels, () => contours());
             this._kdeBandsGen = (this._kdeBandsGen || 0) + 1;   // every set of bands is a new layer for deck.gl
             this._kdeLevelCount = levels.length;
+            this._kdeBandsBw = bwKm;                        // the radius these bands were computed for
             this._kdeKeyDone = key;
             if (this._triggerRedraw) this._triggerRedraw();
           }).catch(err => {
@@ -14896,6 +15166,14 @@ self.onmessage = e => {
       }
       const bands = this._kdeBands;
       if (!bands || !bands.features.length) return [];
+      // bands kept from before the layer was switched off belong to another view and radius: they are not
+      // shown on switching on until the right ones are computed (a wrong-radius density flashing first
+      // reads as flicker). Once the right ones are there the gate opens, and while the map zooms the
+      // last bands stay as before — a gap on every zoom step would be worse.
+      if (this._kdeShowGate) {
+        if (this._kdeBandsBw !== bwKm) return [];
+        this._kdeShowGate = false;
+      }
       const colors = kdeBandColors(this.style.colorscheme, this._kdeLevelCount || levels.length);
       return [new GeoJsonLayer({
         // a new id for each set of bands: deck.gl keeps a layer's buffers by id, and bands whose polygon
@@ -17685,6 +17963,24 @@ self.onmessage = e => {
     //    the item color (stroke font/7, opacity 0.5).
     // Both moved by the chart position (flatChartAlignOffset). The text is
     // the hover target of TEXTONLY, the box of LABEL.
+    // A text field bound as the LABEL's value scans to 0 (flat's __scanValue), so the labels are drawn at the smallest size
+    // with the text "0" — as flat skips such items, nothing visible, and no message. Say how to show a text: flat's
+    // style.valuefield (or "$title$"), with a numeric value or size binding. CATEGORICAL values are categories, not numbers.
+    _warnTextValue(combined) {
+      // looked at once per theme (this runs on every redraw): the first record with a value
+      if (this._checkedTextValue || this.style.valuefield || this.flags.has('CATEGORICAL') || !this.binding.value) return;
+      let sample;
+      for (const d of combined) {
+        const v = d.properties.raw && d.properties.raw[this.binding.value];
+        if (v != null && String(v).trim() !== '') { sample = v; break; }
+      }
+      if (sample === undefined) return;
+      this._checkedTextValue = true;
+      if (!isNaN(scanValue(sample))) return;
+      console.warn(`[ixmaps-gl] theme "${this.name}": LABEL value field "${this.binding.value}" holds text ("${String(sample).slice(0, 20)}"), ` +
+        'which reads as 0 — as in flat the labels are not visible. To show a text keep a numeric value (or size) binding ' +
+        'and name the text field in style.valuefield (or "$title$" for the title).');
+    }
     _buildLabelChartLayers(combined, zoom, liveZoom, sizeValueOf) {
       const textOnly = this.flags.has('TEXTONLY');
       const showValues = this.flags.has('VALUES') && !valuesHiddenByScale(this.style, zoom);
@@ -17699,6 +17995,7 @@ self.onmessage = e => {
       const textOf = props => flatValueText(props.counts ? this._categoryValueRecord(dominant(props.counts)) : props.raw,
         this.binding.title && props.raw ? props.raw[this.binding.title] : undefined, valueOf(props), this.style, this.flags, opts);
 
+      this._warnTextValue(combined);
       if (textOnly) {
         const textRgb = textOverride ? hexOrNamedToRgb(textOverride) : [0, 0, 0];
         const labels = [];
@@ -18069,7 +18366,7 @@ self.onmessage = e => {
   // last built map; called while the map is still building, they run once
   // it is ready.
   const MAP_HANDLE_METHODS = ['replace', 'add', 'newTheme', 'remove', 'removeTheme', 'replaceTheme', 'changeThemeStyle', 'setThemeStyle',
-    'refreshTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'setProjection', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible', 'switchLayer', 'setThemeTimeFrame', 'attribution'];
+    'refreshTheme', 'setBasemapOpacity', 'setMapType', 'setMapTypeId', 'mapType', 'setProjection', 'resize', 'view', 'options', 'layer', 'loadProject', 'require', 'setThemeVisible', 'switchLayer', 'setThemeTimeFrame', 'attribution', 'on', 'off'];
   const _mapHandles = Object.create(null);
   function makeMapHandle(szMap) {
     const h = {};
@@ -18087,6 +18384,9 @@ self.onmessage = e => {
       };
     }
     h.getZoom = () => { const a = api(); return a ? a.getZoom() : undefined; };
+    h.getBounds = () => getBounds();
+    // the MapLibre map itself (undefined until the map is built)
+    h.getMapLibre = () => { const a = api(); return a ? a.map : undefined; };
     h.getThemeObj = id => getThemeObj(id);
     // flat's mapApi.message(szText) (htmlgui_flat.js 1381): a short status
     // line over the map — the same accepted no-op as the global
@@ -18198,6 +18498,12 @@ self.onmessage = e => {
     return [{ lat: Math.max(b[0].lat, -85.05), lng: b[0].lng }, { lat: Math.min(b[1].lat, 85.05), lng: b[1].lng }];
   }
 
+  // flat's mapApi.getBounds() (htmlgui_flat.js): [swLat, swLng, neLat, neLng] — the same box as getBoundingBox
+  function getBounds() {
+    const b = getBoundingBox();
+    return b ? [b[0].lat, b[0].lng, b[1].lat, b[1].lng] : null;
+  }
+
   // flat's ixmaps.setTitle(html) / setTitleBox(text, color) (htmlgui.js
   // 1311-1331): a message line over the last built map, same markup as
   // flat's default (legend not aligned left); '' clears it.
@@ -18743,7 +19049,7 @@ self.onmessage = e => {
   global.ixmaps = {
     layer, Layer: layer, Map: createMap, setExternalData: setExternalDataBridge, getThemeObj, data: ixmapsData,
     szResourceBase: ixmapsSzResourceBase, getProjectString, setProjectJSON, loadProject,
-    markThemeClass, unmarkThemeClass, getBoundingBox, setTitle, setTitleBox, refreshTheme, formatValue: flatFormatValue,
+    markThemeClass, unmarkThemeClass, getBoundingBox, getBounds, setTitle, setTitleBox, refreshTheme, formatValue: flatFormatValue,
     // flat's ixmaps.__formatValue (ui/js/tools/legend.js 451-553) — pages call
     // it for statistics/legend values; legend's own variant differs from
     // format.js's only in the SPACE flag, which flatFormatValue covers too
@@ -18806,7 +19112,7 @@ self.onmessage = e => {
   // 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, 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,
+    splitMapEvents, getBounds, 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,

package/package.json

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