From 1d22259fe9a07ad513620cf1344e3101eb8c6c19 Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 13:46:45 -0300
Subject: [PATCH 1/7] feat(layout): a legend shows a layer under a label
 instead of its name (#1654)

A legend element keeps `labels: {"<layer name>": "<label>"}`, matched by
name in any case as `exclude` is. `layout.update` (and `layout.addElement`
for a legend) take `"labels": {"<layer>": "<label>"|null}`: each entry
replaces that layer's label, null or blank shows its name, {} every name;
a layer the map hasn't is refused. The legend draws and measures the
label (rows, headings, a WMS/WMTS layer's heading), so its size and fit
warnings follow it. Saved with the layout (BTreeMap, skipped when empty);
labels follow a renamed layer and go with a removed one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/layer.rs    |  23 ++--
 crates/engine/src/cmd/layout.rs   | 167 ++++++++++++++++++++++------
 crates/engine/src/tests.rs        |  96 +++++++++++++++++
 crates/map/src/layout.rs          |  28 ++++-
 crates/render/src/layout.rs       | 174 +++++++++++++++++++++---------
 crates/render/src/stream_tests.rs |  10 +-
 crates/render/src/svg.rs          |  20 +++-
 docs/user-guide/layouts.md        |  13 +++
 8 files changed, 436 insertions(+), 95 deletions(-)

diff --git a/crates/engine/src/cmd/layer.rs b/crates/engine/src/cmd/layer.rs
index 9703fe0769..73db4457a9 100644
--- a/crates/engine/src/cmd/layer.rs
+++ b/crates/engine/src/cmd/layer.rs
@@ -4786,12 +4786,13 @@ fn add_sample(s: &mut Session, p: &Value) -> CmdResult {
     Ok(json!({"layer": id}))
 }
 
-/// Legends that leave out layer `old` of the active map, in the frames that show it, follow it:
-/// to its new name, or (`None`, the layer deleted) by dropping it, so a later layer of that name
-/// isn't left out unasked. Called once the layer is renamed or gone: while another layer still
-/// bears `old` (names may repeat), the legends keep it for that one. Renamed onto the name of
-/// another layer a legend lists, the layer is listed with it rather than taking that one out.
-/// A WMS or WMTS layer's name counts as a layer's: legends list those too.
+/// Legends that leave out or label layer `old` of the active map, in the frames that show it,
+/// follow it: to its new name, or (`None`, the layer deleted) by dropping it, so a later layer of
+/// that name isn't left out or labelled unasked. Called once the layer is renamed or gone: while
+/// another layer still bears `old` (names may repeat), the legends keep it for that one. Renamed
+/// onto the name of another layer a legend lists, the layer is listed with it rather than taking
+/// that one out, and under that one's label rather than giving it its own. A WMS or WMTS layer's
+/// name counts as a layer's: legends list those too.
 pub(crate) fn legends_follow_layer(s: &mut Session, old: &str, new: Option<&str>) {
     let named = |s: &Session, n: &str| {
         let m = s.map();
@@ -4810,9 +4811,17 @@ pub(crate) fn legends_follow_layer(s: &mut Session, old: &str, new: Option<&str>
             .map(|e| e.id)
             .collect();
         for e in &mut layout.elements {
-            if let rustgis_map::layout::ElementKind::Legend { frame, exclude, .. } = &mut e.kind
+            if let rustgis_map::layout::ElementKind::Legend { frame, exclude, labels, .. } = &mut e.kind
                 && frames.contains(frame)
             {
+                // Its label (#1654), taken off the old name; onto the new one unless another layer
+                // bears that name, whose label (or none) the renamed layer then shares.
+                let keys: Vec<String> = labels.keys().filter(|n| n.eq_ignore_ascii_case(old)).cloned().collect();
+                let label = keys.iter().filter_map(|k| labels.remove(k)).last();
+                if let (Some(n), Some(l), false) = (new, label, shared) {
+                    labels.retain(|x, _| !x.eq_ignore_ascii_case(n));
+                    labels.insert(n.to_string(), l);
+                }
                 match new {
                     // Another layer the legend lists bears the new name: carrying the exclusion
                     // over would take that one out too, so the renamed layer is listed with it.
diff --git a/crates/engine/src/cmd/layout.rs b/crates/engine/src/cmd/layout.rs
index 54227953c2..f210662417 100644
--- a/crates/engine/src/cmd/layout.rs
+++ b/crates/engine/src/cmd/layout.rs
@@ -1,15 +1,17 @@
 //! Home › Project (New Layout, Import Layout), Publish › Map Frames, Map Surrounds and Text, and
 //! Publish › Output (Export Layout) and Save As (Layout File): page layouts.
 
+use std::collections::BTreeMap;
 use std::path::Path;
 
 use rustgis_geom::{Coord, Extent};
-use rustgis_map::Rgba;
 use rustgis_map::layout::{
     Arrange, ArrowStyle, CoordFormat, ElementKind, FontFamily, FrameShape, Grid, GridEdges, GridKind, GridStyle, Guides, Layout, LineDir,
-    LineHead, MAX_COLORBAR_TICKS, MAX_GRID_WIDTH, MAX_GUIDES, MAX_LEGEND_COLUMNS, MAX_SCALE_DIVISIONS, MAX_TICK_MM, MIN_ELEMENT_MM,
-    MapSeries, Orientation, PAGES, ScaleBarStyle, ScaleUnits, TextAlign, TickSide, fit_scale, line_angle, line_at_angle, line_length,
+    LineHead, MAX_COLORBAR_TICKS, MAX_GRID_WIDTH, MAX_GUIDES, MAX_LEGEND_COLUMNS, MAX_LEGEND_LABEL_CHARS, MAX_LEGEND_LABELS,
+    MAX_SCALE_DIVISIONS, MAX_TICK_MM, MIN_ELEMENT_MM, MapSeries, Orientation, PAGES, ScaleBarStyle, ScaleUnits, TextAlign, TickSide,
+    fit_scale, line_angle, line_at_angle, line_length,
 };
+use rustgis_map::{Map, Rgba};
 use serde_json::{Value, json};
 
 use super::{b, f, numbered, ps};
@@ -91,10 +93,10 @@ pub fn commands() -> Vec<C> {
             r#"{"layout"?, "shape"?: "rectangle"|"circle"|"ellipse"|"polygon"|"lasso", "points"?: [[u, v], …] (polygon/lasso, 0..1 across the frame), "map"?: name, "x"?, "y"?, "w"?, "h"?: mm}"#,
         ),
         C::new("layout.addElement", "Add Element", "Publish › Map Surrounds", add_element).inputs(element_inputs).roles(&[]).effects(crate::policy::Effects::NONE.with(crate::policy::Effect::Files)).params(
-            r##"{"layout"?, "kind": "northArrow"|"scaleBar"|"legend"|"colorbar"|"text"|"dynamicText"|"picture"|"table"|"chart"|"rectangle" (a neatline framing the page unless any of x, y, w, h is given)|"ellipse"|"circle"|"line"|"arrow"|"extentIndicator"|"grid", "frame"?: element id (default: the first map frame), "of"?: frame id (extentIndicator, which also takes "color" and "width" in points, default red and 2), "text"?, "size"?, "color"?: "#RRGGBB"|"#RRGGBBAA" (text, dynamicText, line, arrow, rectangle, ellipse, circle: its outline; extentIndicator; grid; scaleBar; refused for other kinds), "bold"?: bool (text), "italic"?: bool, "align"?: "left"|"center"|"right", "letterSpacing"?: points, -5 to 50 (text, dynamicText), "font"?: "sans"|"serif"|an installed font family's name, as labels.fonts lists them (text, dynamicText; a family not installed here is drawn in its fallback, and a serif where none is installed in the sans, with a warning; refused for other kinds), "fallback"?: "sans"|"serif" (a named font's, where it isn't installed; default its own class, else sans), "title"?: legend title (default "Legend"), "allClasses"?: bool (legend: every class, not only those the frame draws), "hideOther"?: bool (legend: leave out <all other values>), "exclude"?: [layer names] (legend: layers it leaves out though the map draws them), "columns"?: 1..3 (legend: the columns its rows are laid in; default 1), "orientation"?: "horizontal"|"vertical" (colorbar), "ticks"?: 2..21 (colorbar: labelled values, ends included), "tickSide"?: "below"|"above"|"right"|"left" (colorbar), "reverse"?: bool (colorbar: high values first), "fill"?: "#RRGGBBAA" (rectangle, ellipse, circle, northArrow; scaleBar: the alternating bar's light divisions, default white; refused for other kinds), "width"?: outline width in points (rectangle, ellipse, circle; 0 for none) or line width in points (line, grid), "radius"?: mm, 0 to 50 (rectangle: rounded corners), "dir"?: "horizontal"|"vertical"|"falling"|"rising" (line), "head"?: "none"|"end"|"start"|"both" (line; default "end" for an arrow), "angle"?: degrees anticlockwise from pointing right, centred on the page unless x or y is given (line, arrow; it sets the box and the direction, so w, h and dir are not used with it), "length"?: mm (line, arrow), "image"?: base64, "path"?: picture file, "layer"?: (table, chart; colorbar: a raster layer, default the top visible one), "field"?, "label"?, "rows"?, "step"?: degrees, or a measured grid's units (metres) (0 picks one), "type"?: "graticule" (latitudes and longitudes, default) | "measured" (eastings and northings in a projected system, as ArcGIS Pro's measured grid), "crs"?: a measured grid's coordinate system: EPSG:25832, WKT or a PROJ string ("" or none: the map's when projected, else the UTM zone at the frame's centre), "short"?: bool (a measured grid's labels as their kilometres' last two digits, 43 for 543000), "labels"?: bool, "style"?: "lines"|"ticks"|"linesAndTicks" (grid) or "classic"|"compass"|"triangle"|"star" (northArrow) or "alternating"|"stepped"|"line" (scaleBar), "tickLength"?: mm, "format"?: "decimal"|"dms", "hemisphere"?: bool (N/S/E/W rather than a sign), "edges"?: ["top","bottom","left","right"] (labelled edges), "labelOrientation"?: "horizontal"|"vertical", "off"?: bool (grid; options not given keep the grid's), "outline"?: "#RRGGBB" (northArrow, or a rectangle's, ellipse's or circle's outline instead of color; refused for other kinds), "units"?: "auto"|"kilometers"|"meters"|"miles"|"feet", "divisions"?: 1..10 (scaleBar, whose "color" is its lines, dark divisions and labels, default #222222), "x"?, "y"?, "w"?, "h"?: mm}"##,
+            r##"{"layout"?, "kind": "northArrow"|"scaleBar"|"legend"|"colorbar"|"text"|"dynamicText"|"picture"|"table"|"chart"|"rectangle" (a neatline framing the page unless any of x, y, w, h is given)|"ellipse"|"circle"|"line"|"arrow"|"extentIndicator"|"grid", "frame"?: element id (default: the first map frame), "of"?: frame id (extentIndicator, which also takes "color" and "width" in points, default red and 2), "text"?, "size"?, "color"?: "#RRGGBB"|"#RRGGBBAA" (text, dynamicText, line, arrow, rectangle, ellipse, circle: its outline; extentIndicator; grid; scaleBar; refused for other kinds), "bold"?: bool (text), "italic"?: bool, "align"?: "left"|"center"|"right", "letterSpacing"?: points, -5 to 50 (text, dynamicText), "font"?: "sans"|"serif"|an installed font family's name, as labels.fonts lists them (text, dynamicText; a family not installed here is drawn in its fallback, and a serif where none is installed in the sans, with a warning; refused for other kinds), "fallback"?: "sans"|"serif" (a named font's, where it isn't installed; default its own class, else sans), "title"?: legend title (default "Legend"), "allClasses"?: bool (legend: every class, not only those the frame draws), "hideOther"?: bool (legend: leave out <all other values>), "exclude"?: [layer names] (legend: layers it leaves out though the map draws them), "columns"?: 1..3 (legend: the columns its rows are laid in; default 1), "orientation"?: "horizontal"|"vertical" (colorbar), "ticks"?: 2..21 (colorbar: labelled values, ends included), "tickSide"?: "below"|"above"|"right"|"left" (colorbar), "reverse"?: bool (colorbar: high values first), "fill"?: "#RRGGBBAA" (rectangle, ellipse, circle, northArrow; scaleBar: the alternating bar's light divisions, default white; refused for other kinds), "width"?: outline width in points (rectangle, ellipse, circle; 0 for none) or line width in points (line, grid), "radius"?: mm, 0 to 50 (rectangle: rounded corners), "dir"?: "horizontal"|"vertical"|"falling"|"rising" (line), "head"?: "none"|"end"|"start"|"both" (line; default "end" for an arrow), "angle"?: degrees anticlockwise from pointing right, centred on the page unless x or y is given (line, arrow; it sets the box and the direction, so w, h and dir are not used with it), "length"?: mm (line, arrow), "image"?: base64, "path"?: picture file, "layer"?: (table, chart; colorbar: a raster layer, default the top visible one), "field"?, "label"?, "rows"?, "step"?: degrees, or a measured grid's units (metres) (0 picks one), "type"?: "graticule" (latitudes and longitudes, default) | "measured" (eastings and northings in a projected system, as ArcGIS Pro's measured grid), "crs"?: a measured grid's coordinate system: EPSG:25832, WKT or a PROJ string ("" or none: the map's when projected, else the UTM zone at the frame's centre), "short"?: bool (a measured grid's labels as their kilometres' last two digits, 43 for 543000), "labels"?: bool (grid) | {"<layer>": "<label>"} (legend: what it shows instead of a layer's name, as in layout.update; a layer the map hasn't is refused), "style"?: "lines"|"ticks"|"linesAndTicks" (grid) or "classic"|"compass"|"triangle"|"star" (northArrow) or "alternating"|"stepped"|"line" (scaleBar), "tickLength"?: mm, "format"?: "decimal"|"dms", "hemisphere"?: bool (N/S/E/W rather than a sign), "edges"?: ["top","bottom","left","right"] (labelled edges), "labelOrientation"?: "horizontal"|"vertical", "off"?: bool (grid; options not given keep the grid's), "outline"?: "#RRGGBB" (northArrow, or a rectangle's, ellipse's or circle's outline instead of color; refused for other kinds), "units"?: "auto"|"kilometers"|"meters"|"miles"|"feet", "divisions"?: 1..10 (scaleBar, whose "color" is its lines, dark divisions and labels, default #222222), "x"?, "y"?, "w"?, "h"?: mm}"##,
         ),
         C::new("layout.update", "Element Properties", "Publish › Element", update).inputs(update_inputs).roles(&[]).effects(crate::policy::Effects::NONE.with(crate::policy::Effect::Files)).params(
-            r##"{"layout"?, "element": id, "x"?, "y"?, "w"?, "h"?: mm, "name"?, "visible"?, "locked"?: bool (a locked element takes no other change until unlocked; "locked": false unlocks it and may come with changes), "text"?, "size"?, "color"? (text, line, rectangle, ellipse: its outline; scaleBar: its lines, dark divisions and labels; refused for other elements), "bold"?, "italic"?, "align"?, "letterSpacing"?, "font"?: "sans"|"serif"|an installed font family's name, "fallback"?: "sans"|"serif" (text, as in layout.addElement; refused for other elements), "title"?, "allClasses"?: bool (legend), "hideOther"?: bool (legend), "exclude"?: [layer names] (legend; [] lists every layer again), "columns"?: 1..3 (legend), "orientation"?, "ticks"?, "tickSide"?, "reverse"?: (colorbar), "style"?: (northArrow, scaleBar), "fill"?, "outline"? (northArrow, rectangle, ellipse, and a scaleBar's fill; refused for other elements; for a rectangle or ellipse, color sets it when outline is not given; a scaleBar's fill is the alternating bar's light divisions), "radius"?: mm (rectangle: rounded corners), "width"?: points (rectangle, ellipse, line), "dir"?, "head"?, "angle"?, "length"? (line: turned or sized about its centre, then moved by any x or y; dir does not come with angle or length), "units"?, "divisions"? (scaleBar), "map"?, "scale"?, "center"?: [lon, lat], "bearing"?: degrees clockwise from north, "pitch"?: degrees of tilt (0 to 85), "grid"?: {grid options as in layout.addElement} | false (map frame), "extentIndicator"?: {"color"?, "width"?: points} | false (map frame: its extent indicator's style, or removes it), "layer"?: (colorbar: "" for the top visible raster), "field"?, "rows"?}"##,
+            r##"{"layout"?, "element": id, "x"?, "y"?, "w"?, "h"?: mm, "name"?, "visible"?, "locked"?: bool (a locked element takes no other change until unlocked; "locked": false unlocks it and may come with changes), "text"?, "size"?, "color"? (text, line, rectangle, ellipse: its outline; scaleBar: its lines, dark divisions and labels; refused for other elements), "bold"?, "italic"?, "align"?, "letterSpacing"?, "font"?: "sans"|"serif"|an installed font family's name, "fallback"?: "sans"|"serif" (text, as in layout.addElement; refused for other elements), "title"?, "allClasses"?: bool (legend), "hideOther"?: bool (legend), "exclude"?: [layer names] (legend; [] lists every layer again), "labels"?: {"<layer>": "<label>"|null} (legend: what it shows instead of a layer's name, up to 200 characters; each entry replaces that layer's label, null or "" shows its name again, {} every layer's; a layer the map hasn't is refused), "columns"?: 1..3 (legend), "orientation"?, "ticks"?, "tickSide"?, "reverse"?: (colorbar), "style"?: (northArrow, scaleBar), "fill"?, "outline"? (northArrow, rectangle, ellipse, and a scaleBar's fill; refused for other elements; for a rectangle or ellipse, color sets it when outline is not given; a scaleBar's fill is the alternating bar's light divisions), "radius"?: mm (rectangle: rounded corners), "width"?: points (rectangle, ellipse, line), "dir"?, "head"?, "angle"?, "length"? (line: turned or sized about its centre, then moved by any x or y; dir does not come with angle or length), "units"?, "divisions"? (scaleBar), "map"?, "scale"?, "center"?: [lon, lat], "bearing"?: degrees clockwise from north, "pitch"?: degrees of tilt (0 to 85), "grid"?: {grid options as in layout.addElement} | false (map frame), "extentIndicator"?: {"color"?, "width"?: points} | false (map frame: its extent indicator's style, or removes it), "layer"?: (colorbar: "" for the top visible raster), "field"?, "rows"?}"##,
         ),
         C::new("layout.guides", "Guides", "Publish › Page Setup", guides).inputs(object_inputs).roles(&[]).effects(crate::policy::Effects::NONE).params(
             r#"{"layout"?, "x"?: [mm] (vertical guides, from the page's left edge), "y"?: [mm] (horizontal guides, from its top edge), "clear"?: bool (remove every guide first)}"#,
@@ -310,6 +312,7 @@ pub(crate) fn new_layout(s: &mut Session, p: &Value) -> CmdResult {
                     hide_other: false,
                     exclude: Vec::new(),
                     columns: 1,
+                    labels: Default::default(),
                 },
             );
             l.add("North Arrow", (side + sw / 2.0 - 8.0, m + 16.0 + fh * 0.62, 16.0, 24.0), ElementKind::north_arrow(frame));
@@ -1729,7 +1732,7 @@ fn publication(s: &mut Session, p: &Value) -> CmdResult {
     };
     let lonlat = crate::render::view_lonlat(s.map(), &view);
     let reading = s.map_mut().sync_sources(&lonlat, render_scale, true);
-    let mut sizes = crate::render::layout::legend_sizes_mm(s.map_mut(), render_scale, false, false, &[]);
+    let mut sizes = crate::render::layout::legend_sizes_mm(s.map_mut(), render_scale, false, false, (&[], &Default::default()));
     let (mut cw, mut ch) = match sizes {
         Some(sizes) => sizes[0],
         None => {
@@ -2026,6 +2029,7 @@ fn publication(s: &mut Session, p: &Value) -> CmdResult {
                     hide_other: false,
                     exclude: Vec::new(),
                     columns: legend_cols,
+                    labels: Default::default(),
                 },
             );
         }
@@ -2278,6 +2282,7 @@ pub(crate) fn color(p: &Value, k: &str, d: Rgba) -> Result<Rgba, String> {
 }
 
 const ONLY_LEGEND_COLUMNS: &str = "only legends have columns";
+const ONLY_LEGEND_LABELS: &str = "only legends label layers";
 
 /// A box sized to its content, less the padding again, can come out a rounding error short of it:
 /// that still fits.
@@ -2307,13 +2312,13 @@ fn legend_fit_warnings(columns: usize, (w, h): (f64, f64), (room_w, room_h): (f6
 fn say_legend_fit(s: &mut Session, li: usize, id: u32) {
     let Some(l) = s.project.layouts.get(li) else { return };
     let Some(e) = l.element(id) else { return };
-    let ElementKind::Legend { frame, title, all_classes, hide_other, exclude, columns } = &e.kind else { return };
+    let ElementKind::Legend { frame, title, all_classes, hide_other, exclude, columns, labels } = &e.kind else { return };
     let shown = match l.element(*frame).map(|f| &f.kind) {
         Some(ElementKind::MapFrame { map, center, scale, .. }) => Some((map.clone(), *center, *scale)),
         _ => None,
     };
     let (room_w, room_h) = (e.w, e.h - if title.is_empty() { 0.0 } else { crate::render::layout::legend_title_mm() });
-    let (all_classes, hide_other, exclude, columns) = (*all_classes, *hide_other, exclude.clone(), *columns);
+    let (all_classes, hide_other, exclude, columns, labels) = (*all_classes, *hide_other, exclude.clone(), *columns, labels.clone());
     let found = shown
         .and_then(|(name, center, scale)| Some((s.project.maps.iter_mut().find(|m| m.name.eq_ignore_ascii_case(&name))?, center, scale)));
     let Some((map, center, scale)) = found else {
@@ -2321,7 +2326,7 @@ fn say_legend_fit(s: &mut Session, li: usize, id: u32) {
         return;
     };
     let at = crate::render::layout::frame_render_scale(map, center, scale);
-    let Some(sizes) = crate::render::layout::legend_sizes_mm(map, at, all_classes, hide_other, &exclude) else {
+    let Some(sizes) = crate::render::layout::legend_sizes_mm(map, at, all_classes, hide_other, (&exclude, &labels)) else {
         s.warn("a layer's source couldn't be read through, so the legend's fit in its box wasn't checked; exporting says why");
         return;
     };
@@ -2349,6 +2354,10 @@ fn add_element(s: &mut Session, p: &Value) -> CmdResult {
     if kind != "legend" && p.get("columns").is_some_and(|v| !v.is_null()) {
         return Err(ONLY_LEGEND_COLUMNS.into());
     }
+    // (A grid's "labels" is a bool: only an object is a legend's.)
+    if kind != "legend" && p.get("labels").is_some_and(Value::is_object) {
+        return Err(ONLY_LEGEND_LABELS.into());
+    }
     // A family is a text's: refused elsewhere, as a legend's left-out layers are, so a script
     // doesn't take it as applied.
     if !matches!(kind, "text" | "dynamicText") && gives_font(p) {
@@ -2393,10 +2402,14 @@ fn add_element(s: &mut Session, p: &Value) -> CmdResult {
             let hide_other = b(p, "hideOther").unwrap_or(false);
             let exclude = legend_exclude(s, l, frame, p)?.unwrap_or_default();
             let columns = legend_columns_param(p)?.unwrap_or(1);
+            let labels = match legend_labels(s, l, frame, p)? {
+                Some(given) => with_labels(&BTreeMap::new(), given)?,
+                None => BTreeMap::new(),
+            };
             (
                 "Legend",
                 place(p, l, (pw - 70.0, 45.0, 60.0, 80.0))?,
-                ElementKind::Legend { frame, title, all_classes, hide_other, exclude, columns },
+                ElementKind::Legend { frame, title, all_classes, hide_other, exclude, columns, labels },
             )
         }
         "colorbar" => {
@@ -2894,27 +2907,16 @@ fn font_warning(font: FontFamily, name: Option<&str>, fallback_given: bool, styl
 /// A legend's `exclude` from `p`: the names of layers in its frame's map, as the map spells them;
 /// `None` when not given. Not a list of names, or a name the map hasn't, is an error.
 fn legend_exclude(input: &impl super::InputSource, l: &Layout, frame: u32, p: &Value) -> Result<Option<Vec<String>>, String> {
-    let context = input.input_context();
-    let s = &context;
     let Some(v) = p.get("exclude").filter(|v| !v.is_null()) else { return Ok(None) };
     let names = v.as_array().ok_or("exclude is a list of layer names")?;
     if names.len() > rustgis_map::layout::MAX_LEGEND_EXCLUDED {
         return Err(format!("a legend leaves out at most {} layers", rustgis_map::layout::MAX_LEGEND_EXCLUDED));
     }
-    let map_name = match l.element(frame).map(|e| &e.kind) {
-        Some(ElementKind::MapFrame { map, .. }) => map.clone(),
-        _ => return Err("the legend's frame isn't a map frame".into()),
-    };
-    let map = s.project.maps.iter().find(|m| m.name.eq_ignore_ascii_case(&map_name)).ok_or_else(|| format!("no map '{map_name}'"))?;
+    let map = legend_map(input, l, frame)?;
     let mut out: Vec<String> = Vec::new();
     for n in names {
         let n = n.as_str().ok_or("exclude is a list of layer names")?;
-        // A layer of the map's, or a WMS or WMTS layer's (whose legend is its service's picture).
-        let name = map
-            .layer_by_name(n.trim())
-            .map(|l| &l.name)
-            .or_else(|| map.tiles.iter().find(|t| t.name.eq_ignore_ascii_case(n.trim())).map(|t| &t.name))
-            .ok_or_else(|| format!("no layer '{n}' in map '{map_name}'"))?;
+        let name = legend_layer(map, n)?;
         if !out.iter().any(|o| o.eq_ignore_ascii_case(name)) {
             out.push(name.clone());
         }
@@ -2922,6 +2924,80 @@ fn legend_exclude(input: &impl super::InputSource, l: &Layout, frame: u32, p: &V
     Ok(Some(out))
 }
 
+/// The map a legend's frame shows.
+fn legend_map<'m>(input: &'m impl super::InputSource, l: &Layout, frame: u32) -> Result<&'m Map, String> {
+    let context = input.input_context();
+    let s = &context;
+    let map_name = match l.element(frame).map(|e| &e.kind) {
+        Some(ElementKind::MapFrame { map, .. }) => map,
+        _ => return Err("the legend's frame isn't a map frame".into()),
+    };
+    s.project.maps.iter().find(|m| m.name.eq_ignore_ascii_case(map_name)).ok_or_else(|| format!("no map '{map_name}'"))
+}
+
+/// The name of the layer `n` (any case, ends trimmed) of a legend's `map`, as the map spells it:
+/// one of its layers, or a WMS or WMTS layer's (whose legend is its service's picture). One the
+/// map hasn't is an error.
+fn legend_layer<'m>(map: &'m Map, n: &str) -> Result<&'m String, String> {
+    map.layer_by_name(n.trim())
+        .map(|l| &l.name)
+        .or_else(|| map.tiles.iter().find(|t| t.name.eq_ignore_ascii_case(n.trim())).map(|t| &t.name))
+        .ok_or_else(|| format!("no layer '{n}' in map '{}'", map.name))
+}
+
+/// The shape a legend's `labels` takes.
+const LABELS_SHAPE: &str = r#"labels is an object of layer names and labels: {"<layer>": "<label>" | null}"#;
+
+/// A legend's `labels` from `p` (#1654): each layer's name, as its frame's map spells it, with the
+/// label to show for it, or `None` to show its name again (a `null` or blank label). `None` when
+/// not given; an empty list for `{}`, which shows every layer's name again. Not an object of
+/// labels, a name the map hasn't, or a layer named twice is an error.
+fn legend_labels(
+    input: &impl super::InputSource,
+    l: &Layout,
+    frame: u32,
+    p: &Value,
+) -> Result<Option<Vec<(String, Option<String>)>>, String> {
+    let Some(v) = p.get("labels").filter(|v| !v.is_null()) else { return Ok(None) };
+    let given = v.as_object().ok_or(LABELS_SHAPE)?;
+    if given.len() > MAX_LEGEND_LABELS {
+        return Err(format!("a legend labels at most {MAX_LEGEND_LABELS} layers"));
+    }
+    let map = legend_map(input, l, frame)?;
+    let mut out: Vec<(String, Option<String>)> = Vec::new();
+    for (n, label) in given {
+        let label = match label {
+            Value::Null => None,
+            Value::String(t) if t.trim().is_empty() => None,
+            Value::String(t) => Some(t.chars().take(MAX_LEGEND_LABEL_CHARS).collect()),
+            _ => return Err(LABELS_SHAPE.into()),
+        };
+        let name = legend_layer(map, n)?;
+        // Which of two spellings of a name counts is not the caller's to guess: refused.
+        if out.iter().any(|(o, _)| o.eq_ignore_ascii_case(name)) {
+            return Err(format!("labels names layer '{name}' twice"));
+        }
+        out.push((name.clone(), label));
+    }
+    Ok(Some(out))
+}
+
+/// A legend's `labels` with those `given` ([`legend_labels`]) put in: each layer's label replaced,
+/// or dropped for `None`; none at all for an empty list. More than a legend keeps is an error.
+fn with_labels(labels: &BTreeMap<String, String>, given: Vec<(String, Option<String>)>) -> Result<BTreeMap<String, String>, String> {
+    let mut out = if given.is_empty() { BTreeMap::new() } else { labels.clone() };
+    for (name, label) in given {
+        out.retain(|n, _| !n.eq_ignore_ascii_case(&name));
+        if let Some(t) = label {
+            out.insert(name, t);
+        }
+    }
+    if out.len() > MAX_LEGEND_LABELS {
+        return Err(format!("a legend labels at most {MAX_LEGEND_LABELS} layers"));
+    }
+    Ok(out)
+}
+
 /// A north arrow or scale bar with the options in `p` over `kind`'s; `None` for other elements
 /// or when `p` has none. A bad value is an error, leaving nothing changed.
 fn restyle(kind: &ElementKind, p: &Value) -> Result<Option<ElementKind>, String> {
@@ -3164,6 +3240,18 @@ fn update(s: &mut Session, p: &Value) -> CmdResult {
             _ => None,
         }
     };
+    // And its labels, put in over those it has.
+    let new_labels = {
+        let l = s.project.layouts.get(li).ok_or("no layout")?;
+        match l.element(id).map(|e| &e.kind) {
+            Some(ElementKind::Legend { frame, labels, .. }) => match legend_labels(s, l, *frame, p)? {
+                Some(given) => Some(with_labels(labels, given)?),
+                None => None,
+            },
+            _ if p.get("labels").is_some_and(Value::is_object) => return Err(ONLY_LEGEND_LABELS.into()),
+            _ => None,
+        }
+    };
     let new_columns = legend_columns_param(p)?;
     if new_columns.is_some()
         && !matches!(s.project.layouts.get(li).and_then(|l| l.element(id)).map(|e| &e.kind), Some(ElementKind::Legend { .. }))
@@ -3230,10 +3318,13 @@ fn update(s: &mut Session, p: &Value) -> CmdResult {
                 *bold = v;
             }
         }
-        ElementKind::Legend { title, all_classes, hide_other, exclude, columns, .. } => {
+        ElementKind::Legend { title, all_classes, hide_other, exclude, columns, labels, .. } => {
             if let Some(names) = new_exclude {
                 *exclude = names;
             }
+            if let Some(given) = new_labels {
+                *labels = given;
+            }
             if let Some(n) = new_columns {
                 *columns = n;
             }
@@ -3319,7 +3410,8 @@ fn update(s: &mut Session, p: &Value) -> CmdResult {
         || ps(p, "title").is_some()
         || b(p, "allClasses").is_some()
         || b(p, "hideOther").is_some()
-        || p.get("exclude").is_some_and(|v| !v.is_null());
+        || p.get("exclude").is_some_and(|v| !v.is_null())
+        || p.get("labels").is_some_and(|v| !v.is_null());
     if new_columns.is_some() || (in_columns && refitted) {
         say_legend_fit(s, li, id);
     }
@@ -3929,7 +4021,7 @@ fn element_inputs(input: &super::InputContext<'_>, p: &Value) -> Result<super::I
     }
     let layout = s.project.layouts.get(index(input, p)?).ok_or("no layout")?;
     let frame = frame_of(layout, p)?;
-    if kind == "legend" && legend_exclude(input, layout, frame, p)?.is_none() {
+    if kind == "legend" && legend_exclude(input, layout, frame, p)?.is_none() && legend_labels(input, layout, frame, p)?.is_none() {
         let mut inputs = object_inputs(input, p)?;
         inputs.state["frame"] = json!(frame);
         return Ok(inputs);
@@ -3948,10 +4040,8 @@ fn element_inputs(input: &super::InputContext<'_>, p: &Value) -> Result<super::I
         if let Some(name) = colorbar_layer(input, layout, frame, ps(p, "layer"))? {
             inputs.extend(super::Inputs::named(map, [name.as_str()])?);
         }
-    } else if let Some(names) = legend_exclude(input, layout, frame, p)? {
-        inputs.layers.extend(names.iter().filter_map(|name| map.layer_by_name(name)).map(|l| (map.instance_id(), l.id)));
-        // Tile exclusions are stored selector text, not invented layer/table identities.
-        inputs.state = json!(names);
+    } else {
+        legend_inputs(&mut inputs, map, legend_exclude(input, layout, frame, p)?, legend_labels(input, layout, frame, p)?);
     }
     inputs.maps.push(map.instance_id());
     inputs.state = json!({"layout":index(input,p)?,"frame":frame,"selectors":inputs.state});
@@ -4176,10 +4266,9 @@ fn update_inputs(input: &super::InputContext<'_>, p: &Value) -> Result<super::In
             }
         }
         Some(ElementKind::Legend { frame, .. }) => {
-            if let Some(names) = legend_exclude(input, l, *frame, p)? {
-                let map = frame_map(input, l, *frame)?;
-                inputs.layers.extend(names.iter().filter_map(|n| map.layer_by_name(n)).map(|l| (map.instance_id(), l.id)));
-                inputs.state = json!(names);
+            let (names, labels) = (legend_exclude(input, l, *frame, p)?, legend_labels(input, l, *frame, p)?);
+            if names.is_some() || labels.is_some() {
+                legend_inputs(&mut inputs, frame_map(input, l, *frame)?, names, labels);
             }
         }
         _ => {}
@@ -4188,6 +4277,14 @@ fn update_inputs(input: &super::InputContext<'_>, p: &Value) -> Result<super::In
     Ok(inputs)
 }
 
+/// The layers a legend's `exclude` and `labels` name, as inputs. Tile layers' names are stored
+/// selector text, not invented layer/table identities.
+fn legend_inputs(inputs: &mut super::Inputs, map: &Map, names: Option<Vec<String>>, labels: Option<Vec<(String, Option<String>)>>) {
+    let named = names.iter().flatten().chain(labels.iter().flatten().map(|(n, _)| n));
+    inputs.layers.extend(named.filter_map(|n| map.layer_by_name(n)).map(|l| (map.instance_id(), l.id)));
+    inputs.state = json!({"exclude": names, "labels": labels});
+}
+
 /// Reference-only operations bind the actual chosen layout, without reading its stored maps.
 fn object_inputs(input: &super::InputContext<'_>, p: &Value) -> Result<super::Inputs, String> {
     let s = input;
@@ -4215,7 +4312,7 @@ fn element_selectors(kind: &ElementKind) -> Option<Value> {
         ElementKind::MapFrame { map, extent_of, .. } => json!({"map":map,"extentOf":extent_of}),
         ElementKind::Table { frame, layer, .. } => json!({"frame":frame,"layer":layer}),
         ElementKind::Chart { frame, layer, field, label } => json!({"frame":frame,"layer":layer,"field":field,"label":label}),
-        ElementKind::Legend { frame, exclude, .. } => json!({"frame":frame,"exclude":exclude}),
+        ElementKind::Legend { frame, exclude, labels, .. } => json!({"frame":frame,"exclude":exclude,"labels":labels}),
         ElementKind::Colorbar { frame, layer, .. } => json!({"frame":frame,"layer":layer}),
         ElementKind::NorthArrow { frame, .. } | ElementKind::ScaleBar { frame, .. } => json!({"frame":frame}),
         _ => return None,
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 109d7c9969..3cfa360c0d 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29537,6 +29537,102 @@ fn legends_leave_layers_out() {
     assert!(left_out(&s, lakes).is_empty());
 }
 
+/// A legend can show a layer under a label instead of its name (#1654): set when added or later,
+/// entry by entry, `null` or `{}` going back to the name; checked against its frame's map; kept
+/// through a saved project and layout file (not written when empty); following a renamed layer
+/// and dropped with a removed one.
+#[test]
+fn legends_label_layers() {
+    use rustgis_map::layout::ElementKind;
+    let mut s = Session::new(sample::world_project());
+    s.run("layout.new", &json!({"name": "Rótulos"})).unwrap();
+    let labels = |s: &Session, id: u32| -> Vec<(String, String)> {
+        match s.project.layouts[0].element(id).map(|e| &e.kind) {
+            Some(ElementKind::Legend { labels, .. }) => labels.iter().map(|(n, l)| (n.clone(), l.clone())).collect(),
+            _ => panic!("a legend"),
+        }
+    };
+    let pair = |n: &str, l: &str| (n.to_string(), l.to_string());
+    let plain = s.run("layout.addElement", &json!({"kind": "legend"})).unwrap()["element"].as_u64().unwrap() as u32;
+    assert!(labels(&s, plain).is_empty());
+    assert!(!serde_json::to_string(&s.project.layouts[0]).unwrap().contains("labels"), "none isn't written");
+    // Names as the map spells them; a blank label is none.
+    let id = s.run("layout.addElement", &json!({"kind": "legend", "labels": {"rivers": "Rios", "LAKES": " "}})).unwrap()["element"]
+        .as_u64()
+        .unwrap() as u32;
+    assert_eq!(labels(&s, id), [pair("Rivers", "Rios")]);
+    // Entries put in over those it has; null takes one back to the name.
+    s.run("layout.update", &json!({"element": id, "labels": {"Lakes": "Lagos", "Cities": "Cidades"}})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Cities", "Cidades"), pair("Lakes", "Lagos"), pair("Rivers", "Rios")]);
+    s.run("layout.update", &json!({"element": id, "labels": {"cities": null, "RIVERS": "Rios principais"}})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Lakes", "Lagos"), pair("Rivers", "Rios principais")]);
+    // A layer the map hasn't, a layer named twice, or not an object of labels is an error that
+    // changes nothing; so is `labels` on another kind of element.
+    for bad in [
+        json!({"Atlantis": "x"}),
+        json!({"Rivers": "a", "rivers": "b"}),
+        json!({"Rivers": 3}),
+        json!({"Rivers": ["Rios"]}),
+        json!(["Rivers"]),
+        json!("Rivers"),
+    ] {
+        assert!(s.run("layout.update", &json!({"element": id, "labels": bad})).is_err(), "{bad}");
+        assert!(s.run("layout.addElement", &json!({"kind": "legend", "labels": bad})).is_err(), "{bad}");
+    }
+    assert!(s.run("layout.update", &json!({"element": id, "labels": {"Atlantis": "x"}})).unwrap_err().contains("no layer 'Atlantis'"));
+    assert_eq!(labels(&s, id), [pair("Lakes", "Lagos"), pair("Rivers", "Rios principais")]);
+    let title = s.project.layouts[0].elements.iter().find(|e| e.name == "Title").unwrap().id;
+    assert!(s.run("layout.update", &json!({"element": title, "labels": {"Rivers": "Rios"}})).unwrap_err().contains("only legends"));
+    assert!(s.run("layout.addElement", &json!({"kind": "scaleBar", "labels": {"Rivers": "Rios"}})).unwrap_err().contains("only legends"));
+    // A grid's own "labels" (a bool) is still its.
+    let frame = s.run("layout.addElement", &json!({"kind": "grid", "labels": false})).unwrap()["element"].as_u64().unwrap() as u32;
+    assert!(matches!(
+        s.project.layouts[0].element(frame).map(|e| &e.kind),
+        Some(ElementKind::MapFrame { grid: Some(g), .. }) if !g.labels
+    ));
+    // A long label is cut to its length.
+    let long = "x".repeat(rustgis_map::layout::MAX_LEGEND_LABEL_CHARS + 50);
+    s.run("layout.update", &json!({"element": plain, "labels": {"Countries": long}})).unwrap();
+    assert_eq!(labels(&s, plain)[0].1.chars().count(), rustgis_map::layout::MAX_LEGEND_LABEL_CHARS);
+    // Kept through a saved project, and a layout file.
+    let dir = std::env::temp_dir().join(format!("rustgis-legend-labels-{}", std::process::id()));
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("rotulos.rgis");
+    s.run("project.saveAs", &json!({"path": path.display().to_string()})).unwrap();
+    s.run("project.open", &json!({"path": path.display().to_string()})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Lakes", "Lagos"), pair("Rivers", "Rios principais")]);
+    let file = dir.join("rotulos.rgislayout");
+    s.run("layout.save", &json!({"path": file.display().to_string()})).unwrap();
+    s.run("layout.import", &json!({"path": file.display().to_string()})).unwrap();
+    assert!(matches!(
+        s.project.layouts[1].element(id).map(|e| &e.kind),
+        Some(ElementKind::Legend { labels, .. }) if labels.get("Rivers").is_some_and(|l| l == "Rios principais")
+    ));
+    std::fs::remove_dir_all(&dir).ok();
+    // (The imported layout is the active one now; the rest goes to the first.)
+    // The label follows its layer renamed, and goes with it removed, so a later layer of that
+    // name isn't labelled unasked.
+    s.run("layer.rename", &json!({"layer": "Rivers", "name": "Hidrografia"})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Hidrografia", "Rios principais"), pair("Lakes", "Lagos")]);
+    s.run("layer.remove", &json!({"layer": "Lakes"})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Hidrografia", "Rios principais")]);
+    // Renamed onto the name of a layer the legend lists, a layer shares that one's label (here
+    // none) rather than giving it its own.
+    s.run("layer.rename", &json!({"layer": "Hidrografia", "name": "Cities"})).unwrap();
+    assert!(labels(&s, id).is_empty());
+    // A WMS or WMTS layer is labelled by name too.
+    let wms = json!({"url": "https://maps.example.org/wms/{bbox-epsg-3857}", "name": "Soils", "overlay": true, "legend": "https://maps.example.org/legend.png"});
+    s.run("map.addTiles", &wms).unwrap();
+    s.run("layout.update", &json!({"layout": 0, "element": id, "labels": {"soils": "Solos"}})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Soils", "Solos")]);
+    s.run("map.setTiles", &json!({"name": "Soils", "rename": "Soil map"})).unwrap();
+    assert_eq!(labels(&s, id), [pair("Soil map", "Solos")]);
+    // An empty object shows every layer's name again.
+    s.run("layout.update", &json!({"layout": 0, "element": id, "labels": {}})).unwrap();
+    assert!(labels(&s, id).is_empty());
+    assert!(!serde_json::to_string(&s.project.layouts[0].element(id).unwrap()).unwrap().contains("labels"));
+}
+
 /// A point layer of events, one a month through 2015 (two in March), with their dates as text,
 /// epoch milliseconds and years.
 fn timed_events() -> Session {
diff --git a/crates/map/src/layout.rs b/crates/map/src/layout.rs
index d171104e6d..7a9e7c8a5f 100644
--- a/crates/map/src/layout.rs
+++ b/crates/map/src/layout.rs
@@ -4,6 +4,8 @@
 //! Element positions are in millimetres from the page's top-left corner. A map frame shows a map
 //! of the project at its own centre and scale, independent of the map view.
 
+use std::collections::BTreeMap;
+
 use rustgis_geom::Coord;
 use serde::{Deserialize, Serialize};
 
@@ -462,6 +464,12 @@ fn is_left(a: &TextAlign) -> bool {
 /// The most layers a legend leaves out.
 pub const MAX_LEGEND_EXCLUDED: usize = 1000;
 
+/// The most layers a legend labels.
+pub const MAX_LEGEND_LABELS: usize = 1000;
+
+/// The most characters of a legend's label for a layer.
+pub const MAX_LEGEND_LABEL_CHARS: usize = 200;
+
 /// Which way a line element runs across its box.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
 pub enum LineDir {
@@ -927,6 +935,11 @@ pub enum ElementKind {
         /// as they can be, a layer's name staying with the row under it.
         #[serde(default = "one_column", skip_serializing_if = "is_one_column")]
         columns: usize,
+        /// The label it shows for a layer instead of the layer's name, by the layer's name (any
+        /// case, as the map spells it): its row, or the name over its classes (#1654). The layer
+        /// keeps its name everywhere else. A layer not in it shows its name.
+        #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+        labels: BTreeMap<String, String>,
     },
     /// The colour scale of a raster layer in a frame's map: a gradient bar for a stretch, steps
     /// for classes, a block per value for unique values and colour tables (#326).
@@ -1359,12 +1372,25 @@ impl Layout {
                         g.width = finite_or(g.width, grid_width()).clamp(0.0, MAX_GRID_WIDTH);
                     }
                 }
-                ElementKind::Legend { exclude, columns, .. } => {
+                ElementKind::Legend { exclude, columns, labels, .. } => {
                     // Names stay whole: a layer's own name isn't cut, and a cut one would no
                     // longer match it.
                     cut |= exclude.len() > MAX_LEGEND_EXCLUDED;
                     exclude.truncate(MAX_LEGEND_EXCLUDED);
                     *columns = (*columns).clamp(1, MAX_LEGEND_COLUMNS);
+                    // The same for the names labelled; a label is cut to its length, and a blank
+                    // one shows the name, as it would without.
+                    labels.retain(|_, label| !label.trim().is_empty());
+                    let labelled = labels.len();
+                    while labels.len() > MAX_LEGEND_LABELS {
+                        labels.pop_last();
+                    }
+                    cut |= labels.len() < labelled;
+                    for label in labels.values_mut() {
+                        let end = label.char_indices().nth(MAX_LEGEND_LABEL_CHARS).map_or(label.len(), |(i, _)| i);
+                        cut |= end < label.len();
+                        label.truncate(end);
+                    }
                 }
                 ElementKind::Text { text, size, letter_spacing, .. } => {
                     *size = finite_or(*size, 12.0).clamp(*crate::graphics::FONT_SIZE.start(), *crate::graphics::FONT_SIZE.end());
diff --git a/crates/render/src/layout.rs b/crates/render/src/layout.rs
index b9524ecf2d..9c3833cb11 100644
--- a/crates/render/src/layout.rs
+++ b/crates/render/src/layout.rs
@@ -1,6 +1,8 @@
 //! Draws a page layout: the page, its map frames (each a map rendered at the frame's scale and
 //! clipped to its shape, with grids and extent indicators), and the surrounds.
 
+use std::collections::BTreeMap;
+
 use crate::Canvas;
 use rustgis_data::GeometryType;
 use rustgis_geom::{Coord, Extent};
@@ -312,14 +314,15 @@ fn draw_page(
                     scale_bar(&mut pm, r, map.ground_res_at(&cam), bar, (*color, *fill), ppp, layout.decimal_comma);
                 }
             }
-            ElementKind::Legend { frame: f, title, all_classes, hide_other, exclude, columns } => {
+            ElementKind::Legend { frame: f, title, all_classes, hide_other, exclude, columns, labels } => {
                 if let Some(&(_, mi, cam, ..)) = frame(*f)
                     && let Some(map) = maps.get(mi)
                 {
                     let drawn = (!*all_classes).then(|| shown.iter().find(|(id, _)| id == f).map(|(_, v)| v.as_slice()).unwrap_or(&[]));
                     let scale = map.ground_res_at(&cam) / rustgis_geom::PIXEL_M;
                     wait_for_tile_legends(map, scale, exclude);
-                    legend(&mut pm, r, map, (title, *columns), drawn, LegendOptions { hide_other: *hide_other, exclude, scale }, ppp);
+                    let opts = LegendOptions { hide_other: *hide_other, exclude, labels, scale };
+                    legend(&mut pm, r, map, (title, *columns), drawn, opts, ppp);
                 }
             }
             ElementKind::Colorbar { frame: f, layer, title, orientation, ticks, tick_side, reverse } => {
@@ -1536,19 +1539,31 @@ fn complete_shown_legends(map: &mut Map, scale: f64) -> Option<Vec<(u32, Vec<Leg
     Some(out)
 }
 
-/// What a legend leaves out: `<all other values>`, and layers by name; and the scale denominator
-/// whose legend pictures a WMS or WMTS layer shows.
+/// What a legend leaves out: `<all other values>`, and layers by name; the labels it shows for
+/// layers instead of their names; and the scale denominator whose legend pictures a WMS or WMTS
+/// layer shows.
 #[derive(Clone, Copy)]
 struct LegendOptions<'a> {
     hide_other: bool,
     exclude: &'a [String],
+    labels: &'a BTreeMap<String, String>,
     scale: f64,
 }
 
+impl<'a> LegendOptions<'a> {
+    /// What the legend shows for the layer named `name`: its label (by name, any case), or the
+    /// name when it has none (#1654).
+    fn shown(&self, name: &'a str) -> &'a str {
+        let label = self.labels.get(name).or_else(|| self.labels.iter().find(|(n, _)| n.eq_ignore_ascii_case(name)).map(|(_, l)| l));
+        label.map(String::as_str).filter(|l| !l.trim().is_empty()).unwrap_or(name)
+    }
+}
+
 /// A row of a legend: a layer drawn in one symbol (its swatch and name), a layer's name over its
-/// classes, or one of them, or a WMS or WMTS layer's legend picture (under its name).
+/// classes, or one of them, or a WMS or WMTS layer's legend picture (under its name). The name is
+/// the one the legend shows: the layer's label, if the legend gives it one.
 enum LegendRow<'a> {
-    Plain(&'a rustgis_map::Layer),
+    Plain(&'a rustgis_map::Layer, &'a str),
     Head(&'a str),
     Class(&'a rustgis_map::Layer, LegendEntry),
     Picture(std::sync::Arc<rustgis_tiles::cache::Payload>),
@@ -1558,7 +1573,7 @@ impl LegendRow<'_> {
     /// The side of the square its point symbol takes at 1:`scale`, in points, as far as its marks
     /// reach ([`point_marks::reach`]); 0 for any other row. No larger than a legend picture.
     fn symbol_side(&self, scale: f64) -> f32 {
-        let (LegendRow::Plain(l) | LegendRow::Class(l, _)) = self else { return 0.0 };
+        let (LegendRow::Plain(l, _) | LegendRow::Class(l, _)) = self else { return 0.0 };
         if l.geometry_type() != GeometryType::Point {
             return 0.0;
         }
@@ -1581,7 +1596,7 @@ impl LegendRow<'_> {
     /// Its width beside a column of swatches `column` points wide ([`swatch_column`]), in points.
     fn width(&self, column: f32) -> f32 {
         match self {
-            LegendRow::Plain(l) => column + 6.0 + text::measure(&l.name, 9.0, false),
+            LegendRow::Plain(_, name) => column + 6.0 + text::measure(name, 9.0, false),
             LegendRow::Head(name) => text::measure(name, 9.0, true),
             LegendRow::Class(_, en) => column + 12.0 + text::measure(&en.label, 8.5, false),
             LegendRow::Picture(p) => 6.0 + picture_size(p).0,
@@ -1743,7 +1758,7 @@ const LEGEND_COLUMN_GAP: f32 = 10.0;
 /// The rows of the legend of a frame's map. With `drawn` (from [`shown_legends`]) it shows what the
 /// frame draws: only the layers listed there, with their classes. Without, every class of every
 /// visible layer. `opts` leaves out `<all other values>` and the layers it names, either way.
-fn legend_rows<'a>(map: &'a Map, drawn: Option<&[(u32, Vec<LegendEntry>)]>, opts: &LegendOptions) -> Vec<LegendRow<'a>> {
+fn legend_rows<'a>(map: &'a Map, drawn: Option<&[(u32, Vec<LegendEntry>)]>, opts: &LegendOptions<'a>) -> Vec<LegendRow<'a>> {
     let excluded = |name: &str| opts.exclude.iter().any(|n| n.eq_ignore_ascii_case(name));
     let mut rows = Vec::new();
     // In the order the map draws them and the Layers pane lists them, top first.
@@ -1758,7 +1773,7 @@ fn legend_rows<'a>(map: &'a Map, drawn: Option<&[(u32, Vec<LegendEntry>)]>, opts
                 if let Some(t) = map.tiles.get(i).filter(|t| tile_listed(t) && !excluded(&t.name))
                     && let Some(p) = tile_legend(t, opts.scale, &mut false)
                 {
-                    rows.push(LegendRow::Head(&t.name));
+                    rows.push(LegendRow::Head(opts.shown(&t.name)));
                     rows.push(LegendRow::Picture(p));
                 }
                 continue;
@@ -1790,11 +1805,11 @@ fn legend_rows<'a>(map: &'a Map, drawn: Option<&[(u32, Vec<LegendEntry>)]>, opts
         if entries.is_empty() {
             // A Unique Values layer that lists nothing draws nothing visible (#207).
             if !matches!(l.renderer, rustgis_map::Renderer::Unique { .. }) {
-                rows.push(LegendRow::Plain(l));
+                rows.push(LegendRow::Plain(l, opts.shown(&l.name)));
             }
             continue;
         }
-        rows.push(LegendRow::Head(&l.name));
+        rows.push(LegendRow::Head(opts.shown(&l.name)));
         rows.extend(entries.into_iter().map(|en| LegendRow::Class(l, en)));
     }
     rows
@@ -1878,20 +1893,10 @@ fn legend_column(pm: &mut Canvas, r: Rect, rows: &[LegendRow], name_with_class:
             break;
         }
         match row {
-            LegendRow::Plain(l) => {
+            LegendRow::Plain(l, name) => {
                 let s = l.renderer.symbol_for(&l.dataset, 0);
                 swatch(pm, (r.x(), y, sw, height), l, (&s, l.line_strokes.as_slice()), map.layer_opacity(l), opts.scale, ppp);
-                text::text_at(
-                    pm,
-                    &l.name,
-                    r.x() + sw + 6.0 * ppp,
-                    y + height / 2.0,
-                    9.0 * 1.33 * ppp,
-                    dark,
-                    false,
-                    text::Align::Left,
-                    false,
-                );
+                text::text_at(pm, name, r.x() + sw + 6.0 * ppp, y + height / 2.0, 9.0 * 1.33 * ppp, dark, false, text::Align::Left, false);
             }
             LegendRow::Head(name) => {
                 text::text_at(pm, name, r.x(), y + line / 2.0, 9.0 * 1.33 * ppp, dark, true, text::Align::Left, false);
@@ -1959,16 +1964,16 @@ fn legend_picture(pm: &mut Canvas, r: Rect, y: f32, pic: &Pixmap, ppp: f32) -> O
 /// it), or every class with `all_classes`. For sizing a legend to its content. `None` when a
 /// complete source can't be read, as [`render`] then draws no page. A WMS or WMTS layer's legend
 /// picture still on its way isn't waited for, nor counted ([`tile_legends_pending`] says whether
-/// one is).
+/// one is). Its layers' rows are measured by the `labels` it shows for them, else their names.
 pub fn legend_sizes_mm(
     map: &mut Map,
     scale: f64,
     all_classes: bool,
     hide_other: bool,
-    exclude: &[String],
+    (exclude, labels): (&[String], &BTreeMap<String, String>),
 ) -> Option<[(f64, f64); MAX_LEGEND_COLUMNS]> {
     let drawn = if all_classes { None } else { Some(complete_shown_legends(map, scale)?) };
-    let rows = legend_rows(map, drawn.as_deref(), &LegendOptions { hide_other, exclude, scale });
+    let rows = legend_rows(map, drawn.as_deref(), &LegendOptions { hide_other, exclude, labels, scale });
     let mm = 25.4 / 96.0;
     Some(std::array::from_fn(|i| {
         let (starts, height) = balanced(&rows, i + 1, scale);
@@ -2475,6 +2480,9 @@ pub fn map_index(maps: &[rustgis_map::Map], name: &str) -> Option<usize> {
 mod tests {
     use super::*;
 
+    /// No layer labelled: every layer under its name.
+    static NO_LABELS: BTreeMap<String, String> = BTreeMap::new();
+
     /// A frame drawn over another takes its rectangle out of the other's: the bands above and below
     /// it and the strips beside it are left, a strip too narrow to point into is dropped, and one
     /// that covers it all leaves nothing (#1191).
@@ -2609,7 +2617,7 @@ mod tests {
         let red = |map: &Map, width: f32, exclude: &[String], scale: f64| {
             let mut pm = Pixmap::new(300, 400).unwrap();
             pm.fill(tiny_skia::Color::WHITE);
-            let opts = LegendOptions { hide_other: false, exclude, scale };
+            let opts = LegendOptions { hide_other: false, exclude, labels: &NO_LABELS, scale };
             crate::canvas::with_canvas(&mut pm, |c| {
                 legend(c, Rect::from_xywh(0.0, 0.0, width, 400.0).unwrap(), map, ("", 1), None, opts, 1.0)
             });
@@ -2625,7 +2633,7 @@ mod tests {
         assert!(ink > 200 * 200, "the picture is drawn: {ink} px");
         assert!(right < 6 + 256, "a pixel a point: {right}");
         // Its name's row and the picture, 256 points down and 6 + 256 across.
-        let (w, h) = legend_sizes_mm(&mut map, 1e6, false, false, &[]).unwrap()[0];
+        let (w, h) = legend_sizes_mm(&mut map, 1e6, false, false, (&[], &NO_LABELS)).unwrap()[0];
         let mm = 25.4 / 96.0;
         assert!((w - 262.0 * mm).abs() < 1e-6 && (h - (f64::from(LEGEND_ROW) + 256.0) * mm).abs() < 1e-6, "{w} × {h} mm");
         let (_, right) = red(&map, 100.0, &[], 1e6);
@@ -2641,7 +2649,7 @@ mod tests {
         map.tiles.push(second);
         let mut pm = Pixmap::new(70, 200).unwrap();
         pm.fill(tiny_skia::Color::WHITE);
-        let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         crate::canvas::with_canvas(&mut pm, |c| legend(c, Rect::from_xywh(0.0, 0.0, 70.0, 200.0).unwrap(), &map, ("", 1), None, opts, 1.0));
         let red_rows =
             (0..pm.height()).filter(|&y| (0..pm.width()).any(|x| pm.pixel(x, y).is_some_and(|p| p.red() > 200 && p.green() < 60))).count();
@@ -2663,7 +2671,7 @@ mod tests {
             .iter()
             .filter_map(|r| match r {
                 LegendRow::Head(n) => Some(*n),
-                LegendRow::Plain(l) => Some(l.name.as_str()),
+                LegendRow::Plain(_, name) => Some(*name),
                 _ => None,
             })
             .collect();
@@ -2800,7 +2808,7 @@ mod tests {
                 expression: None,
             };
         }
-        let opts = || LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = || LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         let rows = legend_rows(&map, None, &opts());
         assert_eq!(rows.len(), 32);
         assert_eq!(balanced(&rows, 1, 1e6), (vec![0], 32.0 * LEGEND_ROW));
@@ -2814,7 +2822,7 @@ mod tests {
         let heads = [LegendRow::Head("a"), LegendRow::Head("b"), LegendRow::Head("c"), LegendRow::Head("d"), LegendRow::Head("e")];
         assert_eq!(flow(&heads, 3, 3.0 * LEGEND_ROW, 1e6), (vec![0, 2], true));
 
-        let sizes = legend_sizes_mm(&mut map, 1e6, true, false, &[]).unwrap();
+        let sizes = legend_sizes_mm(&mut map, 1e6, true, false, (&[], &NO_LABELS)).unwrap();
         let row = f64::from(LEGEND_ROW) * 25.4 / 96.0;
         for (size, rows) in sizes.iter().zip([32.0, 16.0, 11.0]) {
             assert!((size.1 - rows * row).abs() < 1e-6, "{size:?} for {rows} rows");
@@ -2884,7 +2892,7 @@ mod tests {
         let small = rustgis_map::Symbol::default_for(GeometryType::Point, 0);
         let classes = (0u32..4).map(|i| (format!("c{i}"), small)).collect();
         let map = classed_point_map(classes, small);
-        let opts = || LegendOptions { hide_other: true, exclude: &[], scale: 1e6 };
+        let opts = || LegendOptions { hide_other: true, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         let rows = legend_rows(&map, None, &opts());
         let (starts, _) = flow(&rows, 2, LEGEND_ROW, 1e6);
         assert_eq!(starts, vec![0, 2]);
@@ -2909,7 +2917,7 @@ mod tests {
         let classes =
             (0u32..10).map(|i| (format!("c{i}"), rustgis_map::Symbol { size: if i < 2 { 40.0 } else { 4.0 }, ..small })).collect();
         let map = classed_point_map(classes, small);
-        let opts = LegendOptions { hide_other: true, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: true, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         let rows = legend_rows(&map, None, &opts);
         let tall = rows[1].height(1e6);
         assert!(tall > 2.0 * LEGEND_ROW, "{tall}");
@@ -2924,6 +2932,74 @@ mod tests {
         assert_eq!(widest(&rows, 1e6), widest(parts[0], 1e6).max(swatch_column(&rows, 1e6) + 12.0 + widest_label(parts[1])));
     }
 
+    /// A legend shows a layer under the label it gives it, by the layer's name in any case (#1654):
+    /// a plain layer's row and a classed layer's heading; it measures and draws the label, so its
+    /// size follows it. A layer it gives no label, or a blank one, shows its name.
+    #[test]
+    fn a_legend_shows_a_layers_label() {
+        use rustgis_data::{Dataset, Field, FieldType, Geometry, Value};
+        let mut map = Map::new("m");
+        let long = "BrasilData: Setores censitários 2022 (MG)";
+        map.add_dataset(Dataset::new(long, GeometryType::Point, vec![]));
+        let mut d = Dataset::new("pts", GeometryType::Point, vec![Field::new("g", FieldType::Text)]);
+        d.push(Some(Geometry::Point(Coord::new(0.0, 0.0))), vec![Value::Text("a".into())]);
+        let pts = map.add_dataset(d);
+        if let Some(l) = map.layers.iter_mut().find(|l| l.id == pts) {
+            l.renderer = rustgis_map::Renderer::Unique {
+                field: "g".into(),
+                classes: vec![("a".into(), rustgis_map::Symbol::default_for(GeometryType::Point, 0))],
+                other: rustgis_map::Symbol::default_for(GeometryType::Point, 1),
+                ramp: rustgis_map::Ramp::Ember,
+                class_labels: Default::default(),
+                other_label: None,
+                class_strokes: Default::default(),
+                other_strokes: Vec::new(),
+                class_fills: Default::default(),
+                other_fills: Vec::new(),
+                expression: None,
+            };
+        }
+        let labels =
+            |pairs: &[(&str, &str)]| -> BTreeMap<String, String> { pairs.iter().map(|(n, l)| (n.to_string(), l.to_string())).collect() };
+        let names = |labels: &BTreeMap<String, String>| -> Vec<String> {
+            let opts = LegendOptions { hide_other: true, exclude: &[], labels, scale: 1e6 };
+            legend_rows(&map, None, &opts)
+                .iter()
+                .filter_map(|r| match r {
+                    LegendRow::Head(n) | LegendRow::Plain(_, n) => Some(n.to_string()),
+                    _ => None,
+                })
+                .collect()
+        };
+        // Top first: pts over the long-named layer.
+        assert_eq!(names(&NO_LABELS), ["pts", long]);
+        let short = labels(&[("brasildata: Setores censitários 2022 (mg)", "Setores"), ("PTS", "Pontos")]);
+        assert_eq!(names(&short), ["Pontos", "Setores"], "by name, any case");
+        assert_eq!(names(&labels(&[("pts", "  ")])), ["pts", long], "a blank label shows the name");
+        assert_eq!(names(&labels(&[("Atlantis", "x")])), ["pts", long], "a label for no layer of the map changes nothing");
+        // Its size: narrower with the short label, wider with a long one; as tall either way.
+        let size = |labels: &BTreeMap<String, String>| legend_sizes_mm(&mut map.clone(), 1e6, true, true, (&[], labels)).unwrap()[0];
+        let (named, labelled) = (size(&NO_LABELS), size(&short));
+        let wide = size(&labels(&[(long, "Setores censitários do Censo Demográfico de 2022 em Minas Gerais")]));
+        assert!(labelled.0 < named.0 - 20.0 && wide.0 > named.0 + 20.0, "{labelled:?} {named:?} {wide:?}");
+        assert!((labelled.1 - named.1).abs() < 1e-9 && (wide.1 - named.1).abs() < 1e-9);
+        // Drawn: the label, which ends within the width measured for it.
+        let reach = |labels: &BTreeMap<String, String>| {
+            let mut pm = Pixmap::new(400, 200).unwrap();
+            pm.fill(tiny_skia::Color::WHITE);
+            let opts = LegendOptions { hide_other: true, exclude: &[], labels, scale: 1e6 };
+            crate::canvas::with_canvas(&mut pm, |c| {
+                legend(c, Rect::from_xywh(0.0, 0.0, 400.0, 200.0).unwrap(), &map, ("", 1), None, opts, 1.0)
+            });
+            let right = (0..pm.width()).filter(|&x| (0..pm.height()).any(|y| pm.pixel(x, y).is_some_and(|p| p.red() < 200))).max();
+            f64::from(right.unwrap_or(0)) * 25.4 / 96.0
+        };
+        for (labels, (w, _)) in [(&NO_LABELS, named), (&short, labelled)] {
+            let right = reach(labels);
+            assert!(right <= w + 0.3 && right > w - 1.5, "{right} mm drawn across {w} mm");
+        }
+    }
+
     #[test]
     fn legends_leave_out_what_the_frame_does_not_draw() {
         use rustgis_data::{Dataset, Field, FieldType, Geometry, Value};
@@ -2954,7 +3030,7 @@ mod tests {
         let depth_without = |map: &Map, drawn: Option<&[(u32, Vec<LegendEntry>)]>, hide_other: bool, exclude: &[String]| {
             let mut pm = Pixmap::new(300, 400).unwrap();
             pm.fill(tiny_skia::Color::WHITE);
-            let opts = LegendOptions { hide_other, exclude, scale: 1e6 };
+            let opts = LegendOptions { hide_other, exclude, labels: &NO_LABELS, scale: 1e6 };
             crate::canvas::with_canvas(&mut pm, |c| {
                 legend(c, Rect::from_xywh(0.0, 0.0, 300.0, 400.0).unwrap(), map, ("", 1), drawn, opts, 1.0)
             });
@@ -2983,21 +3059,21 @@ mod tests {
                     map,
                     ("", 1),
                     drawn,
-                    LegendOptions { hide_other: false, exclude: &[], scale: 1e6 },
+                    LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 },
                     1.0,
                 )
             });
             (0..pm.width()).filter(|&x| (0..pm.height()).any(|y| pm.pixel(x, y).is_some_and(|p| p.red() < 200))).max().unwrap_or(0)
         };
         for (all_classes, ink, right) in [(false, shown, reach(&map, Some(&drawn))), (true, all, reach(&map, None))] {
-            let (w, h) = legend_sizes_mm(&mut map, 1e6, all_classes, false, &[]).unwrap()[0];
+            let (w, h) = legend_sizes_mm(&mut map, 1e6, all_classes, false, (&[], &NO_LABELS)).unwrap()[0];
             let (ink, right) = (f64::from(ink) * 25.4 / 96.0, f64::from(right) * 25.4 / 96.0);
             assert!(w > 0.0 && ink <= h && h - ink < row, "{ink} mm drawn in {h} mm");
             // The widths in the same units as the drawing: the ink ends within the width measured,
             // short of it by no more than a glyph's side bearing.
             assert!(right <= w + 0.3 && right > w - 1.5, "{right} mm drawn across {w} mm");
         }
-        assert!((legend_sizes_mm(&mut map, 1e6, false, false, &[]).unwrap()[0].1 - 2.0 * row).abs() < 1e-9);
+        assert!((legend_sizes_mm(&mut map, 1e6, false, false, (&[], &NO_LABELS)).unwrap()[0].1 - 2.0 * row).abs() < 1e-9);
         // A layer the legend leaves out (by name, any case) isn't listed, drawn or not.
         let name = map.layer(pts).unwrap().name.to_uppercase();
         assert_eq!(depth_without(&map, Some(&drawn), false, std::slice::from_ref(&name)), 0, "its only drawn layer left out");
@@ -3845,7 +3921,7 @@ mod tests {
     fn point_legend(map: &Map) -> Pixmap {
         let mut pm = Pixmap::new(200, 200).unwrap();
         pm.fill(tiny_skia::Color::WHITE);
-        let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         crate::canvas::with_canvas(&mut pm, |c| legend(c, Rect::from_xywh(0.0, 0.0, 200.0, 200.0).unwrap(), map, ("", 1), None, opts, 1.0));
         pm
     }
@@ -3854,7 +3930,7 @@ mod tests {
     /// back on white.
     fn recorded_legend(map: &Map, side: u32) -> Pixmap {
         let mut c = Canvas::recording(side, side).unwrap();
-        let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         legend(&mut c, Rect::from_xywh(0.0, 0.0, side as f32, side as f32).unwrap(), map, ("", 1), None, opts, 1.0);
         let (_, _, items) = c.into_drawing().unwrap().finish();
         let mut pm = Pixmap::new(side, side).unwrap();
@@ -4062,13 +4138,13 @@ mod tests {
         let label = f64::from(6.0 + text::measure("pts", 9.0, false));
         // An ordinary symbol keeps the row and the swatch's column.
         let mut map = point_legend_map(|l| l.renderer = rustgis_map::Renderer::Single(s(10.0)));
-        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, false, &[]).unwrap();
+        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, false, (&[], &NO_LABELS)).unwrap();
         assert!((h - f64::from(LEGEND_ROW) * mm).abs() < 1e-6, "{h} mm");
         // Its width within a rounding: it is summed in f32, past a name as wide as its font makes it.
         assert!((w - (f64::from(LEGEND_SWATCH) + label) * mm).abs() < 1e-4, "{w} mm");
         // One of 40 pt reaches 24 pt from its point: 48 pt each way.
         let mut map = point_legend_map(|l| l.renderer = rustgis_map::Renderer::Single(s(40.0)));
-        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, false, &[]).unwrap();
+        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, false, (&[], &NO_LABELS)).unwrap();
         assert!((h - 48.0 * mm).abs() < 1e-6, "{h} mm");
         assert!((w - (48.0 + label) * mm).abs() < 1e-4, "{w} mm");
         assert!(same_corner(&point_legend(&map), &drawn_point(&s(40.0), &[], (24.0, 24.0), 1.0), 48, 48));
@@ -4076,12 +4152,12 @@ mod tests {
         let mut pm = Pixmap::new(200, 200).unwrap();
         pm.fill(tiny_skia::Color::WHITE);
         let blank = pm.clone();
-        let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         crate::canvas::with_canvas(&mut pm, |c| legend(c, Rect::from_xywh(0.0, 0.0, 200.0, 47.0).unwrap(), &map, ("", 1), None, opts, 1.0));
         assert!(pm.data() == blank.data());
         // A size no page could hold stays a size a legend can take.
         let mut map = point_legend_map(|l| l.renderer = rustgis_map::Renderer::Single(s(f32::MAX)));
-        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, false, &[]).unwrap();
+        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, false, (&[], &NO_LABELS)).unwrap();
         assert!(w.is_finite() && h.is_finite(), "{w} × {h} mm");
     }
 
@@ -4136,7 +4212,7 @@ mod tests {
         };
         let map = point_legend_map(|l| l.renderer = rustgis_map::Renderer::Single(s));
         let mut c = Canvas::recording(2100, 2100).unwrap();
-        let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         legend(&mut c, Rect::from_xywh(0.5, 0.5, 2099.0, 2099.0).unwrap(), &map, ("", 1), None, opts, 1.0);
         let (_, _, items) = c.into_drawing().unwrap().finish();
         let mut pm = Pixmap::new(2100, 2100).unwrap();
@@ -4262,7 +4338,7 @@ mod tests {
             });
             let mut pm = Pixmap::new(2100, 2100).unwrap();
             pm.fill(tiny_skia::Color::WHITE);
-            let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+            let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
             crate::canvas::with_canvas(&mut pm, |c| {
                 legend(c, Rect::from_xywh(0.0, 0.0, 2100.0, 2100.0).unwrap(), &map, ("", 1), None, opts, 1.0)
             });
@@ -4291,7 +4367,7 @@ mod tests {
         });
         let mut pm = Pixmap::new(300, 300).unwrap();
         pm.fill(tiny_skia::Color::WHITE);
-        let opts = LegendOptions { hide_other: false, exclude: &[], scale: 1e6 };
+        let opts = LegendOptions { hide_other: false, exclude: &[], labels: &NO_LABELS, scale: 1e6 };
         crate::canvas::with_canvas(&mut pm, |c| {
             legend(c, Rect::from_xywh(-50.0, -50.0, 2100.0, 2100.0).unwrap(), &map, ("", 1), None, opts, 1.0)
         });
@@ -4323,7 +4399,7 @@ mod tests {
             };
         });
         // The layer's name over the class: a row of 15 and one of 48, 6 + 48 + 6 before its label.
-        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, true, &[]).unwrap();
+        let [(w, h), ..] = legend_sizes_mm(&mut map, 1e6, true, true, (&[], &NO_LABELS)).unwrap();
         assert!((h - f64::from(LEGEND_ROW + 48.0) * mm).abs() < 1e-6, "{h} mm");
         assert!((w - f64::from(48.0 + 12.0 + text::measure("a", 8.5, false)) * mm).abs() < 1e-4, "{w} mm");
     }
diff --git a/crates/render/src/stream_tests.rs b/crates/render/src/stream_tests.rs
index 3276be7640..7135971cef 100644
--- a/crates/render/src/stream_tests.rs
+++ b/crates/render/src/stream_tests.rs
@@ -543,7 +543,15 @@ fn layout_export_keeps_all_drawn_legend_classes() {
     page.add(
         "legend",
         (90.0, 0.0, 45.0, 95.0),
-        ElementKind::Legend { frame, title: "classes".into(), all_classes: false, hide_other: false, exclude: vec![], columns: 1 },
+        ElementKind::Legend {
+            frame,
+            title: "classes".into(),
+            all_classes: false,
+            hide_other: false,
+            exclude: vec![],
+            columns: 1,
+            labels: Default::default(),
+        },
     );
     let expected = layout::render(&page, &mut [base.clone()], 96.0, &layout::PageInfo::default()).unwrap();
     for size in [1, 3, 20] {
diff --git a/crates/render/src/svg.rs b/crates/render/src/svg.rs
index 8a73a58055..33beb26f7c 100644
--- a/crates/render/src/svg.rs
+++ b/crates/render/src/svg.rs
@@ -350,7 +350,15 @@ mod tests {
         layout.add(
             "Legend",
             (10.0, 10.0, 40.0, 30.0),
-            ElementKind::Legend { frame, title: "Map legend".into(), all_classes: true, hide_other: false, exclude: vec![], columns: 1 },
+            ElementKind::Legend {
+                frame,
+                title: "Map legend".into(),
+                all_classes: true,
+                hide_other: false,
+                exclude: vec![],
+                columns: 1,
+                labels: Default::default(),
+            },
         );
         assert_eq!(picture_dpi(&layout, 600.0, |e| !written_as_svg(e)), 600.0);
         // A frame and an inset filling an A0 page that is already drawn at its pixel limit.
@@ -381,7 +389,15 @@ mod tests {
         let legend = layout.add(
             "Legend",
             (10.0, 10.0, 40.0, 30.0),
-            ElementKind::Legend { frame, title: "Map legend".into(), all_classes: true, hide_other: false, exclude: vec![], columns: 1 },
+            ElementKind::Legend {
+                frame,
+                title: "Map legend".into(),
+                all_classes: true,
+                hide_other: false,
+                exclude: vec![],
+                columns: 1,
+                labels: Default::default(),
+            },
         );
         let info = PageInfo::default();
         let (svg, pictured) = layout_svg(&layout, &mut maps, 72.0, &info).unwrap();
diff --git a/docs/user-guide/layouts.md b/docs/user-guide/layouts.md
index 3fd9bc4ba8..14be733910 100644
--- a/docs/user-guide/layouts.md
+++ b/docs/user-guide/layouts.md
@@ -200,6 +200,19 @@ Layouts open as tabs next to the maps; while one is open, its groups lead the Pu
     (a mask, a highlight, a basemap-like layer). Scripts give the same with
     `"exclude": ["Graticule"]` on `layout.addElement` or `layout.update` (`[]` lists every layer
     again); a renamed layer stays left out.
+  - **Labels**: a legend can show a layer under a label instead of its name, so a layer named for
+    a plugin or a script (`BrasilData: Setores censitários 2022 (MG)`, `setores_mg_2022_clip`)
+    reads well on the page while it keeps its name everywhere else. Scripts give
+    `"labels": {"BrasilData: Setores censitários 2022 (MG)": "Setores censitários"}` on
+    `layout.addElement` or `layout.update`: the layer by its name (any case), as `exclude` names
+    it, and a layer the map hasn't is refused. Each entry replaces that layer's label and leaves
+    the others; `null` or a blank label shows the layer's name again, and `{}` every layer's. The
+    label goes in the layer's row, or over its classes; a WMS or WMTS layer's goes over its
+    picture. It is up to 200 characters, and the legend measures it, not the name, so sizing a
+    legend to its content and the warnings on its fit follow the label. Two legends can label a
+    layer differently (in two languages, say). A renamed layer keeps its label; a removed one's
+    is dropped, so a later layer of that name isn't labelled unasked. Labels are saved with the
+    layout, in the project and in a `.rgislayout` file.
 - **Colorbar**: the colour scale of a raster layer in the frame's map, as the map draws it (its
   stretch, colour ramp and enhancement): a gradient bar for a stretch or a tinted hillshade,
   steps labelled at their breaks for Classify, and a block per value for Unique Values and colour

From 8795cb7d4c0391299af91f37aa2797464a6ccf34 Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 15:31:09 -0300
Subject: [PATCH 2/7] fix(layout): refuse a legend label over 200 characters,
 and name labels in the import notice (#1654)

- layout.addElement and layout.update refuse a label longer than a
  legend keeps instead of cutting it (AGENTS.md "Never silent").
- The notice for layout elements cut on reading now names legend
  labels, which Layout::sanitize also cuts.
- Tests: a 201-character label refused, a 200-character one kept
  whole; an imported layout file with a long label cut, with the
  notice; no notice for a clean file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/layout.rs |  8 ++++++--
 crates/engine/src/project.rs    |  2 +-
 crates/engine/src/tests.rs      | 29 +++++++++++++++++++++++++----
 crates/map/src/layout.rs        |  4 ++--
 docs/user-guide/layouts.md      |  2 +-
 5 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/crates/engine/src/cmd/layout.rs b/crates/engine/src/cmd/layout.rs
index f210662417..b7b1a61821 100644
--- a/crates/engine/src/cmd/layout.rs
+++ b/crates/engine/src/cmd/layout.rs
@@ -96,7 +96,7 @@ pub fn commands() -> Vec<C> {
             r##"{"layout"?, "kind": "northArrow"|"scaleBar"|"legend"|"colorbar"|"text"|"dynamicText"|"picture"|"table"|"chart"|"rectangle" (a neatline framing the page unless any of x, y, w, h is given)|"ellipse"|"circle"|"line"|"arrow"|"extentIndicator"|"grid", "frame"?: element id (default: the first map frame), "of"?: frame id (extentIndicator, which also takes "color" and "width" in points, default red and 2), "text"?, "size"?, "color"?: "#RRGGBB"|"#RRGGBBAA" (text, dynamicText, line, arrow, rectangle, ellipse, circle: its outline; extentIndicator; grid; scaleBar; refused for other kinds), "bold"?: bool (text), "italic"?: bool, "align"?: "left"|"center"|"right", "letterSpacing"?: points, -5 to 50 (text, dynamicText), "font"?: "sans"|"serif"|an installed font family's name, as labels.fonts lists them (text, dynamicText; a family not installed here is drawn in its fallback, and a serif where none is installed in the sans, with a warning; refused for other kinds), "fallback"?: "sans"|"serif" (a named font's, where it isn't installed; default its own class, else sans), "title"?: legend title (default "Legend"), "allClasses"?: bool (legend: every class, not only those the frame draws), "hideOther"?: bool (legend: leave out <all other values>), "exclude"?: [layer names] (legend: layers it leaves out though the map draws them), "columns"?: 1..3 (legend: the columns its rows are laid in; default 1), "orientation"?: "horizontal"|"vertical" (colorbar), "ticks"?: 2..21 (colorbar: labelled values, ends included), "tickSide"?: "below"|"above"|"right"|"left" (colorbar), "reverse"?: bool (colorbar: high values first), "fill"?: "#RRGGBBAA" (rectangle, ellipse, circle, northArrow; scaleBar: the alternating bar's light divisions, default white; refused for other kinds), "width"?: outline width in points (rectangle, ellipse, circle; 0 for none) or line width in points (line, grid), "radius"?: mm, 0 to 50 (rectangle: rounded corners), "dir"?: "horizontal"|"vertical"|"falling"|"rising" (line), "head"?: "none"|"end"|"start"|"both" (line; default "end" for an arrow), "angle"?: degrees anticlockwise from pointing right, centred on the page unless x or y is given (line, arrow; it sets the box and the direction, so w, h and dir are not used with it), "length"?: mm (line, arrow), "image"?: base64, "path"?: picture file, "layer"?: (table, chart; colorbar: a raster layer, default the top visible one), "field"?, "label"?, "rows"?, "step"?: degrees, or a measured grid's units (metres) (0 picks one), "type"?: "graticule" (latitudes and longitudes, default) | "measured" (eastings and northings in a projected system, as ArcGIS Pro's measured grid), "crs"?: a measured grid's coordinate system: EPSG:25832, WKT or a PROJ string ("" or none: the map's when projected, else the UTM zone at the frame's centre), "short"?: bool (a measured grid's labels as their kilometres' last two digits, 43 for 543000), "labels"?: bool (grid) | {"<layer>": "<label>"} (legend: what it shows instead of a layer's name, as in layout.update; a layer the map hasn't is refused), "style"?: "lines"|"ticks"|"linesAndTicks" (grid) or "classic"|"compass"|"triangle"|"star" (northArrow) or "alternating"|"stepped"|"line" (scaleBar), "tickLength"?: mm, "format"?: "decimal"|"dms", "hemisphere"?: bool (N/S/E/W rather than a sign), "edges"?: ["top","bottom","left","right"] (labelled edges), "labelOrientation"?: "horizontal"|"vertical", "off"?: bool (grid; options not given keep the grid's), "outline"?: "#RRGGBB" (northArrow, or a rectangle's, ellipse's or circle's outline instead of color; refused for other kinds), "units"?: "auto"|"kilometers"|"meters"|"miles"|"feet", "divisions"?: 1..10 (scaleBar, whose "color" is its lines, dark divisions and labels, default #222222), "x"?, "y"?, "w"?, "h"?: mm}"##,
         ),
         C::new("layout.update", "Element Properties", "Publish › Element", update).inputs(update_inputs).roles(&[]).effects(crate::policy::Effects::NONE.with(crate::policy::Effect::Files)).params(
-            r##"{"layout"?, "element": id, "x"?, "y"?, "w"?, "h"?: mm, "name"?, "visible"?, "locked"?: bool (a locked element takes no other change until unlocked; "locked": false unlocks it and may come with changes), "text"?, "size"?, "color"? (text, line, rectangle, ellipse: its outline; scaleBar: its lines, dark divisions and labels; refused for other elements), "bold"?, "italic"?, "align"?, "letterSpacing"?, "font"?: "sans"|"serif"|an installed font family's name, "fallback"?: "sans"|"serif" (text, as in layout.addElement; refused for other elements), "title"?, "allClasses"?: bool (legend), "hideOther"?: bool (legend), "exclude"?: [layer names] (legend; [] lists every layer again), "labels"?: {"<layer>": "<label>"|null} (legend: what it shows instead of a layer's name, up to 200 characters; each entry replaces that layer's label, null or "" shows its name again, {} every layer's; a layer the map hasn't is refused), "columns"?: 1..3 (legend), "orientation"?, "ticks"?, "tickSide"?, "reverse"?: (colorbar), "style"?: (northArrow, scaleBar), "fill"?, "outline"? (northArrow, rectangle, ellipse, and a scaleBar's fill; refused for other elements; for a rectangle or ellipse, color sets it when outline is not given; a scaleBar's fill is the alternating bar's light divisions), "radius"?: mm (rectangle: rounded corners), "width"?: points (rectangle, ellipse, line), "dir"?, "head"?, "angle"?, "length"? (line: turned or sized about its centre, then moved by any x or y; dir does not come with angle or length), "units"?, "divisions"? (scaleBar), "map"?, "scale"?, "center"?: [lon, lat], "bearing"?: degrees clockwise from north, "pitch"?: degrees of tilt (0 to 85), "grid"?: {grid options as in layout.addElement} | false (map frame), "extentIndicator"?: {"color"?, "width"?: points} | false (map frame: its extent indicator's style, or removes it), "layer"?: (colorbar: "" for the top visible raster), "field"?, "rows"?}"##,
+            r##"{"layout"?, "element": id, "x"?, "y"?, "w"?, "h"?: mm, "name"?, "visible"?, "locked"?: bool (a locked element takes no other change until unlocked; "locked": false unlocks it and may come with changes), "text"?, "size"?, "color"? (text, line, rectangle, ellipse: its outline; scaleBar: its lines, dark divisions and labels; refused for other elements), "bold"?, "italic"?, "align"?, "letterSpacing"?, "font"?: "sans"|"serif"|an installed font family's name, "fallback"?: "sans"|"serif" (text, as in layout.addElement; refused for other elements), "title"?, "allClasses"?: bool (legend), "hideOther"?: bool (legend), "exclude"?: [layer names] (legend; [] lists every layer again), "labels"?: {"<layer>": "<label>"|null} (legend: what it shows instead of a layer's name, up to 200 characters, a longer one is refused; each entry replaces that layer's label, null or "" shows its name again, {} every layer's; a layer the map hasn't is refused), "columns"?: 1..3 (legend), "orientation"?, "ticks"?, "tickSide"?, "reverse"?: (colorbar), "style"?: (northArrow, scaleBar), "fill"?, "outline"? (northArrow, rectangle, ellipse, and a scaleBar's fill; refused for other elements; for a rectangle or ellipse, color sets it when outline is not given; a scaleBar's fill is the alternating bar's light divisions), "radius"?: mm (rectangle: rounded corners), "width"?: points (rectangle, ellipse, line), "dir"?, "head"?, "angle"?, "length"? (line: turned or sized about its centre, then moved by any x or y; dir does not come with angle or length), "units"?, "divisions"? (scaleBar), "map"?, "scale"?, "center"?: [lon, lat], "bearing"?: degrees clockwise from north, "pitch"?: degrees of tilt (0 to 85), "grid"?: {grid options as in layout.addElement} | false (map frame), "extentIndicator"?: {"color"?, "width"?: points} | false (map frame: its extent indicator's style, or removes it), "layer"?: (colorbar: "" for the top visible raster), "field"?, "rows"?}"##,
         ),
         C::new("layout.guides", "Guides", "Publish › Page Setup", guides).inputs(object_inputs).roles(&[]).effects(crate::policy::Effects::NONE).params(
             r#"{"layout"?, "x"?: [mm] (vertical guides, from the page's left edge), "y"?: [mm] (horizontal guides, from its top edge), "clear"?: bool (remove every guide first)}"#,
@@ -2969,7 +2969,11 @@ fn legend_labels(
         let label = match label {
             Value::Null => None,
             Value::String(t) if t.trim().is_empty() => None,
-            Value::String(t) => Some(t.chars().take(MAX_LEGEND_LABEL_CHARS).collect()),
+            // Refused rather than cut, so a label is never shown other than as given.
+            Value::String(t) if t.chars().count() > MAX_LEGEND_LABEL_CHARS => {
+                return Err(format!("a legend's label is at most {MAX_LEGEND_LABEL_CHARS} characters ('{n}' has {})", t.chars().count()));
+            }
+            Value::String(t) => Some(t.clone()),
             _ => return Err(LABELS_SHAPE.into()),
         };
         let name = legend_layer(map, n)?;
diff --git a/crates/engine/src/project.rs b/crates/engine/src/project.rs
index 795aa6c7fd..de87a8c6bc 100644
--- a/crates/engine/src/project.rs
+++ b/crates/engine/src/project.rs
@@ -1738,7 +1738,7 @@ pub(crate) fn layout_notices(
     let cut = total(|r| r.elements_cut);
     if cut > 0 {
         notices.push(format!(
-            "{name}: {cut} layout element(s) with a name, text, polygon points or legend exclusions cut to their limits {when} (in {})",
+            "{name}: {cut} layout element(s) with a name, text, polygon points, legend exclusions or legend labels cut to their limits {when} (in {})",
             layout_names(repairs, |r| r.elements_cut)
         ));
     }
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 3cfa360c0d..bd1aa7151f 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29590,10 +29590,17 @@ fn legends_label_layers() {
         s.project.layouts[0].element(frame).map(|e| &e.kind),
         Some(ElementKind::MapFrame { grid: Some(g), .. }) if !g.labels
     ));
-    // A long label is cut to its length.
-    let long = "x".repeat(rustgis_map::layout::MAX_LEGEND_LABEL_CHARS + 50);
-    s.run("layout.update", &json!({"element": plain, "labels": {"Countries": long}})).unwrap();
-    assert_eq!(labels(&s, plain)[0].1.chars().count(), rustgis_map::layout::MAX_LEGEND_LABEL_CHARS);
+    // A label longer than a legend keeps is refused, not cut, and changes nothing; one at the
+    // limit is kept whole.
+    let before = labels(&s, plain);
+    let long = "x".repeat(rustgis_map::layout::MAX_LEGEND_LABEL_CHARS + 1);
+    let err = s.run("layout.update", &json!({"element": plain, "labels": {"Countries": long}})).unwrap_err();
+    assert!(err.contains("at most 200 characters") && err.contains("has 201"), "{err}");
+    assert_eq!(labels(&s, plain), before);
+    let full = "é".repeat(rustgis_map::layout::MAX_LEGEND_LABEL_CHARS);
+    s.run("layout.update", &json!({"element": plain, "labels": {"Countries": full}})).unwrap();
+    assert_eq!(labels(&s, plain)[0].1, full);
+    s.run("layout.update", &json!({"element": plain, "labels": {"Countries": null}})).unwrap();
     // Kept through a saved project, and a layout file.
     let dir = std::env::temp_dir().join(format!("rustgis-legend-labels-{}", std::process::id()));
     std::fs::create_dir_all(&dir).unwrap();
@@ -29608,6 +29615,20 @@ fn legends_label_layers() {
         s.project.layouts[1].element(id).map(|e| &e.kind),
         Some(ElementKind::Legend { labels, .. }) if labels.get("Rivers").is_some_and(|l| l == "Rios principais")
     ));
+    let cut_notice =
+        |s: &Session, from: usize| s.notices[from..].iter().filter(|n| n.text.contains("legend labels cut to their limits")).count();
+    assert_eq!(cut_notice(&s, 0), 0, "nothing was cut");
+    // A layout file with a label longer than a legend keeps is read with it cut, and says so.
+    let mut text: Value = serde_json::from_str(&std::fs::read_to_string(&file).unwrap()).unwrap();
+    let legend = text["elements"].as_array_mut().unwrap().iter_mut().find(|e| e["id"] == json!(id)).unwrap();
+    legend["kind"]["Legend"]["labels"]["Rivers"] = json!("x".repeat(rustgis_map::layout::MAX_LEGEND_LABEL_CHARS + 50));
+    let mark = s.notices.len();
+    s.run("layout.import", &json!({"text": text.to_string()})).unwrap();
+    assert_eq!(cut_notice(&s, mark), 1);
+    assert!(matches!(
+        s.project.layouts[2].element(id).map(|e| &e.kind),
+        Some(ElementKind::Legend { labels, .. }) if labels["Rivers"].chars().count() == rustgis_map::layout::MAX_LEGEND_LABEL_CHARS
+    ));
     std::fs::remove_dir_all(&dir).ok();
     // (The imported layout is the active one now; the rest goes to the first.)
     // The label follows its layer renamed, and goes with it removed, so a later layer of that
diff --git a/crates/map/src/layout.rs b/crates/map/src/layout.rs
index 7a9e7c8a5f..e5ed74a3a5 100644
--- a/crates/map/src/layout.rs
+++ b/crates/map/src/layout.rs
@@ -1461,8 +1461,8 @@ impl Layout {
 pub struct LayoutRepairs {
     /// Elements kept with a value brought into range, a new id, or a reference cleared.
     pub elements_adjusted: usize,
-    /// Elements with a name, text, polygon points or legend exclusions cut to their limits (the
-    /// same element may count as adjusted too).
+    /// Elements with a name, text, polygon points, legend exclusions or legend labels cut to their
+    /// limits (the same element may count as adjusted too).
     pub elements_cut: usize,
     /// Elements removed: beyond the 500 a layout holds, or tied to a map frame it doesn't have.
     pub elements_removed: usize,
diff --git a/docs/user-guide/layouts.md b/docs/user-guide/layouts.md
index 14be733910..abdef08a80 100644
--- a/docs/user-guide/layouts.md
+++ b/docs/user-guide/layouts.md
@@ -208,7 +208,7 @@ Layouts open as tabs next to the maps; while one is open, its groups lead the Pu
     it, and a layer the map hasn't is refused. Each entry replaces that layer's label and leaves
     the others; `null` or a blank label shows the layer's name again, and `{}` every layer's. The
     label goes in the layer's row, or over its classes; a WMS or WMTS layer's goes over its
-    picture. It is up to 200 characters, and the legend measures it, not the name, so sizing a
+    picture. It is up to 200 characters (a longer one is refused), and the legend measures it, not the name, so sizing a
     legend to its content and the warnings on its fit follow the label. Two legends can label a
     layer differently (in two languages, say). A renamed layer keeps its label; a removed one's
     is dropped, so a later layer of that name isn't labelled unasked. Labels are saved with the

From d8f94a7fc0bf28754399ce17fb56a2f860af23d5 Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 16:14:17 -0300
Subject: [PATCH 3/7] fix(layout): a layout read from a file keeps one label
 per layer (#1654)

Layout::sanitize now keeps one of two spellings of a layer's name in a
legend's labels (the first in order) and counts the other as cut, so
the import notice reports it, as a command refuses both spellings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/tests.rs | 12 ++++++++++++
 crates/map/src/layout.rs   |  4 ++++
 2 files changed, 16 insertions(+)

diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index bd1aa7151f..17630b5b0b 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29629,6 +29629,18 @@ fn legends_label_layers() {
         s.project.layouts[2].element(id).map(|e| &e.kind),
         Some(ElementKind::Legend { labels, .. }) if labels["Rivers"].chars().count() == rustgis_map::layout::MAX_LEGEND_LABEL_CHARS
     ));
+    // One with two spellings of a layer keeps the first in order, as a command keeps one, and
+    // says so.
+    let legend = text["elements"].as_array_mut().unwrap().iter_mut().find(|e| e["id"] == json!(id)).unwrap();
+    legend["kind"]["Legend"]["labels"] = json!({"Rivers": "Rios", "rivers": "rios", "Lakes": "Lagos"});
+    let mark = s.notices.len();
+    s.run("layout.import", &json!({"text": text.to_string()})).unwrap();
+    assert_eq!(cut_notice(&s, mark), 1);
+    assert!(matches!(
+        s.project.layouts[3].element(id).map(|e| &e.kind),
+        Some(ElementKind::Legend { labels, .. })
+            if labels.iter().map(|(n, l)| (n.as_str(), l.as_str())).collect::<Vec<_>>() == [("Lakes", "Lagos"), ("Rivers", "Rios")]
+    ));
     std::fs::remove_dir_all(&dir).ok();
     // (The imported layout is the active one now; the rest goes to the first.)
     // The label follows its layer renamed, and goes with it removed, so a later layer of that
diff --git a/crates/map/src/layout.rs b/crates/map/src/layout.rs
index e5ed74a3a5..d917aebaab 100644
--- a/crates/map/src/layout.rs
+++ b/crates/map/src/layout.rs
@@ -1382,6 +1382,10 @@ impl Layout {
                     // one shows the name, as it would without.
                     labels.retain(|_, label| !label.trim().is_empty());
                     let labelled = labels.len();
+                    // One label per layer, as a command keeps: of two spellings of a name (any
+                    // case), the first in order stays and the other is cut.
+                    let mut seen = std::collections::HashSet::new();
+                    labels.retain(|name, _| seen.insert(name.to_ascii_lowercase()));
                     while labels.len() > MAX_LEGEND_LABELS {
                         labels.pop_last();
                     }

From f0a74f88d0c419b369a3a01957c71d45adfc8fbc Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 16:39:16 -0300
Subject: [PATCH 4/7] fix(layout): refuse labels of any value on elements that
 aren't legends (#1654)

layout.addElement and layout.update refused "labels" on another kind
of element only when it was an object; a string, list or bool was
left unread. Now any non-null value is refused there, as "exclude"
and "columns" are, and a grid's "labels" that isn't true or false is
refused with its own message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/layout.rs | 12 ++++++++----
 crates/engine/src/tests.rs      |  9 +++++++++
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/crates/engine/src/cmd/layout.rs b/crates/engine/src/cmd/layout.rs
index b7b1a61821..9dffe23a1e 100644
--- a/crates/engine/src/cmd/layout.rs
+++ b/crates/engine/src/cmd/layout.rs
@@ -2354,9 +2354,12 @@ fn add_element(s: &mut Session, p: &Value) -> CmdResult {
     if kind != "legend" && p.get("columns").is_some_and(|v| !v.is_null()) {
         return Err(ONLY_LEGEND_COLUMNS.into());
     }
-    // (A grid's "labels" is a bool: only an object is a legend's.)
-    if kind != "legend" && p.get("labels").is_some_and(Value::is_object) {
-        return Err(ONLY_LEGEND_LABELS.into());
+    // A grid's "labels" is a bool and a legend's an object (read with it); on any other kind, or as
+    // anything else on a grid, it is refused rather than left unread.
+    match p.get("labels").filter(|v| !v.is_null()) {
+        Some(v) if kind == "grid" && !v.is_boolean() => return Err("a grid's labels is true or false".into()),
+        Some(_) if kind != "legend" && kind != "grid" => return Err(ONLY_LEGEND_LABELS.into()),
+        _ => {}
     }
     // A family is a text's: refused elsewhere, as a legend's left-out layers are, so a script
     // doesn't take it as applied.
@@ -3252,7 +3255,8 @@ fn update(s: &mut Session, p: &Value) -> CmdResult {
                 Some(given) => Some(with_labels(labels, given)?),
                 None => None,
             },
-            _ if p.get("labels").is_some_and(Value::is_object) => return Err(ONLY_LEGEND_LABELS.into()),
+            // (A map frame's grid takes its labels under "grid".)
+            _ if p.get("labels").is_some_and(|v| !v.is_null()) => return Err(ONLY_LEGEND_LABELS.into()),
             _ => None,
         }
     };
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 17630b5b0b..ddcb40a1cd 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29584,6 +29584,15 @@ fn legends_label_layers() {
     let title = s.project.layouts[0].elements.iter().find(|e| e.name == "Title").unwrap().id;
     assert!(s.run("layout.update", &json!({"element": title, "labels": {"Rivers": "Rios"}})).unwrap_err().contains("only legends"));
     assert!(s.run("layout.addElement", &json!({"kind": "scaleBar", "labels": {"Rivers": "Rios"}})).unwrap_err().contains("only legends"));
+    // Any other value is refused too, rather than left unread, and nothing is added.
+    let count = s.project.layouts[0].elements.len();
+    for v in [json!("Rivers"), json!(["Rivers"]), json!(true)] {
+        assert!(s.run("layout.update", &json!({"element": title, "labels": v})).unwrap_err().contains("only legends"), "{v}");
+        assert!(s.run("layout.addElement", &json!({"kind": "scaleBar", "labels": v})).unwrap_err().contains("only legends"), "{v}");
+    }
+    let err = s.run("layout.addElement", &json!({"kind": "grid", "labels": "no"})).unwrap_err();
+    assert!(err.contains("a grid's labels is true or false"), "{err}");
+    assert_eq!(s.project.layouts[0].elements.len(), count);
     // A grid's own "labels" (a bool) is still its.
     let frame = s.run("layout.addElement", &json!({"kind": "grid", "labels": false})).unwrap()["element"].as_u64().unwrap() as u32;
     assert!(matches!(

From 3f959e51e1376756ab9d766b40b5e9f9f7e5385d Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 17:15:54 -0300
Subject: [PATCH 5/7] fix(layout): say when a renamed layer loses its legend
 label (#1654)

A layer renamed onto a name another layer has is listed under that
one's label (or name), so its own label is dropped. That is now said:
"'Hidrografia', renamed 'Cities', lost its label in 4 legend(s):
another layer is called 'Cities', and a legend labels layers by name".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/layer.rs | 23 ++++++++++++++++++-----
 crates/engine/src/tests.rs     |  6 ++++++
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/crates/engine/src/cmd/layer.rs b/crates/engine/src/cmd/layer.rs
index 73db4457a9..5b7e4dd802 100644
--- a/crates/engine/src/cmd/layer.rs
+++ b/crates/engine/src/cmd/layer.rs
@@ -4791,8 +4791,8 @@ fn add_sample(s: &mut Session, p: &Value) -> CmdResult {
 /// that name isn't left out or labelled unasked. Called once the layer is renamed or gone: while
 /// another layer still bears `old` (names may repeat), the legends keep it for that one. Renamed
 /// onto the name of another layer a legend lists, the layer is listed with it rather than taking
-/// that one out, and under that one's label rather than giving it its own. A WMS or WMTS layer's
-/// name counts as a layer's: legends list those too.
+/// that one out, and under that one's label rather than giving it its own, which is said. A WMS or
+/// WMTS layer's name counts as a layer's: legends list those too.
 pub(crate) fn legends_follow_layer(s: &mut Session, old: &str, new: Option<&str>) {
     let named = |s: &Session, n: &str| {
         let m = s.map();
@@ -4803,6 +4803,7 @@ pub(crate) fn legends_follow_layer(s: &mut Session, old: &str, new: Option<&str>
     }
     let shared = new.is_some_and(|n| named(s, n) > 1);
     let map = s.map().name.clone();
+    let mut unlabelled = 0usize;
     for layout in &mut s.project.layouts {
         let frames: Vec<u32> = layout
             .elements
@@ -4818,9 +4819,13 @@ pub(crate) fn legends_follow_layer(s: &mut Session, old: &str, new: Option<&str>
                 // bears that name, whose label (or none) the renamed layer then shares.
                 let keys: Vec<String> = labels.keys().filter(|n| n.eq_ignore_ascii_case(old)).cloned().collect();
                 let label = keys.iter().filter_map(|k| labels.remove(k)).last();
-                if let (Some(n), Some(l), false) = (new, label, shared) {
-                    labels.retain(|x, _| !x.eq_ignore_ascii_case(n));
-                    labels.insert(n.to_string(), l);
+                match (new, label, shared) {
+                    (Some(n), Some(l), false) => {
+                        labels.retain(|x, _| !x.eq_ignore_ascii_case(n));
+                        labels.insert(n.to_string(), l);
+                    }
+                    (Some(_), Some(_), true) => unlabelled += 1,
+                    _ => {}
                 }
                 match new {
                     // Another layer the legend lists bears the new name: carrying the exclusion
@@ -4845,6 +4850,14 @@ pub(crate) fn legends_follow_layer(s: &mut Session, old: &str, new: Option<&str>
             }
         }
     }
+    // The text given for the layer goes while the layer stays: said. (A removed layer's goes
+    // with its row.)
+    if let Some(n) = new.filter(|_| unlabelled > 0) {
+        s.notify(
+            format!("'{old}', renamed '{n}', lost its label in {unlabelled} legend(s): another layer is called '{n}', and a legend labels layers by name"),
+            false,
+        );
+    }
 }
 
 /// Removes the layers `ids` from the active map, and legends that left them out forget them, as
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index ddcb40a1cd..9f1a51aa94 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29654,6 +29654,8 @@ fn legends_label_layers() {
     // (The imported layout is the active one now; the rest goes to the first.)
     // The label follows its layer renamed, and goes with it removed, so a later layer of that
     // name isn't labelled unasked.
+    let lost = |s: &Session, from: usize| s.notices[from..].iter().filter(|n| n.text.contains("lost its label")).count();
+    let mark = s.notices.len();
     s.run("layer.rename", &json!({"layer": "Rivers", "name": "Hidrografia"})).unwrap();
     assert_eq!(labels(&s, id), [pair("Hidrografia", "Rios principais"), pair("Lakes", "Lagos")]);
     s.run("layer.remove", &json!({"layer": "Lakes"})).unwrap();
@@ -29661,6 +29663,10 @@ fn legends_label_layers() {
     // Renamed onto the name of a layer the legend lists, a layer shares that one's label (here
     // none) rather than giving it its own.
     s.run("layer.rename", &json!({"layer": "Hidrografia", "name": "Cities"})).unwrap();
+    // Its label is dropped, and said once for the four legends that had it (this one and the
+    // three layouts imported above); following a rename or a removal is not.
+    assert_eq!(lost(&s, mark), 1);
+    assert!(s.notices[mark..].iter().any(|n| n.text.contains("'Hidrografia', renamed 'Cities', lost its label in 4 legend(s)")));
     assert!(labels(&s, id).is_empty());
     // A WMS or WMTS layer is labelled by name too.
     let wms = json!({"url": "https://maps.example.org/wms/{bbox-epsg-3857}", "name": "Soils", "overlay": true, "legend": "https://maps.example.org/legend.png"});

From 2b98ad1aec3a644ddab0271d06c6d3baf1a15388 Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 17:32:14 -0300
Subject: [PATCH 6/7] fix(layout): say where a map frame's grid labels go, and
 rewrap the labels docs (#1654)

- layout.update with a top-level "labels" on a map frame now says
  where they go ({"grid": {"labels": false}}) instead of "only legends
  label layers".
- docs: the labels bullet wrapped near 100 columns, and it says a
  renamed layer loses its label when another layer has its new name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/layout.rs |  5 ++++-
 crates/engine/src/tests.rs      |  8 ++++++++
 docs/user-guide/layouts.md      | 11 ++++++-----
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/crates/engine/src/cmd/layout.rs b/crates/engine/src/cmd/layout.rs
index 9dffe23a1e..c2ddff6142 100644
--- a/crates/engine/src/cmd/layout.rs
+++ b/crates/engine/src/cmd/layout.rs
@@ -3255,7 +3255,10 @@ fn update(s: &mut Session, p: &Value) -> CmdResult {
                 Some(given) => Some(with_labels(labels, given)?),
                 None => None,
             },
-            // (A map frame's grid takes its labels under "grid".)
+            // A map frame's grid takes its labels under "grid", as its other options: said where.
+            Some(ElementKind::MapFrame { .. }) if p.get("labels").is_some_and(|v| !v.is_null()) => {
+                return Err(r#"a map frame's grid labels go under "grid": {"grid": {"labels": false}}"#.into());
+            }
             _ if p.get("labels").is_some_and(|v| !v.is_null()) => return Err(ONLY_LEGEND_LABELS.into()),
             _ => None,
         }
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 9f1a51aa94..e6074939a6 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29599,6 +29599,14 @@ fn legends_label_layers() {
         s.project.layouts[0].element(frame).map(|e| &e.kind),
         Some(ElementKind::MapFrame { grid: Some(g), .. }) if !g.labels
     ));
+    // On layout.update they go under "grid", and a top-level "labels" there says so.
+    let err = s.run("layout.update", &json!({"element": frame, "labels": true})).unwrap_err();
+    assert!(err.contains(r#"go under "grid""#), "{err}");
+    s.run("layout.update", &json!({"element": frame, "grid": {"labels": true}})).unwrap();
+    assert!(matches!(
+        s.project.layouts[0].element(frame).map(|e| &e.kind),
+        Some(ElementKind::MapFrame { grid: Some(g), .. }) if g.labels
+    ));
     // A label longer than a legend keeps is refused, not cut, and changes nothing; one at the
     // limit is kept whole.
     let before = labels(&s, plain);
diff --git a/docs/user-guide/layouts.md b/docs/user-guide/layouts.md
index abdef08a80..546b583885 100644
--- a/docs/user-guide/layouts.md
+++ b/docs/user-guide/layouts.md
@@ -208,11 +208,12 @@ Layouts open as tabs next to the maps; while one is open, its groups lead the Pu
     it, and a layer the map hasn't is refused. Each entry replaces that layer's label and leaves
     the others; `null` or a blank label shows the layer's name again, and `{}` every layer's. The
     label goes in the layer's row, or over its classes; a WMS or WMTS layer's goes over its
-    picture. It is up to 200 characters (a longer one is refused), and the legend measures it, not the name, so sizing a
-    legend to its content and the warnings on its fit follow the label. Two legends can label a
-    layer differently (in two languages, say). A renamed layer keeps its label; a removed one's
-    is dropped, so a later layer of that name isn't labelled unasked. Labels are saved with the
-    layout, in the project and in a `.rgislayout` file.
+    picture. It is up to 200 characters (a longer one is refused), and the legend measures it, not
+    the name, so sizing a legend to its content and the warnings on its fit follow the label. Two
+    legends can label a layer differently (in two languages, say). A renamed layer keeps its label
+    (not when another layer has its new name, which is said); a removed one's is dropped, so a later
+    layer of that name isn't labelled unasked. Labels are saved with the layout, in the project and
+    in a `.rgislayout` file.
 - **Colorbar**: the colour scale of a raster layer in the frame's map, as the map draws it (its
   stretch, colour ramp and enhancement): a gradient bar for a stretch or a tinted hillshade,
   steps labelled at their breaks for Classify, and a block per value for Unique Values and colour

From a09323d1a0510a244bf28edf38f592468ad5397c Mon Sep 17 00:00:00 2001
From: elpidioassinaturas <elpidiofilho@gmail.com>
Date: Tue, 10 Nov 2026 18:09:38 -0300
Subject: [PATCH 7/7] fix(layout): a legend given labels says when they don't
 fit its box (#1654)

layout.addElement checked a legend's fit only when "columns" was
given, and layout.update only for a legend in columns. A legend given
labels is now checked in one column too, added or changed, so a label
wider than its box says that its end is left out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/layout.rs |  9 +++++++--
 crates/engine/src/tests.rs      | 29 +++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/layout.rs b/crates/engine/src/cmd/layout.rs
index c2ddff6142..94562a9649 100644
--- a/crates/engine/src/cmd/layout.rs
+++ b/crates/engine/src/cmd/layout.rs
@@ -2595,7 +2595,10 @@ fn add_element(s: &mut Session, p: &Value) -> CmdResult {
     };
     let l = s.project.layouts.get_mut(i).ok_or("no layout")?;
     let id = l.add(name, rect, k);
-    if p.get("columns").is_some_and(|v| !v.is_null()) {
+    // In columns, or with labels of its own (which may be wider than its box), it says what it
+    // loses in its box.
+    let labelled = kind == "legend" && p.get("labels").is_some_and(|v| !v.is_null());
+    if p.get("columns").is_some_and(|v| !v.is_null()) || labelled {
         say_legend_fit(s, i, id);
     }
     let mut out = json!({"element": id});
@@ -3423,7 +3426,9 @@ fn update(s: &mut Session, p: &Value) -> CmdResult {
         || b(p, "hideOther").is_some()
         || p.get("exclude").is_some_and(|v| !v.is_null())
         || p.get("labels").is_some_and(|v| !v.is_null());
-    if new_columns.is_some() || (in_columns && refitted) {
+    // Labels given are told in one column too: a label is text chosen for the box.
+    let labelled = matches!(&e.kind, ElementKind::Legend { .. }) && p.get("labels").is_some_and(|v| !v.is_null());
+    if new_columns.is_some() || (in_columns && refitted) || labelled {
         say_legend_fit(s, li, id);
     }
     if let Some(text) = p.get("grid").and_then(|grid| grid.get("crs")).and_then(Value::as_str) {
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index e6074939a6..f1d1532a25 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -29689,6 +29689,35 @@ fn legends_label_layers() {
     assert!(!serde_json::to_string(&s.project.layouts[0].element(id).unwrap()).unwrap().contains("labels"));
 }
 
+/// A legend given labels says when they don't fit its box, added or changed, in one column too
+/// (#1654); labels that fit say nothing.
+#[test]
+fn a_legends_labels_say_when_they_dont_fit() {
+    let mut s = Session::new(sample::world_project());
+    s.run("layout.new", &json!({"name": "Rótulos"})).unwrap();
+    let said = |s: &Session, mark: u64| s.notices_since(mark).iter().map(|n| n.text.clone()).collect::<Vec<_>>().join(" | ");
+    let cut = "the ends of long labels are left out";
+    let box_ = json!({"kind": "legend", "x": 10, "y": 10, "w": 150, "h": 180});
+    let with = |labels: Value| {
+        let mut p = box_.clone();
+        p["labels"] = labels;
+        p
+    };
+    let mark = s.notice_mark();
+    let id = s.run("layout.addElement", &with(json!({"Rivers": "Rios"}))).unwrap()["element"].as_u64().unwrap();
+    assert_eq!(said(&s, mark), "");
+    let long = "Rios principais da América do Sul ".repeat(5);
+    let mark = s.notice_mark();
+    s.run("layout.addElement", &with(json!({"Rivers": long}))).unwrap();
+    assert!(said(&s, mark).contains(cut), "{}", said(&s, mark));
+    let mark = s.notice_mark();
+    s.run("layout.update", &json!({"element": id, "labels": {"Rivers": long}})).unwrap();
+    assert!(said(&s, mark).contains(cut), "{}", said(&s, mark));
+    let mark = s.notice_mark();
+    s.run("layout.update", &json!({"element": id, "labels": {"Rivers": null}})).unwrap();
+    assert_eq!(said(&s, mark), "");
+}
+
 /// A point layer of events, one a month through 2015 (two in March), with their dates as text,
 /// epoch milliseconds and years.
 fn timed_events() -> Session {