@diagrammo/dgmo 0.23.0 → 0.25.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Diagrammo
+Copyright (c) 2026 Demian Neidetcher
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/advanced.cjs

@@ -840,7 +840,7 @@ function withTagAliases(base, aliases) {
 function isReservedKey(registry, key) {
   return registry.keys.has(key) || registry.tagAliases.has(key);
 }
-var SEQUENCE_REGISTRY, INFRA_REGISTRY, MAP_REGISTRY, ORG_REGISTRY, C4_REGISTRY, ER_REGISTRY, CLASS_REGISTRY, KANBAN_REGISTRY, SITEMAP_REGISTRY, GANTT_REGISTRY, PERT_REGISTRY, BOXES_AND_LINES_REGISTRY, TIMELINE_REGISTRY, MINDMAP_REGISTRY, TECH_RADAR_REGISTRY, CYCLE_REGISTRY, JOURNEY_MAP_REGISTRY, PYRAMID_REGISTRY, RING_REGISTRY, RACI_REGISTRY, WIREFRAME_REGISTRY;
+var SEQUENCE_REGISTRY, INFRA_REGISTRY, MAP_REGISTRY, ORG_REGISTRY, C4_REGISTRY, ER_REGISTRY, KANBAN_REGISTRY, SITEMAP_REGISTRY, GANTT_REGISTRY, PERT_REGISTRY, BOXES_AND_LINES_REGISTRY, TIMELINE_REGISTRY, MINDMAP_REGISTRY, TECH_RADAR_REGISTRY, CYCLE_REGISTRY, JOURNEY_MAP_REGISTRY, PYRAMID_REGISTRY, RING_REGISTRY, RACI_REGISTRY;
 var init_reserved_key_registry = __esm({
   "src/utils/reserved-key-registry.ts"() {
     "use strict";
@@ -884,10 +884,6 @@ var init_reserved_key_registry = __esm({
       "description",
       "domain"
     ]);
-    CLASS_REGISTRY = staticRegistry([
-      "color",
-      "description"
-    ]);
     KANBAN_REGISTRY = staticRegistry([
       "color",
       "description",
@@ -963,7 +959,6 @@ var init_reserved_key_registry = __esm({
       "color",
       "description"
     ]);
-    WIREFRAME_REGISTRY = staticRegistry([]);
   }
 });
 
@@ -4236,6 +4231,9 @@ var init_legend_layout = __esm({
 });
 
 // src/utils/legend-d3.ts
+function centerText(sel) {
+  return sel.attr("dy", LEGEND_TEXT_DY);
+}
 function renderLegendD3(container, config, state, palette, isDark, callbacks, containerWidth) {
   const width = containerWidth ?? parseFloat(container.attr("width") || "800");
   let currentState = { ...state };
@@ -4318,21 +4316,21 @@ function renderCapsule(parent, capsule, palette, groupBg, pillBorder, _isDark, c
   const pill = capsule.pill;
   g.append("rect").attr("x", pill.x).attr("y", pill.y).attr("width", pill.width).attr("height", pill.height).attr("rx", pill.height / 2).attr("fill", palette.bg);
   g.append("rect").attr("x", pill.x).attr("y", pill.y).attr("width", pill.width).attr("height", pill.height).attr("rx", pill.height / 2).attr("fill", "none").attr("stroke", pillBorder).attr("stroke-width", 0.75);
-  g.append("text").attr("x", pill.x + pill.width / 2).attr("y", LEGEND_HEIGHT / 2).attr("text-anchor", "middle").attr("dominant-baseline", "central").attr("font-size", LEGEND_PILL_FONT_SIZE).attr("font-weight", 500).attr("fill", palette.text).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(capsule.groupName);
+  g.append("text").attr("x", pill.x + pill.width / 2).attr("y", LEGEND_HEIGHT / 2).attr("text-anchor", "middle").call(centerText).attr("font-size", LEGEND_PILL_FONT_SIZE).attr("font-weight", 500).attr("fill", palette.text).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(capsule.groupName);
   if (capsule.gradient) {
     const gr = capsule.gradient;
     const gradId = `dgmo-legend-ramp-${capsule.groupName.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
     const def = g.append("defs").append("linearGradient").attr("id", gradId);
     def.append("stop").attr("offset", "0%").attr("stop-color", mix(gr.hue, gr.base, 15));
     def.append("stop").attr("offset", "100%").attr("stop-color", gr.hue);
-    g.append("text").attr("x", gr.minX).attr("y", gr.textY).attr("dominant-baseline", "central").attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(gr.minText);
+    g.append("text").attr("x", gr.minX).attr("y", gr.textY).call(centerText).attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(gr.minText);
     g.append("rect").attr("class", "dgmo-legend-gradient-ramp").attr("data-ramp-min", gr.min).attr("data-ramp-max", gr.max).attr("x", gr.rampX).attr("y", gr.rampY).attr("width", gr.rampW).attr("height", gr.rampH).attr("rx", 2).attr("fill", `url(#${gradId})`);
-    g.append("text").attr("x", gr.maxX).attr("y", gr.textY).attr("dominant-baseline", "central").attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(gr.maxText);
+    g.append("text").attr("x", gr.maxX).attr("y", gr.textY).call(centerText).attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(gr.maxText);
   }
   for (const entry of capsule.entries) {
     const entryG = g.append("g").attr("data-legend-entry", entry.value.toLowerCase()).attr("data-series-name", entry.value).style("cursor", "pointer");
     entryG.append("circle").attr("cx", entry.dotCx).attr("cy", entry.dotCy).attr("r", LEGEND_DOT_R).attr("fill", entry.color);
-    entryG.append("text").attr("x", entry.textX).attr("y", entry.textY).attr("dominant-baseline", "central").attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("font-family", FONT_FAMILY).text(entry.displayValue ?? entry.value);
+    entryG.append("text").attr("x", entry.textX).attr("y", entry.textY).call(centerText).attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("font-family", FONT_FAMILY).text(entry.displayValue ?? entry.value);
     if (callbacks?.onEntryHover) {
       const groupName = capsule.groupName;
       const entryValue = entry.value;
@@ -4352,7 +4350,7 @@ function renderCapsule(parent, capsule, palette, groupBg, pillBorder, _isDark, c
 function renderPill(parent, pill, palette, groupBg, callbacks) {
   const g = parent.append("g").attr("transform", `translate(${pill.x},${pill.y})`).attr("data-legend-group", pill.groupName.toLowerCase()).style("cursor", "pointer");
   g.append("rect").attr("width", pill.width).attr("height", pill.height).attr("rx", pill.height / 2).attr("fill", groupBg);
-  g.append("text").attr("x", pill.width / 2).attr("y", pill.height / 2).attr("text-anchor", "middle").attr("dominant-baseline", "central").attr("font-size", LEGEND_PILL_FONT_SIZE).attr("font-weight", 500).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(pill.groupName);
+  g.append("text").attr("x", pill.width / 2).attr("y", pill.height / 2).attr("text-anchor", "middle").call(centerText).attr("font-size", LEGEND_PILL_FONT_SIZE).attr("font-weight", 500).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(pill.groupName);
   if (callbacks?.onGroupToggle) {
     const cb = callbacks.onGroupToggle;
     const name = pill.groupName;
@@ -4375,7 +4373,7 @@ function renderControl(parent, ctrl, palette, _groupBg, pillBorder, _isDark, con
     textX = 8 + 14 + LEGEND_ENTRY_DOT_GAP + measureLegendText(ctrl.label, LEGEND_PILL_FONT_SIZE) / 2;
   }
   if (ctrl.label) {
-    g.append("text").attr("x", textX).attr("y", ctrl.height / 2).attr("text-anchor", "middle").attr("dominant-baseline", "central").attr("font-size", LEGEND_PILL_FONT_SIZE).attr("font-weight", 500).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(ctrl.label);
+    g.append("text").attr("x", textX).attr("y", ctrl.height / 2).attr("text-anchor", "middle").call(centerText).attr("font-size", LEGEND_PILL_FONT_SIZE).attr("font-weight", 500).attr("fill", palette.textMuted).attr("pointer-events", "none").attr("font-family", FONT_FAMILY).text(ctrl.label);
   }
   if (ctrl.children) {
     let cx = ctrl.width + 4;
@@ -4385,7 +4383,7 @@ function renderControl(parent, ctrl, palette, _groupBg, pillBorder, _isDark, con
         "fill",
         child.isActive ? palette.primary ?? palette.text : "none"
       ).attr("stroke", pillBorder).attr("stroke-width", 0.75);
-      childG.append("text").attr("x", child.width / 2).attr("y", ctrl.height / 2).attr("text-anchor", "middle").attr("dominant-baseline", "central").attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", child.isActive ? palette.bg : palette.textMuted).attr("font-family", FONT_FAMILY).text(child.label);
+      childG.append("text").attr("x", child.width / 2).attr("y", ctrl.height / 2).attr("text-anchor", "middle").call(centerText).attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", child.isActive ? palette.bg : palette.textMuted).attr("font-family", FONT_FAMILY).text(child.label);
       const configCtrl2 = configControls?.find((c) => c.id === ctrl.id);
       const configChild = configCtrl2?.children?.find((c) => c.id === child.id);
       if (configChild?.onClick) {
@@ -4439,7 +4437,7 @@ function renderControlsGroup(parent, layout, palette, groupBg, pillBorder, callb
       } else {
         entryG.append("circle").attr("cx", tl.dotCx).attr("cy", tl.dotCy).attr("r", LEGEND_TOGGLE_DOT_R).attr("fill", "none").attr("stroke", palette.textMuted).attr("stroke-width", 1);
       }
-      entryG.append("text").attr("x", tl.textX).attr("y", tl.textY).attr("dominant-baseline", "central").attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("opacity", tl.active ? 1 : LEGEND_TOGGLE_OFF_OPACITY).attr("font-family", FONT_FAMILY).text(tl.label);
+      entryG.append("text").attr("x", tl.textX).attr("y", tl.textY).call(centerText).attr("font-size", LEGEND_ENTRY_FONT_SIZE).attr("fill", palette.textMuted).attr("opacity", tl.active ? 1 : LEGEND_TOGGLE_OFF_OPACITY).attr("font-family", FONT_FAMILY).text(tl.label);
       if (callbacks?.onControlsToggle && toggle) {
         const cb = callbacks.onControlsToggle;
         const id = tl.id;
@@ -4452,6 +4450,7 @@ function renderControlsGroup(parent, layout, palette, groupBg, pillBorder, callb
     }
   }
 }
+var LEGEND_TEXT_DY;
 var init_legend_d3 = __esm({
   "src/utils/legend-d3.ts"() {
     "use strict";
@@ -4459,6 +4458,7 @@ var init_legend_d3 = __esm({
     init_legend_layout();
     init_color_utils();
     init_fonts();
+    LEGEND_TEXT_DY = "0.32em";
   }
 });
 
@@ -4644,7 +4644,6 @@ var init_name_normalize = __esm({
 var parser_exports = {};
 __export(parser_exports, {
   isSequenceBlock: () => isSequenceBlock,
-  isSequenceMessage: () => isSequenceMessage,
   isSequenceNote: () => isSequenceNote,
   isSequenceSection: () => isSequenceSection,
   looksLikeSequence: () => looksLikeSequence,
@@ -4660,9 +4659,6 @@ function isHardRemovedToken(remainder) {
   }
   return { removed: false };
 }
-function isSequenceMessage(el) {
-  return el.kind === "message";
-}
 function isSequenceBlock(el) {
   return el.kind === "block";
 }
@@ -26631,7 +26627,7 @@ function renderBoxesAndLines(container, parsed, layout, palette, isDark, options
   const VALUE_NAME = hasRamp ? parsed.boxMetric?.trim() || "Value" : null;
   const matchColorGroup = (v) => {
     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;
@@ -26972,6 +26968,22 @@ function renderBoxesAndLines(container, parsed, layout, palette, isDark, options
         const tooltipText = fullText.length > 200 ? fullText.slice(0, 199) + "\u2026" : fullText;
         nodeG.append("title").text(tooltipText);
       }
+    } else if (parsed.showValues && node.value !== void 0) {
+      const valueLabel = parsed.boxMetric ? `${parsed.boxMetric}: ${node.value}` : String(node.value);
+      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).text(fitted.lines[li]);
+      }
+      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);
+      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,
@@ -26984,21 +26996,16 @@ function renderBoxesAndLines(container, parsed, layout, palette, isDark, options
         nodeG.append("text").attr("x", 0).attr("y", -totalH / 2 + lineH / 2 + li * lineH).attr("text-anchor", "middle").attr("dominant-baseline", "central").attr("font-size", fitted.fontSize).attr("font-weight", "600").attr("fill", colors.text).text(fitted.lines[li]);
       }
     }
-    if (parsed.showValues && node.value !== void 0) {
+    if (parsed.showValues && node.value !== void 0 && desc && desc.length > 0 && !hideDescriptions) {
       const valueText = String(node.value);
-      const descShown = !!(desc && desc.length > 0 && !hideDescriptions);
-      if (descShown) {
-        const padX = 6;
-        const padY = 5;
-        const bw = valueText.length * VALUE_FONT_SIZE * CHAR_WIDTH_RATIO2 + 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 {
-        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_RATIO2 + 8;
+      const bh = VALUE_FONT_SIZE + 4;
+      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);
     }
   }
   const hasDescriptions = parsed.nodes.some(
@@ -27094,7 +27101,7 @@ var init_renderer6 = __esm({
     init_wrapped_desc();
     init_scaling();
     DIAGRAM_PADDING6 = 20;
-    NODE_FONT_SIZE = 13;
+    NODE_FONT_SIZE = 11;
     MIN_NODE_FONT_SIZE = 9;
     EDGE_LABEL_FONT_SIZE4 = 11;
     EDGE_STROKE_WIDTH5 = 1.5;
@@ -47054,7 +47061,11 @@ function resolveMap(parsed, data) {
       if (bb && !isWholeSphere(bb)) containerBoxes.push(bb);
     }
     const containerUnion = unionExtent(containerBoxes, points);
-    if (containerUnion) extent2 = pad(containerUnion, PAD_FRACTION);
+    if (containerUnion)
+      extent2 = pad(
+        clampContainerToCluster(containerUnion, points),
+        PAD_FRACTION
+      );
   }
   if (isPoiOnly) {
     const cx = (extent2[0][0] + extent2[1][0]) / 2;
@@ -47135,6 +47146,22 @@ function mostCommonCountry(regions, poiCountries) {
   }
   return best;
 }
+function clampContainerToCluster(container, points) {
+  const poi = unionExtent([], points);
+  if (!poi) return container;
+  let [[west, south], [east, north]] = container;
+  const [[pWest, pSouth], [pEast, pNorth]] = poi;
+  south = Math.max(south, pSouth - CONTAINER_OVERSHOOT_DEG);
+  north = Math.min(north, pNorth + CONTAINER_OVERSHOOT_DEG);
+  if (east <= 180 && pEast <= 180) {
+    west = Math.max(west, pWest - CONTAINER_OVERSHOOT_DEG);
+    east = Math.min(east, pEast + CONTAINER_OVERSHOOT_DEG);
+  }
+  return [
+    [west, south],
+    [east, north]
+  ];
+}
 function pad(e, frac) {
   const dLon = (e[1][0] - e[0][0]) * frac || 1;
   const dLat = (e[1][1] - e[0][1]) * frac || 1;
@@ -47147,7 +47174,7 @@ function firstError(diags) {
   const e = diags.find((d) => d.severity === "error");
   return e ? formatDgmoError(e) : null;
 }
-var WORLD_SPAN, MERCATOR_MAX_LAT, PAD_FRACTION, REGION_PAD_FRACTION, WORLD_LAT_SOUTH, WORLD_LAT_NORTH, POI_ZOOM_FLOOR_DEG, US_NATIONAL_LON_SPAN, REGION_ALIASES, US_STATE_POSTAL;
+var WORLD_SPAN, MERCATOR_MAX_LAT, PAD_FRACTION, REGION_PAD_FRACTION, WORLD_LAT_SOUTH, WORLD_LAT_NORTH, POI_ZOOM_FLOOR_DEG, CONTAINER_OVERSHOOT_DEG, US_NATIONAL_LON_SPAN, REGION_ALIASES, US_STATE_POSTAL;
 var init_resolver2 = __esm({
   "src/map/resolver.ts"() {
     "use strict";
@@ -47160,6 +47187,7 @@ var init_resolver2 = __esm({
     WORLD_LAT_SOUTH = -58;
     WORLD_LAT_NORTH = 78;
     POI_ZOOM_FLOOR_DEG = 7;
+    CONTAINER_OVERSHOOT_DEG = 8;
     US_NATIONAL_LON_SPAN = 48;
     REGION_ALIASES = {
       // Common everyday names → the Natural-Earth display name actually shipped.
@@ -47238,6 +47266,55 @@ var init_resolver2 = __esm({
   }
 });
 
+// src/map/legend-band.ts
+function mapLegendGroups(legend) {
+  const ramp = 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 = legend.tagGroups.filter((g) => g.entries.length > 0).map((g) => ({ name: g.name, entries: [...g.entries] }));
+  return [...scoreGroup ? [scoreGroup] : [], ...tagGroups];
+}
+function mapLegendConfig(groups, mode) {
+  return {
+    groups,
+    position: { placement: "top-center", titleRelation: "below-title" },
+    mode,
+    showEmptyGroups: false,
+    showInactivePills: true
+  };
+}
+function mapLegendTop(hasTitle, hasSubtitle) {
+  return (hasTitle ? TITLE_Y + TITLE_FONT_SIZE : 0) + (hasSubtitle ? TITLE_FONT_SIZE : 0) + LEGEND_TOP_GAP2;
+}
+function mapLegendBand(legend, opts) {
+  if (!legend) return 0;
+  const groups = mapLegendGroups(legend);
+  if (groups.length === 0) return 0;
+  const config = mapLegendConfig(groups, opts.mode);
+  const state = { activeGroup: legend.activeGroup };
+  const { height } = computeLegendLayout(config, state, opts.width);
+  if (height <= 0) return 0;
+  return mapLegendTop(opts.hasTitle, opts.hasSubtitle) + height + LEGEND_BOTTOM_GAP2;
+}
+var LEGEND_TOP_GAP2, LEGEND_BOTTOM_GAP2;
+var init_legend_band = __esm({
+  "src/map/legend-band.ts"() {
+    "use strict";
+    init_legend_layout();
+    init_title_constants();
+    LEGEND_TOP_GAP2 = 8;
+    LEGEND_BOTTOM_GAP2 = 10;
+  }
+});
+
 // src/map/colorize.ts
 function assignColors(isos, adjacency) {
   const sorted = [...isos].sort();
@@ -47818,12 +47895,43 @@ function layoutMap(resolved, data, size, opts) {
     return tagFill(r.tags, activeGroup) ?? neutralFill;
   };
   const regionById = new Map(resolved.regions.map((r) => [r.iso, r]));
+  let legend = 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 !== void 0 && {
+              metric: resolved.directives.regionMetric
+            },
+            min: rampMin,
+            max: rampMax,
+            hue: rampHue,
+            base: rampBase
+          }
+        }
+      };
+    }
+  }
   const TITLE_GAP2 = 16;
   let topPad = FIT_PAD;
   if (resolved.title && resolved.pois.length > 0) {
     const bannerBottom = (resolved.subtitle ? TITLE_Y + TITLE_FONT_SIZE : TITLE_Y) + TITLE_FONT_SIZE / 2;
     topPad = Math.max(FIT_PAD, bannerBottom + TITLE_GAP2);
   }
+  const legendBand = mapLegendBand(legend, {
+    width,
+    mode: opts.legendMode ?? "preview",
+    hasTitle: Boolean(resolved.title),
+    hasSubtitle: Boolean(resolved.subtitle)
+  });
+  if (legendBand > topPad) topPad = legendBand;
   const fitBox = [
     [FIT_PAD, topPad],
     [
@@ -47841,7 +47949,7 @@ function layoutMap(resolved, data, size, opts) {
     const by0 = cb[0][1];
     const cw = cb[1][0] - bx0;
     const ch = cb[1][1] - by0;
-    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;
@@ -48905,30 +49013,6 @@ function layoutMap(resolved, data, size, opts) {
     });
     labels.push(...contextLabels);
   }
-  let legend = 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 }))
-    }));
-    if (tagGroups.length > 0 || hasRamp) {
-      legend = {
-        tagGroups,
-        activeGroup,
-        ...hasRamp && {
-          ramp: {
-            ...resolved.directives.regionMetric !== void 0 && {
-              metric: resolved.directives.regionMetric
-            },
-            min: rampMin,
-            max: rampMax,
-            hue: rampHue,
-            base: rampBase
-          }
-        }
-      };
-    }
-  }
   return {
     width,
     height,
@@ -48966,6 +49050,7 @@ var init_layout15 = __esm({
     init_label_layout();
     init_legend_constants();
     init_title_constants();
+    init_legend_band();
     init_context_labels();
     FIT_PAD = 24;
     RAMP_FLOOR2 = 15;
@@ -49165,6 +49250,9 @@ function renderMap(container, resolved, data, palette, isDark, onClickItem, expo
       // 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 !== void 0 && {
         activeGroup: activeGroupOverride
       }
@@ -49456,30 +49544,12 @@ function renderMap(container, resolved, data, palette, isDark, onClickItem, expo
   if (layout.legend) {
     const legendY = (layout.title ? TITLE_Y + TITLE_FONT_SIZE : 0) + (layout.subtitle ? TITLE_FONT_SIZE : 0) + 8;
     const legendG = svg.append("g").attr("class", "dgmo-map-legend").attr("transform", `translate(0, ${legendY})`);
-    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];
+    const groups = mapLegendGroups(layout.legend);
     if (groups.length > 0) {
-      const config = {
+      const config = 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 = { activeGroup: layout.legend.activeGroup };
       renderLegendD3(legendG, config, state, palette, isDark, void 0, width);
     }
@@ -49524,6 +49594,7 @@ var init_renderer16 = __esm({
     init_title_constants();
     init_color_utils();
     init_legend_d3();
+    init_legend_band();
     init_layout15();
     LABEL_FONT = 11;
   }
@@ -49544,9 +49615,10 @@ function mapContentAspect(resolved, data, ref = REF) {
   const aspect = w / h;
   return Number.isFinite(aspect) && aspect > 0 ? aspect : FALLBACK_ASPECT;
 }
-function mapExportDimensions(resolved, data, baseWidth = 1200) {
-  const raw = mapContentAspect(resolved, data);
-  const clamped = Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
+function mapExportDimensions(resolved, data, baseWidth = 1200, aspectOverride) {
+  const useOverride = aspectOverride !== void 0 && Number.isFinite(aspectOverride) && aspectOverride > 0;
+  const raw = useOverride ? aspectOverride : mapContentAspect(resolved, data);
+  const clamped = useOverride ? raw : Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
   const width = baseWidth;
   let height = Math.round(width / clamped);
   let chromeReserve = 0;
@@ -49559,7 +49631,7 @@ function mapExportDimensions(resolved, data, baseWidth = 1200) {
     height = Math.round(chromeReserve + MIN_MAP_BAND);
     floored = true;
   }
-  const preferContain = clamped !== raw || floored;
+  const preferContain = useOverride ? floored : clamped !== raw || floored;
   return { width, height, preferContain };
 }
 var import_d3_geo3, FIT_PAD2, TITLE_GAP, ASPECT_MAX, ASPECT_MIN, MIN_MAP_BAND, FALLBACK_ASPECT, REF;
@@ -55266,7 +55338,6 @@ function renderTimelineTagLegendOverlay(container, parsed, palette, isDark, setu
 function renderTimelineHorizontalTimeSort(container, parsed, palette, isDark, setup, hovers, onClickItem, _exportDims, _swimlaneTagGroup, _activeTagGroup, _onTagStateChange, _viewMode) {
   const {
     width,
-    height,
     tooltip,
     solid,
     textColor,
@@ -55315,8 +55386,7 @@ function renderTimelineHorizontalTimeSort(container, parsed, palette, isDark, se
   const markerLabelY = markerReserve ? -(topScaleH + MARKER_ROW_H / 2) : 0;
   const eraLabelY = eraReserve ? -(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);
+  const rowH = ctx.structural(28);
   const innerHeight = rowH * sorted.length;
   const usedHeight = margin.top + innerHeight + margin.bottom;
   const xScale = d3Scale2.scaleLinear().domain([minDate - datePadding, maxDate + datePadding]).range([0, innerWidth]);
@@ -57897,7 +57967,12 @@ async function renderForExport(content, theme, palette, viewState, options) {
       }
     }
     const mapResolved = resolveMap2(mapParsed, mapData);
-    const dims2 = mapExportDimensions2(mapResolved, mapData, EXPORT_WIDTH);
+    const dims2 = mapExportDimensions2(
+      mapResolved,
+      mapData,
+      EXPORT_WIDTH,
+      options?.mapAspect
+    );
     const container2 = createExportContainer(dims2.width, dims2.height);
     renderMapForExport2(
       container2,

package/dist/advanced.d.cts

@@ -236,6 +236,28 @@ interface ParsedMap {
     readonly diagnostics: readonly DgmoError[];
     readonly error: string | null;
 }
+/** Legend descriptor for a rendered map (a layout-stage output, re-exported from
+ *  `layout.ts`). It lives here so the `legend-band` helper can consume it without
+ *  importing `layout` — `layout` already value-imports `mapLegendBand`, so the
+ *  reverse type import would form a layout↔legend-band cycle. */
+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;
+    };
+}
 
 /** A TopoJSON topology (world-coarse/world-detail keyed by ISO 3166-1 alpha-2;
  *  us-states keyed by ISO 3166-2). Geometry feature `id` is the ISO code;
@@ -1568,6 +1590,7 @@ declare function renderForExport(content: string, theme: 'light' | 'dark' | 'tra
     tagGroup?: string;
     exportMode?: boolean;
     mapData?: MapData;
+    mapAspect?: number;
 }): Promise<string>;
 
 /**
@@ -4839,24 +4862,7 @@ interface PlacedLabel {
     readonly clusterMember?: string;
     readonly lineNumber: number;
 }
-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;
-    };
-}
+
 /** A drawn river centerline — an open stroked path (no fill). */
 interface MapLayoutRiver {
     readonly d: string;
@@ -4955,6 +4961,10 @@ 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 {
     readonly width: number;
@@ -5007,7 +5017,13 @@ interface MapExportDimensions {
     readonly height: number;
     readonly preferContain: boolean;
 }
-declare function mapExportDimensions(resolved: ResolvedMap, data: MapData, baseWidth?: number): MapExportDimensions;
+declare function mapExportDimensions(resolved: ResolvedMap, data: MapData, baseWidth?: number, 
+/** 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;
 
 /** Nearest gazetteer city to a point: the real haversine distance, plus the
  *  canonical name + ISO + (US-only) subdivision for token shaping. `lon`/`lat`