feat(legend): set_legend / reset_legend, and legend state in get_map_state (#334) (#340)

Author: cboettig

AGENTS.md

@@ -14,7 +14,7 @@ Core library for map-based applications with LLM-powered data analysis. Interact
 - `main.js` — Bootstrap: loads config, initializes catalog → map → tools → agent → UI
 - `dataset-catalog.js` — Fetches STAC collections, builds unified records
 - `map-manager.js` — Creates MapLibre map, manages layers/filters/styles
-- `map-tools.js` — 9 local tools the LLM agent can call
+- `map-tools.js` — the local tools the LLM agent can call (map control, styling, legends, geocoding)
 - `tool-registry.js` — Unified dispatch for local + remote (MCP) tools
 - `mcp-client.js` — MCP transport wrapper (connect once, lazy reconnect)
 - `agent.js` — LLM orchestration loop (agentic tool-use cycle)

app/map-manager.js

@@ -1088,6 +1088,131 @@ export class MapManager {
         return { success: true, layer: layerId, displayName: state.displayName, tooltipFields: state.tooltipFields };
     }
 
+    // ---- Legend ----
+
+    /**
+     * Set the parts of a legend that cannot be derived from the map: what the
+     * classes are called, what the layer is called, the unit on a colorbar's end
+     * values, and whether the section shows at all (#334).
+     *
+     * Colors and value ranges are deliberately not settable — those come from
+     * the paint, so a legend cannot be made to disagree with what's rendered
+     * (the staleness #333 removed). What the agent supplies is the semantics it
+     * alone knows: it wrote the SQL that turned "Amphibians" into the integer 1,
+     * and nothing on the client can recover that mapping from the tiles.
+     *
+     * @param {string} layerId
+     * @param {Object} opts
+     * @param {Object<string,string>} [opts.labels] - value → class name, for
+     *   categorical legends. Merged with any labels already set.
+     * @param {string} [opts.title] - Layer heading, in the legend and the layer panel.
+     * @param {string} [opts.units] - Unit suffix on colorbar end values.
+     * @param {boolean} [opts.visible] - false suppresses the section.
+     * @returns {Object} Result, including the legend as it now reads.
+     */
+    setLegend(layerId, opts = {}) {
+        const state = this.layers.get(layerId);
+        if (!state) return { success: false, error: `Unknown layer: ${layerId}` };
+
+        const { labels, title, units, visible } = opts;
+
+        if (labels !== undefined) {
+            if (labels === null || typeof labels !== 'object' || Array.isArray(labels)) {
+                return { success: false, error: 'labels must be an object mapping class values to names' };
+            }
+            const bad = Object.entries(labels).find(([, v]) => typeof v !== 'string');
+            if (bad) return { success: false, error: `label for "${bad[0]}" must be a string` };
+            // Merge: labelling classes one call at a time shouldn't drop earlier names.
+            state.legendLabels = { ...(state.legendLabels || {}), ...labels };
+        }
+
+        if (title !== undefined) {
+            if (typeof title !== 'string' || !title.trim()) {
+                return { success: false, error: 'title must be a non-empty string' };
+            }
+            // Capture once, so reset lands on the name boot rendered rather than
+            // on whatever an earlier setLegend left behind.
+            if (state.defaultDisplayName === undefined) state.defaultDisplayName = state.displayName;
+            state.displayName = title;
+            this._renameLayerControl(layerId, title);
+        }
+
+        if (units !== undefined) {
+            if (units !== null && typeof units !== 'string') {
+                return { success: false, error: 'units must be a string (or null to clear)' };
+            }
+            if (state.defaultLegendLabel === undefined) state.defaultLegendLabel = state.legendLabel ?? null;
+            state.legendLabel = units || null;
+        }
+
+        if (visible !== undefined) {
+            if (typeof visible !== 'boolean') return { success: false, error: 'visible must be a boolean' };
+            state.legendHidden = !visible;
+        }
+
+        this._refreshLegend(layerId);
+        return { success: true, layer: layerId, ...this.describeLegend(layerId) };
+    }
+
+    /**
+     * Drop agent-supplied legend labels, title, units, and suppression, leaving
+     * the legend as config declared it. Mirrors resetStyle / resetTooltip; does
+     * not touch paint, so a legend derived from a restyle stays derived.
+     */
+    resetLegend(layerId) {
+        const state = this.layers.get(layerId);
+        if (!state) return { success: false, error: `Unknown layer: ${layerId}` };
+
+        state.legendLabels = null;
+        state.legendHidden = false;
+        if (state.defaultDisplayName !== undefined) {
+            state.displayName = state.defaultDisplayName;
+            this._renameLayerControl(layerId, state.displayName);
+        }
+        if (state.defaultLegendLabel !== undefined) state.legendLabel = state.defaultLegendLabel;
+
+        this._refreshLegend(layerId);
+        return { success: true, layer: layerId, ...this.describeLegend(layerId) };
+    }
+
+    /**
+     * How a layer's legend currently reads — the resolved type, whether it's on
+     * screen, and for a categorical legend the class values with their labels,
+     * so the agent can see which are still bare codes.
+     */
+    describeLegend(layerId) {
+        const state = this.layers.get(layerId);
+        if (!state) return { error: `Unknown layer: ${layerId}` };
+
+        const type = this._resolvedLegendType(state);
+        const categorical = type === 'categorical' ? this._categoricalLegend(state) : null;
+        return {
+            displayName: state.displayName,
+            legend: {
+                type,
+                rendered: !!type && state.visible && !state.legendHidden,
+                ...(state.legendLabel && { units: state.legendLabel }),
+                ...(categorical && {
+                    classes: categorical.classes.map(c => ({
+                        ...(c.value !== undefined && { value: c.value }),
+                        label: c.name ?? `Class ${c.value}`,
+                    })),
+                }),
+            },
+        };
+    }
+
+    /** Update a layer's row in the layer panel after a rename. */
+    _renameLayerControl(layerId, name) {
+        const safeId = layerId.replace(/\//g, '-');
+        const row = document.getElementById(`layer-item-${safeId}`);
+        if (!row) return;
+        const span = row.querySelector('label span');
+        if (span) span.textContent = name;
+        const removeBtn = row.querySelector('.layer-remove-btn');
+        if (removeBtn) removeBtn.setAttribute('aria-label', `Remove ${name}`);
+    }
+
     // ---- Styling ----
 
     /**
@@ -1228,6 +1353,10 @@ export class MapManager {
                 // Hex layers color by a single dynamic column; expose it so the
                 // agent styles against the real property, not a guess (#259).
                 ...(state.valueColumn && { valueColumn: state.valueColumn }),
+                // What the legend currently says. Without this the agent is
+                // blind to the one part of the map it can't see, and reads a
+                // "the colors are wrong" complaint as a paint bug (#334).
+                legend: this.describeLegend(id).legend,
             };
         }
         return { success: true, layers };
@@ -1840,10 +1969,26 @@ export class MapManager {
      * declared `continuous` or which is a hex layer.
      */
     _hasLegend(state) {
-        return state.type === 'raster'
-            || !!this._categoricalLegend(state)
-            || (state.legendType === 'continuous' && !!this._continuousVectorLegend(state))
-            || (state.legendType === 'hex' && !!this._hexLegend(state));
+        return !state.legendHidden && !!this._resolvedLegendType(state);
+    }
+
+    /**
+     * What a layer's legend actually renders as *now* — as opposed to
+     * `state.legendType`, which is what config declared. They diverge whenever a
+     * restyle has recolored the layer past its declared type (a hex layer
+     * recolored with `match` resolves 'categorical'), and `get_map_state`
+     * reports this one so the agent can see the legend it's being asked about
+     * (#334).
+     *
+     * @returns {'raster'|'categorical'|'continuous'|'hex'|null} null when the
+     *   layer contributes no legend.
+     */
+    _resolvedLegendType(state) {
+        if (state.type === 'raster') return 'raster';
+        if (this._categoricalLegend(state)) return 'categorical';
+        if (state.legendType === 'continuous' && this._continuousVectorLegend(state)) return 'continuous';
+        if (state.legendType === 'hex' && this._hexLegend(state)) return 'hex';
+        return null;
     }
 
     /**
@@ -1868,20 +2013,37 @@ export class MapManager {
             if (!derived) return null;
             const classes = derived.classes.map(c => ({
                 value: c.value,
-                // No name exists to show: the tiles carry the code, and what it
-                // means lives in the SQL that produced it. Label with the value
-                // itself — honest and discrete, and `set_legend` can name it.
-                name: Array.isArray(c.value)
-                    ? c.value.map(v => this._fmtLegendValue(v)).join(', ')
-                    : this._fmtLegendValue(c.value),
+                // Nothing on the client knows what the code means — the tiles
+                // carry the code, and its meaning lives in the SQL that produced
+                // it. Fall back to the value itself, which `set_legend` labels.
+                name: this._legendClassLabel(state, c.value)
+                    ?? (Array.isArray(c.value)
+                        ? c.value.map(v => this._fmtLegendValue(v)).join(', ')
+                        : this._fmtLegendValue(c.value)),
                 'color-hint': c.color,
             }));
             return { classes, derived: true };
         }
 
-        return (state.legendType === 'categorical' && state.legendClasses?.length > 0)
-            ? { classes: state.legendClasses, derived: false }
-            : null;
+        if (!(state.legendType === 'categorical' && state.legendClasses?.length > 0)) return null;
+        // Author-declared classes, with any agent-supplied label taking priority
+        // (the agent is renaming what the user is looking at right now).
+        const classes = state.legendClasses.map(cls => {
+            const label = this._legendClassLabel(state, cls.value);
+            return label == null ? cls : { ...cls, name: label };
+        });
+        return { classes, derived: false };
+    }
+
+    /**
+     * An agent-supplied label for one legend class, or null. Values arrive from
+     * the model as strings even when the paint matches numbers, so compare
+     * stringified (and join array-valued match arms the way they render).
+     */
+    _legendClassLabel(state, value) {
+        if (!state.legendLabels) return null;
+        const key = Array.isArray(value) ? value.join(',') : String(value);
+        return state.legendLabels[key] ?? null;
     }
 
     /**

app/map-tools.js

@@ -305,6 +305,63 @@ ${pickLayerNudge}`,
             execute: (args) => JSON.stringify(mapManager.resetTooltip(args.layer_id)),
         },
 
+        {
+            name: 'set_legend',
+            description: `Label a layer's legend. Use after you build a map whose meaning isn't visible from the tiles — above all after styling a layer with a \`match\` expression over codes you invented in SQL.
+
+The legend already mirrors the map's colors automatically: a \`match\` recolor renders one swatch per category, a gradient recolor renders a colorbar. What it cannot know is what your codes MEAN. If your SQL emitted \`CASE WHEN ... THEN 1\` for amphibians, the legend shows a swatch labelled "1" until you name it here.
+
+So: whenever you post a color key in chat, call this instead — that key belongs on the map.
+
+  set_legend { "layer_id": "hex-1a66…",
+               "labels": { "1": "Amphibians", "2": "Reptiles", "3": "Birds", "4": "Mammals", "5": "Plants" } }
+
+Fields (all optional except layer_id):
+  labels    class value → name, for a categorical/swatch legend. Keys are the values in
+            your \`match\` expression, as strings. Merged with labels already set.
+  title     heading for the layer, in both the legend and the layer panel.
+  units     unit shown after a colorbar's end values (e.g. "observations", "kg/ha").
+  visible   false hides this layer's legend section; true brings it back.
+
+Colors and value ranges are NOT settable — they are read from the layer's paint, so the legend can never disagree with the map. To change the colors, call set_style; the legend follows.
+
+Call get_map_state to see what a legend currently says (its \`legend.type\`, and \`legend.classes\` with the label each class shows now). Use reset_legend to return to the app's own labels.`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    layer_id: { type: 'string', description: 'Layer ID whose legend to label' },
+                    labels: {
+                        type: 'object',
+                        description: 'Class value → display name, e.g. {"1": "Amphibians", "2": "Reptiles"}. Keys are the values from the layer\'s `match` expression, as strings.',
+                        additionalProperties: { type: 'string' },
+                    },
+                    title: { type: 'string', description: 'Heading for this layer in the legend and layer panel' },
+                    units: { type: 'string', description: 'Unit suffix for a colorbar\'s end values, e.g. "species"' },
+                    visible: { type: 'boolean', description: 'false hides this layer\'s legend section' },
+                },
+                required: ['layer_id'],
+            },
+            execute: (args) => JSON.stringify(mapManager.setLegend(args.layer_id, {
+                labels: args.labels,
+                title: args.title,
+                units: args.units,
+                visible: args.visible,
+            })),
+        },
+
+        {
+            name: 'reset_legend',
+            description: `Discard legend labels, title, units, and hiding you set with set_legend, returning the layer to the app's own legend. Does not change the map's colors — a legend derived from a restyle stays derived. Use when the user asks to "reset the legend" or "put the labels back".`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    layer_id: { type: 'string', description: 'Layer ID whose legend to reset' },
+                },
+                required: ['layer_id'],
+            },
+            execute: (args) => JSON.stringify(mapManager.resetLegend(args.layer_id)),
+        },
+
         {
             name: 'set_style',
             description: `Update a layer's paint/style properties. Provide MapLibre paint properties — every property name carries a layer-type prefix (\`fill-\`, \`line-\`, \`circle-\`, \`raster-\`).
@@ -323,6 +380,8 @@ Examples:
   Data-driven gradient: { "fill-color": ["interpolate", ["linear"], ["get", "PROP"], 0, "#low", 100, "#high"] }
   Stepped: { "fill-color": ["step", ["get", "PROP"], "#c1", 10, "#c2", 50, "#c3"] }
 
+After a \`match\` recolor over codes you defined in SQL, the legend shows one swatch per code labelled with the bare number — call set_legend with \`labels\` to name them, rather than writing the color key out in chat.
+
 For dynamic hex layers (\`hex-…\` ids from add_hex_tile_layer), \`PROP\` is the layer's value column (the \`value_column\` you passed to add_hex_tile_layer, e.g. "species_richness") — NOT "count" unless that is literally the column. If unsure, call get_map_state to read the layer's \`valueColumn\`.
 
 ${pickLayerNudge}`,

docs/guide/configuration.md

@@ -138,6 +138,8 @@ A layer with no `legend_type` at all gains a legend when the agent recolors it i
 
 Swatches derived from a `match` are labelled with the matched value itself (`1`, `2`, …), because the vector tiles carry only the code — what the code *means* usually lives in the SQL that produced the layer. Author-supplied `legend_classes` labels are used whenever the layer has not been recolored past them.
 
+The agent closes that last gap with `set_legend`, which names the classes (`{"1": "Amphibians"}`), retitles the layer, adds a colorbar unit, or hides the section. It cannot set colors or value ranges — those stay derived from the paint, so a legend can't be made to contradict the map. `reset_legend` restores the labels configured here. Nothing in this file needs to change to allow it; `set_legend` overrides `legend_label` and `legend_classes` names for the session only.
+
 ## Asset config — raster (COG)
 
 | Field | Type | Description |