@diagrammo/dgmo 0.23.0 → 0.25.0

package/src/boxes-and-lines/renderer.ts

@@ -35,7 +35,9 @@ import { ScaleContext } from '../utils/scaling';
 
 // ── Constants (aligned with infra pattern) ─────────────────
 const DIAGRAM_PADDING = 20;
-const NODE_FONT_SIZE = 13;
+// Box labels run smaller than the 13px org/infra use — boxes-and-lines nodes are
+// narrower (~97px), so a smaller label fits more text per line before wrapping.
+const NODE_FONT_SIZE = 11;
 const MIN_NODE_FONT_SIZE = 9;
 const EDGE_LABEL_FONT_SIZE = 11;
 const EDGE_STROKE_WIDTH = 1.5;
@@ -429,7 +431,7 @@ export function renderBoxesAndLines(
   // between a tag group and the metric label, the tag group wins (AC9).
   const matchColorGroup = (v: string): string | null => {
     const lv = v.trim().toLowerCase();
-    if (lv === 'none') return null;
+    if (lv === '' || lv === 'none') return null;
     const tg = parsed.tagGroups.find((g) => g.name.toLowerCase() === lv);
     if (tg) return tg.name;
     if (lv === VALUE_NAME?.toLowerCase()) return VALUE_NAME;
@@ -1087,6 +1089,61 @@ export function renderBoxesAndLines(
           fullText.length > 200 ? fullText.slice(0, 199) + '\u2026' : fullText;
         nodeG.append('title').text(tooltipText);
       }
+    } else if (parsed.showValues && node.value !== undefined) {
+      // Plain node with show-values: label header + thin divider + a
+      // "Metric: value" line below (org/infra card style), instead of a
+      // vertically-centered label with a floating number.
+      const valueLabel = parsed.boxMetric
+        ? `${parsed.boxMetric}: ${node.value}`
+        : String(node.value);
+      // Fixed header zone (not label-height-driven) so the divider sits at a
+      // UNIFORM Y across every box, regardless of label line count (infra/org
+      // both anchor the separator to a constant header height).
+      const headerH = ln.height / 2;
+      const sepY = -ln.height / 2 + headerH;
+      const fitted = fitLabelToHeader(node.label, ln.width, 2);
+      const labelLineH = fitted.fontSize * 1.3;
+      const labelTotalH = fitted.lines.length * labelLineH;
+      const headerCenterY = -ln.height / 2 + headerH / 2;
+      for (let li = 0; li < fitted.lines.length; li++) {
+        nodeG
+          .append('text')
+          .attr('x', 0)
+          .attr(
+            'y',
+            headerCenterY - labelTotalH / 2 + labelLineH / 2 + li * labelLineH
+          )
+          .attr('text-anchor', 'middle')
+          .attr('dominant-baseline', 'central')
+          .attr('font-size', fitted.fontSize)
+          .attr('font-weight', '600')
+          .attr('fill', colors.text)
+          // In-bounds by loop guard.
+          .text(fitted.lines[li]!);
+      }
+      // Thin divider under the title — a tint of the box's own stroke colour
+      // (matches org / infra card separators), not a neutral text line.
+      nodeG
+        .append('line')
+        .attr('x1', -ln.width / 2)
+        .attr('y1', sepY)
+        .attr('x2', ln.width / 2)
+        .attr('y2', sepY)
+        .attr('stroke', colors.stroke)
+        .attr('stroke-opacity', 0.3)
+        .attr('stroke-width', 1);
+      // "Metric: value" centered in the space below the divider.
+      nodeG
+        .append('text')
+        .attr('class', 'bl-node-value')
+        .attr('x', 0)
+        .attr('y', (sepY + ln.height / 2) / 2)
+        .attr('text-anchor', 'middle')
+        .attr('dominant-baseline', 'central')
+        .attr('font-size', VALUE_FONT_SIZE)
+        .attr('fill', colors.text)
+        .attr('opacity', 0.85)
+        .text(valueLabel);
     } else {
       const maxLabelLines = Math.max(
         2,
@@ -1110,56 +1167,46 @@ export function renderBoxesAndLines(
       }
     }
 
-    // ── show-values: print the numeric value as text (opt-in) ──
-    // Independent of the active dimension (a user may want the numbers printed
-    // while a tag group tints). Plain nodes: centered below the label. Described
-    // nodes: a top-right corner badge so it never overflows the full body (R2-6).
-    if (parsed.showValues && node.value !== undefined) {
+    // ── show-values on a DESCRIBED node ── the body is already full, so the
+    // value rides in a top-right corner badge (plain nodes are handled in the
+    // header/divider branch above; a described node with descriptions hidden
+    // also falls through to that plain branch).
+    if (
+      parsed.showValues &&
+      node.value !== undefined &&
+      desc &&
+      desc.length > 0 &&
+      !hideDescriptions
+    ) {
       const valueText = String(node.value);
-      const descShown = !!(desc && desc.length > 0 && !hideDescriptions);
-      if (descShown) {
-        // Corner badge — pill behind the number so it reads over the header.
-        const padX = 6;
-        const padY = 5;
-        const bw = valueText.length * VALUE_FONT_SIZE * CHAR_WIDTH_RATIO + 8;
-        const bh = VALUE_FONT_SIZE + 4;
-        const bx = ln.width / 2 - bw - 4;
-        const by = -ln.height / 2 + 4;
-        nodeG
-          .append('rect')
-          .attr('x', bx)
-          .attr('y', by)
-          .attr('width', bw)
-          .attr('height', bh)
-          .attr('rx', 3)
-          .attr('fill', palette.bg)
-          .attr('opacity', 0.85);
-        nodeG
-          .append('text')
-          .attr('class', 'bl-node-value')
-          .attr('x', bx + bw - padX)
-          .attr('y', by + padY)
-          .attr('text-anchor', 'end')
-          .attr('dominant-baseline', 'central')
-          .attr('font-size', VALUE_FONT_SIZE)
-          .attr('font-weight', '600')
-          .attr('fill', palette.textMuted)
-          .text(valueText);
-      } else {
-        // Plain node: value centered just above the bottom edge.
-        nodeG
-          .append('text')
-          .attr('class', 'bl-node-value')
-          .attr('x', 0)
-          .attr('y', ln.height / 2 - VALUE_FONT_SIZE)
-          .attr('text-anchor', 'middle')
-          .attr('dominant-baseline', 'central')
-          .attr('font-size', VALUE_FONT_SIZE)
-          .attr('font-weight', '600')
-          .attr('fill', colors.text)
-          .attr('opacity', 0.8)
-          .text(valueText);
-      }
+      const padX = 6;
+      const padY = 5;
+      const bw = valueText.length * VALUE_FONT_SIZE * CHAR_WIDTH_RATIO + 8;
+      const bh = VALUE_FONT_SIZE + 4;
+      // Clamp to the left padding so a long value on a narrow node never
+      // slides past the box edge / over the label (R2-6 / AC23).
+      const bx = Math.max(-ln.width / 2 + 4, ln.width / 2 - bw - 4);
+      const by = -ln.height / 2 + 4;
+      nodeG
+        .append('rect')
+        .attr('x', bx)
+        .attr('y', by)
+        .attr('width', bw)
+        .attr('height', bh)
+        .attr('rx', 3)
+        .attr('fill', palette.bg)
+        .attr('opacity', 0.85);
+      nodeG
+        .append('text')
+        .attr('class', 'bl-node-value')
+        .attr('x', bx + bw - padX)
+        .attr('y', by + padY)
+        .attr('text-anchor', 'end')
+        .attr('dominant-baseline', 'central')
+        .attr('font-size', VALUE_FONT_SIZE)
+        .attr('font-weight', '600')
+        .attr('fill', palette.textMuted)
+        .text(valueText);
     }
   }
 

package/src/d3.ts

@@ -4238,7 +4238,6 @@ function renderTimelineHorizontalTimeSort(
 ): void {
   const {
     width,
-    height,
     tooltip,
     solid,
     textColor,
@@ -4301,14 +4300,18 @@ function renderTimelineHorizontalTimeSort(
     ? -(topScaleH + markerReserve + ERA_ROW_H / 2)
     : 0;
   const innerWidth = width - margin.left - margin.right;
-  const availInnerHeight = height - margin.top - margin.bottom;
-  const rowH = Math.min(ctx.structural(28), availInnerHeight / sorted.length);
-  // Each event needs only `rowH` of vertical space. When the container is
-  // taller than the rows require (rowH hits its 28px cap), draw the era
-  // bands and time axis to the content height instead of the full container
-  // so the axis sits just below the last event rather than leaving a large
-  // vertical gap. The SVG itself shrinks to match (top-aligned via
-  // preserveAspectRatio) so callers don't reserve dead space below the chart.
+  // Each event gets a fixed comfortable row. The old behaviour compressed rowH
+  // to fit the container height (`min(28, avail / n)`), but that only ever
+  // shrank rows BELOW the 22px bar height — cramming events into overlap when
+  // the host surface was shorter than the content required (e.g. the app's
+  // fixed-height embedded-diagram surface). A constant rowH never overlaps:
+  // when the container is taller than needed the SVG shrinks to the content
+  // (top-aligned via preserveAspectRatio); when shorter, the SVG grows past it
+  // and the host collapses/expands to the rendered height. This also makes the
+  // interactive preview match the exported image, which already used rowH=28.
+  const rowH = ctx.structural(28);
+  // Draw the era bands and time axis to the content height (not the full
+  // container) so the axis sits just below the last event.
   const innerHeight = rowH * sorted.length;
   const usedHeight = margin.top + innerHeight + margin.bottom;
 
@@ -7751,6 +7754,10 @@ export async function renderForExport(
     // here — the Node fs `loadMapData()` seam can't run in a browser. CLI/SSR
     // omit this and fall back to the fs loader.
     mapData?: import('./map/resolved-types').MapData;
+    // WYSIWYG map export: the live preview pane's displayed aspect (w/h). When
+    // set, the map canvas adopts it + stretch-fills so the PNG matches the
+    // on-screen map. The app passes this; headless consumers omit it.
+    mapAspect?: number;
   }
 ): Promise<string> {
   const exportMode = options?.exportMode ?? false;
@@ -8491,7 +8498,12 @@ export async function renderForExport(
     // aspect (world ~2.3:1, a region taller, etc.) instead of the fixed 800, so the
     // export matches the content's natural shape — no vertical stretch, no
     // letterbox bands. `preferContain` rides along to the renderer.
-    const dims = mapExportDimensions(mapResolved, mapData, EXPORT_WIDTH);
+    const dims = mapExportDimensions(
+      mapResolved,
+      mapData,
+      EXPORT_WIDTH,
+      options?.mapAspect
+    );
     const container = createExportContainer(dims.width, dims.height);
     renderMapForExport(
       container,

package/src/diagnostics.ts

@@ -347,13 +347,6 @@ export function bareDescriptionRemovedMessage(args: {
   return `'|' description shorthand removed in ${args.chartType} — use 'description: ${quoted}'`;
 }
 
-/**
- * Canonical message for `E_TAG_DECLARED_AFTER_CONTENT`.
- */
-export function tagDeclaredAfterContentMessage(tagName: string): string {
-  return `'tag ${tagName}' must appear before content — move it above diagram lines`;
-}
-
 /**
  * Canonical message for `W_EMPTY_METADATA_VALUE`. Emitted when a
  * `key:` token has no value following the colon.
@@ -364,15 +357,3 @@ export function emptyMetadataValueMessage(key: string): string {
     `Provide a value or remove the key.`
   );
 }
-
-/**
- * Canonical message for `W_ATTRIBUTE_AT_PARENT_INDENT`. Emitted
- * when an indented reserved-key attribute appears at the same indent
- * level as preceding structural children.
- */
-export function attributeAtParentIndentMessage(key: string): string {
-  return (
-    `Attribute '${key}:' attaches to the parent above — ` +
-    `indent further if you meant it on the preceding structural child.`
-  );
-}

package/src/index.ts

@@ -213,6 +213,14 @@ export { themes, type Theme } from './themes';
 
 export { getMinDimensions } from './dimensions';
 
+// ============================================================
+// SVG embed normalization (responsive inline embedding)
+// ============================================================
+// Tightens a static render() SVG's viewBox to its content + strips fixed
+// width/height so hosts (Obsidian, remark/markdown, web) can size it to its
+// natural aspect ratio with no dead space. Pure string transform.
+export { normalizeSvgForEmbed, getEmbedSvgViewBox } from './utils/svg-embed';
+
 // ============================================================
 // Map chart-type completion (gazetteer-fed; §24B.5/.8)
 // ============================================================

package/src/map/dimensions.ts

@@ -83,10 +83,24 @@ export interface MapExportDimensions {
 export function mapExportDimensions(
   resolved: ResolvedMap,
   data: MapData,
-  baseWidth = 1200
+  baseWidth = 1200,
+  /** WYSIWYG override (app export): the live preview pane's displayed aspect
+   *  (width / height). When provided, the canvas adopts it verbatim and
+   *  stretch-fills (no clamp, no contain) so the PNG matches exactly what's on
+   *  screen. Omitted by every headless consumer (CLI / MCP / SSG / Obsidian),
+   *  which keep the intrinsic-aspect sizing below. */
+  aspectOverride?: number
 ): MapExportDimensions {
-  const raw = mapContentAspect(resolved, data);
-  const clamped = Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
+  const useOverride =
+    aspectOverride !== undefined &&
+    Number.isFinite(aspectOverride) &&
+    aspectOverride > 0;
+  const raw = useOverride ? aspectOverride : mapContentAspect(resolved, data);
+  // The override is the user's on-screen aspect — honour it as-is (no clamp);
+  // only the intrinsic path guards against pathological extents.
+  const clamped = useOverride
+    ? raw
+    : Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
   const width = baseWidth;
   let height = Math.round(width / clamped);
 
@@ -111,7 +125,9 @@ export function mapExportDimensions(
   }
 
   // The canvas was forced off the content aspect ⇒ tell the renderer to
-  // contain-fit (letterbox) rather than stretch-distort.
-  const preferContain = clamped !== raw || floored;
+  // contain-fit (letterbox) rather than stretch-distort. The WYSIWYG override is
+  // exempt: it stretch-fills (mirroring the preview pane) unless the MIN_MAP_BAND
+  // floor had to grow the canvas off-aspect.
+  const preferContain = useOverride ? floored : clamped !== raw || floored;
   return { width, height, preferContain };
 }

package/src/map/geo.ts

@@ -42,11 +42,6 @@ export function featureIndex(
   return idx;
 }
 
-/** Set of geometry ids (ISO codes) present in a topology. */
-export function idSet(topo: BoundaryTopology): Set<string> {
-  return new Set(geomObject(topo).geometries.map((g) => g.id));
-}
-
 // Memoize adjacency on the RAW asset object (never the per-render-mutated
 // `worldLayer`). Keyed by topology identity — the assets are stable singletons
 // from load-data.ts, so one build per topology lasts the process (G13).

package/src/map/layout.ts

@@ -36,6 +36,9 @@ import {
 import type { LabelRect, PointCircle } from '../label-layout';
 import { measureLegendText } from '../utils/legend-constants';
 import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
+import type { LegendMode } from '../utils/legend-types';
+import { mapLegendBand } from './legend-band';
+import type { MapLayoutLegend } from './types';
 import type { DgmoError } from '../diagnostics';
 import type { BoundaryTopology } from './data/types';
 import type {
@@ -363,21 +366,11 @@ export interface PlacedLabel {
   readonly lineNumber: number;
 }
 
-export interface MapLayoutLegend {
-  readonly tagGroups: ReadonlyArray<{
-    name: string;
-    entries: ReadonlyArray<{ value: string; color: string }>;
-  }>;
-  readonly activeGroup: string | null;
-  readonly ramp?: {
-    metric?: string;
-    min: number;
-    max: number;
-    hue: string;
-    /** Low end of the ramp gradient (the land colour the fills blend from). */
-    base: string;
-  };
-}
+// MapLayoutLegend now lives in ./types (imported for local use + re-exported
+// below) so that ./legend-band can consume the type without importing this
+// module, which would re-introduce the layout↔legend-band cycle (this module
+// value-imports mapLegendBand from ./legend-band).
+export type { MapLayoutLegend };
 
 /** A drawn river centerline — an open stroked path (no fill). */
 export interface MapLayoutRiver {
@@ -482,6 +475,10 @@ export interface LayoutOptions {
    *  canvas away from the content aspect, so the off-aspect canvas doesn't
    *  re-distort. The in-app preview pane leaves this unset (keeps stretch-fill). */
   readonly preferContain?: boolean;
+  /** Which legend variant gets drawn — `'export'` shows only the active group,
+   *  `'preview'` keeps inactive pills. Used to size the reserved legend band so
+   *  the projected land starts below the legend. Defaults to `'preview'`. */
+  readonly legendMode?: LegendMode;
 }
 
 interface Size {
@@ -1168,6 +1165,35 @@ export function layoutMap(
 
   const regionById = new Map(resolved.regions.map((r) => [r.iso, r]));
 
+  // -- Legend model (AR1: categorical via renderer's renderLegendD3). Built here
+  // (before the fit) so the fit can reserve a band for it. Only the colouring
+  // dimensions (value ramp + tag groups) get a legend; POI size and edge
+  // thickness are self-evident from the marker/line scale and carry no key. --
+  let legend: MapLayoutLegend | null = null;
+  if (!resolved.directives.noLegend) {
+    const legendTagGroups = resolved.tagGroups.map((g) => ({
+      name: g.name,
+      entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
+    }));
+    if (legendTagGroups.length > 0 || hasRamp) {
+      legend = {
+        tagGroups: legendTagGroups,
+        activeGroup,
+        ...(hasRamp && {
+          ramp: {
+            ...(resolved.directives.regionMetric !== undefined && {
+              metric: resolved.directives.regionMetric,
+            }),
+            min: rampMin,
+            max: rampMax,
+            hue: rampHue,
+            base: rampBase,
+          },
+        }),
+      };
+    }
+  }
+
   // -- Fit the projection to the canvas (size-dependent; the projection + fit
   // target themselves came from buildMapProjection above). --
   // Reserve top padding for the title/subtitle banner ONLY when there are POIs,
@@ -1183,6 +1209,18 @@ export function layoutMap(
       TITLE_FONT_SIZE / 2;
     topPad = Math.max(FIT_PAD, bannerBottom + TITLE_GAP);
   }
+  // Reserve a band for the top-center legend so the projected land starts BELOW
+  // it (the legend is a foreground overlay — without this it covers land, e.g.
+  // Europe on a world map). The band is measured from the SAME groups/config the
+  // renderer draws (mode-aware: export shows only the active group), so the
+  // reserve matches the rendered legend exactly.
+  const legendBand = mapLegendBand(legend, {
+    width,
+    mode: opts.legendMode ?? 'preview',
+    hasTitle: Boolean(resolved.title),
+    hasSubtitle: Boolean(resolved.subtitle),
+  });
+  if (legendBand > topPad) topPad = legendBand;
   const fitBox: [[number, number], [number, number]] = [
     [FIT_PAD, topPad],
     [
@@ -1223,7 +1261,10 @@ export function layoutMap(
     // edge, not 24px short of it with a coastline ringing the gap). The title
     // overlays the top; we reserve a top band only when POIs are present (so
     // their markers don't project up under the foreground title banner).
-    const topReserve = resolved.title && resolved.pois.length > 0 ? topPad : 0;
+    const topReserve =
+      (resolved.title && resolved.pois.length > 0) || legendBand > 0
+        ? topPad
+        : 0;
     const ox = 0;
     const oy = topReserve;
     const sx = cw > 0 ? width / cw : 1;
@@ -2887,36 +2928,6 @@ export function layoutMap(
     labels.push(...contextLabels);
   }
 
-  // -- Legend model (AR1: categorical via renderer's renderLegendD3) --
-  let legend: MapLayoutLegend | null = null;
-  if (!resolved.directives.noLegend) {
-    const tagGroups = resolved.tagGroups.map((g) => ({
-      name: g.name,
-      entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
-    }));
-    // Only the colouring dimensions (value ramp + tag groups) get a legend.
-    // POI size and edge thickness are self-evident from the marker/line scale and
-    // intentionally carry no key (the poi-metric/flow-metric labels are captured
-    // for future use but not rendered as legend keys in v1).
-    if (tagGroups.length > 0 || hasRamp) {
-      legend = {
-        tagGroups,
-        activeGroup,
-        ...(hasRamp && {
-          ramp: {
-            ...(resolved.directives.regionMetric !== undefined && {
-              metric: resolved.directives.regionMetric,
-            }),
-            min: rampMin,
-            max: rampMax,
-            hue: rampHue,
-            base: rampBase,
-          },
-        }),
-      };
-    }
-  }
-
   return {
     width,
     height,

package/src/map/legend-band.ts

@@ -0,0 +1,99 @@
+// Vertical band reserved at the top of a map canvas for the choropleth / tag
+// legend, so the projected land starts BELOW the legend instead of being covered
+// by it. The legend (§24B.11) is drawn as a top-center foreground overlay; on a
+// world map that placement sits over land (e.g. Europe), hiding it. Reserving a
+// band in the fit box pushes the map down so the legend clears the land.
+//
+// Shared by `layoutMap` (grows `topPad`) and `mapExportDimensions` is intentionally
+// NOT a consumer — the canvas height is independent; the band only repositions the
+// map WITHIN the canvas. The group builder + config are reused by the renderer so
+// the measured band matches exactly what gets drawn.
+import { computeLegendLayout } from '../utils/legend-layout';
+import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
+import type {
+  LegendConfig,
+  LegendGroupData,
+  LegendMode,
+  LegendState,
+} from '../utils/legend-types';
+import type { MapLayoutLegend } from './types';
+
+// Gap between the title/subtitle banner and the legend top — mirrors the `+ 8`
+// in renderer.ts `legendY`.
+const LEGEND_TOP_GAP = 8;
+// Gap between the legend bottom and the start of the map content.
+const LEGEND_BOTTOM_GAP = 10;
+
+/** The legend's colouring groups (score ramp first, then non-empty tag groups) —
+ *  the SAME array the renderer draws, so a measured layout matches the rendered
+ *  one. Empty when the legend has neither a ramp nor any populated tag group. */
+export function mapLegendGroups(legend: MapLayoutLegend): LegendGroupData[] {
+  const ramp = legend.ramp;
+  // Reserved name "Value" when no region-metric label is set — must match
+  // VALUE_NAME in layout.ts so the resolved activeGroup selects it.
+  const scoreGroup: LegendGroupData | null = ramp
+    ? {
+        name: ramp.metric?.trim() || 'Value',
+        entries: [],
+        gradient: {
+          min: ramp.min,
+          max: ramp.max,
+          hue: ramp.hue,
+          base: ramp.base,
+        },
+      }
+    : null;
+  const tagGroups: LegendGroupData[] = legend.tagGroups
+    .filter((g) => g.entries.length > 0)
+    .map((g) => ({ name: g.name, entries: [...g.entries] }));
+  return [...(scoreGroup ? [scoreGroup] : []), ...tagGroups];
+}
+
+/** The shared map-legend config (top-center, below the title, inactive pills kept
+ *  so the preview can flip the active colouring dimension). `mode` gates the
+ *  export-only filtering (active group only). */
+export function mapLegendConfig(
+  groups: readonly LegendGroupData[],
+  mode: LegendMode
+): LegendConfig {
+  return {
+    groups,
+    position: { placement: 'top-center', titleRelation: 'below-title' },
+    mode,
+    showEmptyGroups: false,
+    showInactivePills: true,
+  };
+}
+
+/** Y of the legend's top edge — mirrors `legendY` in renderer.ts. */
+export function mapLegendTop(hasTitle: boolean, hasSubtitle: boolean): number {
+  return (
+    (hasTitle ? TITLE_Y + TITLE_FONT_SIZE : 0) +
+    (hasSubtitle ? TITLE_FONT_SIZE : 0) +
+    LEGEND_TOP_GAP
+  );
+}
+
+/** Total vertical band (px from the canvas top) the legend occupies = its top Y +
+ *  measured height + a bottom gap. Returns 0 when no legend is drawn, so callers
+ *  can `Math.max` it into their existing top reserve without special-casing. */
+export function mapLegendBand(
+  legend: MapLayoutLegend | null,
+  opts: {
+    width: number;
+    mode: LegendMode;
+    hasTitle: boolean;
+    hasSubtitle: boolean;
+  }
+): number {
+  if (!legend) return 0;
+  const groups = mapLegendGroups(legend);
+  if (groups.length === 0) return 0;
+  const config = mapLegendConfig(groups, opts.mode);
+  const state: LegendState = { activeGroup: legend.activeGroup };
+  const { height } = computeLegendLayout(config, state, opts.width);
+  if (height <= 0) return 0;
+  return (
+    mapLegendTop(opts.hasTitle, opts.hasSubtitle) + height + LEGEND_BOTTOM_GAP
+  );
+}

package/src/map/renderer.ts

@@ -14,6 +14,7 @@ import {
 import { mix } from '../palettes/color-utils';
 import { renderLegendD3 } from '../utils/legend-d3';
 import type { LegendConfig, LegendState } from '../utils/legend-types';
+import { mapLegendConfig, mapLegendGroups } from './legend-band';
 import type { PaletteColors } from '../palettes/types';
 import type { D3ExportDimensions } from '../utils/d3-types';
 import type { MapData, ResolvedMap } from './resolved-types';
@@ -236,6 +237,9 @@ export function renderMap(
       // stretch-distorting. The in-app preview pane passes no exportDims → unset →
       // keeps the global stretch-fill.
       preferContain: exportDims?.preferContain ?? false,
+      // Reserve the legend band for the mode actually drawn below (export shows
+      // only the active group; preview keeps the inactive pills).
+      legendMode: exportDims ? 'export' : 'preview',
       ...(activeGroupOverride !== undefined && {
         activeGroup: activeGroupOverride,
       }),
@@ -912,36 +916,14 @@ export function renderMap(
       .attr('transform', `translate(0, ${legendY})`);
     // The value ramp is a selectable colouring group alongside the tag groups
     // (the user flips between them); its capsule renders the gradient inline.
-    // Reserved name "Value" when no region-metric label is set — must match
-    // VALUE_NAME in layout.ts so the resolved activeGroup selects it.
-    const ramp = layout.legend.ramp;
-    const scoreGroup = ramp
-      ? {
-          name: ramp.metric?.trim() || 'Value',
-          entries: [],
-          gradient: {
-            min: ramp.min,
-            max: ramp.max,
-            hue: ramp.hue,
-            base: ramp.base,
-          },
-        }
-      : null;
-    const tagGroups = layout.legend.tagGroups
-      .filter((g) => g.entries.length > 0)
-      .map((g) => ({ name: g.name, entries: [...g.entries] }));
-    const groups = [...(scoreGroup ? [scoreGroup] : []), ...tagGroups];
+    // Built from the shared helper so the drawn legend matches the band the
+    // layout reserved for it (see legend-band.ts).
+    const groups = mapLegendGroups(layout.legend);
     if (groups.length > 0) {
-      const config: LegendConfig = {
+      const config: LegendConfig = mapLegendConfig(
         groups,
-        position: { placement: 'top-center', titleRelation: 'below-title' },
-        mode: exportDims ? 'export' : 'preview',
-        showEmptyGroups: false,
-        // Keep inactive siblings visible as pills so the user can click to flip
-        // the active colouring dimension (preview only — export shows just the
-        // active group).
-        showInactivePills: true,
-      };
+        exportDims ? 'export' : 'preview'
+      );
       const state: LegendState = { activeGroup: layout.legend.activeGroup };
       renderLegendD3(legendG, config, state, palette, isDark, undefined, width);
     }