@diagrammo/dgmo 0.22.0 → 0.24.0

package/docs/language-reference.md

@@ -1469,12 +1469,47 @@ Indented shorthand also supports groups (place arrow directly after group header
 ### 13.6 Directives
 
 - `direction TB` — top-to-bottom layout (default: `LR`)
+- `box-metric <Label> [color]` — name a numeric value dimension (see §13.8); optional trailing color sets the ramp hue
+- `show-values` — print each box's numeric value as text (off by default)
 
 ### 13.7 Options
 
 - `active-tag GroupName` — set active tag group for coloring
+- `active-tag none` — suppress tag coloring
+- `active-tag <metric>` — make the value ramp the active dimension (see §13.8)
 - `hide team:Backend, team:Frontend` — hide nodes with matching tag values (colon syntax for tag:value)
 
+### 13.8 Value metric (numeric ramp)
+
+Boxes can carry a numeric measure that drives a continuous color ramp — a
+choropleth-style "value dimension" alongside the categorical tag groups.
+
+```
+boxes-and-lines Fleet Crews
+box-metric Crew blue
+show-values
+
+Flagship value: 120
+Frigate value: 40
+Sloop value: 12
+Flagship -> Frigate
+Flagship -> Sloop
+```
+
+- `value: <number>` on any box records its measure (a reserved metadata key —
+  lifted out, never rendered as a tag). Non-numeric values are an error.
+- `box-metric <Label> [color]` names the dimension and optionally sets the ramp
+  hue (default: the palette's primary color).
+- The ramp anchors at `0` for all-non-negative data, else at the data minimum.
+- The value ramp is the resting-active dimension whenever any box has a
+  `value:` (so value shading works in static export with no interaction).
+  `active-tag <tag-group>` switches to a tag group; `active-tag none` suppresses
+  tinting; `active-tag <metric>` forces the value ramp. On a name collision
+  between a tag group and the metric label, the tag group wins.
+- When the value ramp is active, every box tints along the min→max ramp and the
+  legend shows a gradient capsule; boxes without a `value:` get a neutral fill.
+- `show-values` additionally prints each box's number as text.
+
 ---
 
 ## 15. Timeline Diagrams
@@ -2751,7 +2786,8 @@ route Miami style: arc
 - Title is the declaration line; `caption` (data-source attribution, travels with the exported PNG) is the only chrome directive. There is no `subtitle`.
 - Legend auto-composes below the title: the value ramp + `region-metric` and each tag group are **selectable colouring groups** (collapse/activate to flip the fill); POI size (`poi-metric`) and edge thickness (`flow-metric`) are self-evident from scale and carry no legend key in v1. `no-legend` suppresses all of it.
 - **Region and POI labels are on by default.** Region labels auto-fit **full → abbrev → hide** (a US-state 2-letter abbreviation is tried when the full name doesn't fit; other regions degrade full → hide); POI labels are collision-managed. Labels render **on the map** (export-safe), escalating inline → leader line → numbered pin in dense clusters; markers never move. A wide map in a narrow column (< ~480px) prefers abbreviations and drops reference relief, as if zoomed out.
-- **Cosmetic features are on by default**; the only switches are bare `no-*` opt-outs (no positive opt-in flag): `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-legend`. A plain look = the four basemap flags together.
+- **Cosmetic features are on by default**; the only switches are bare `no-*` opt-outs (no positive opt-in flag): `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-legend`, `no-colorize`. A plain look = the four basemap flags together (`no-colorize` is **not** one of the four — it toggles region *fill style*, not a basemap backdrop layer).
+- **Colorize (distinct political fills) is the default for any map without region data.** Unless a region carries data (a `value:` or a tag), every region drawn at the resolved extent is filled a **distinct light pastel** such that no two bordering regions share a hue — the conventional "colour the countries/states so neighbours separate" look, with zero config. It applies to named-region maps, POI/route-only maps, and even a bare `map` (the whole world colours as the backdrop). The fills are **non-semantic** (no legend entry) and **extent-independent** (a region's colour is the same at any width and in an inset). A direct trailing colour (`Texas red`) paints on top as a highlight and does not suppress colorize; adding any `value:`/tag flips the map to the data dress (colorize auto-suppressed, no error). `no-colorize` forces the plain green-land + blue-water dress — useful when many POIs/routes should pop against a calm map.
 
 ### Name resolution
 
@@ -2767,7 +2803,7 @@ route Miami style: arc
 
 ### Directives & reserved keys
 
-The directive set is **12, all colon-free**: six naming intent the renderer can't infer — `region-metric`, `poi-metric`, `flow-metric`, `locale`, `active-tag`, `caption` — and six `no-*` cosmetic opt-outs — `no-legend`, `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`. There is **no** `projection`, `scale`, `subtitle`, `surface`, `region`, or label-enum directive, and cosmetics have no positive opt-in form. Reserved metadata keys (need colons): `value`, `label`, `style` (`value` = the one numeric channel: region shade / POI size / edge thickness); `surface:` is no longer recognized. A bare US state postal code resolves to that state (`poi Portland OR` → Oregon; `CA` = California). Coordinates are positional (no `at:` key). Projection is inferred from extent + whether the map carries data (US → albers-usa; world data → Equal Earth; world reference → natural-earth; regional → mercator) and cannot be overridden.
+The directive set is **13, all colon-free**: six naming intent the renderer can't infer — `region-metric`, `poi-metric`, `flow-metric`, `locale`, `active-tag`, `caption` — and seven `no-*` cosmetic opt-outs — `no-legend`, `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-colorize`. There is **no** `projection`, `scale`, `subtitle`, `surface`, `region`, or label-enum directive, and cosmetics have no positive opt-in form. Reserved metadata keys (need colons): `value`, `label`, `style` (`value` = the one numeric channel: region shade / POI size / edge thickness); `surface:` is no longer recognized. A bare US state postal code resolves to that state (`poi Portland OR` → Oregon; `CA` = California). Coordinates are positional (no `at:` key). Projection is inferred from extent + whether the map carries data (US → albers-usa; world data → Equal Earth; world reference → natural-earth; regional → mercator) and cannot be overridden.
 
 ---
 

package/gallery/fixtures/boxes-and-lines.dgmo

@@ -6,28 +6,30 @@ tag Priority p High red, Medium orange, Low gray
 active-tag Team
 hide priority:Low
 
+box-metric Load orange
+
 direction LR
 
 // --- Services ---
-API Gateway t: Backend
+API Gateway t: Backend, value: 850
   Main entry point for all requests
   Routes to **backend services**
   -routes-> UserService
   -routes-> ProductService
   -routes-> OrderService
 
-UserService t: Backend
+UserService t: Backend, value: 430
   Handles auth and profiles
   Uses `JWT` tokens for sessions
   -reads-> UserDB
   -checks-> SessionCache
 
-ProductService t: Frontend, description: Product catalog and search
+ProductService t: Frontend, value: 620, description: Product catalog and search
   Supports *full-text* search
   -queries-> ProductDB
   -invalidates-> ProductCache
 
-OrderService t: Backend
+OrderService t: Backend, value: 290
   Order processing pipeline
   Validates inventory before commit
   -writes-> OrderDB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

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

@@ -26,6 +26,7 @@ import {
   extractColor,
   parseFirstLine,
   OPTION_NOCOLON_RE,
+  peelTrailingColorName,
   splitNameAndMeta,
   tryParseSharedOption,
   warnUnknownMetaKeys,
@@ -297,6 +298,26 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
         continue;
       }
 
+      // box-metric / show-values directives — pre-content only (like
+      // active-tag). Explicit regex branches: a bare flag and a
+      // `key value` form won't both match the active-tag OPTION codepath.
+      if (!contentStarted) {
+        const metricMatch = trimmed.match(/^box-metric\s+(.+)$/i);
+        if (metricMatch) {
+          // Regex capture group present after successful match.
+          const { label, colorName } = peelTrailingColorName(
+            metricMatch[1]!.trim()
+          );
+          result.boxMetric = label;
+          if (colorName !== undefined) result.boxMetricColor = colorName;
+          continue;
+        }
+        if (/^show-values$/i.test(trimmed)) {
+          result.showValues = true;
+          continue;
+        }
+      }
+
       // active-tag directive
       if (!contentStarted) {
         const optMatch = trimmed.match(OPTION_NOCOLON_RE);
@@ -784,6 +805,23 @@ function parseNodeLine(
     delete metadata['description'];
   }
 
+  // Lift `value: X` out of metadata into a typed numeric field (mirror of the
+  // map parser). Validate finite-numeric; delete from metadata so it never
+  // becomes a `data-tag-value` attribute.
+  let value: number | undefined;
+  if (metadata['value'] !== undefined) {
+    const raw = metadata['value'];
+    const num = Number(raw);
+    if (Number.isFinite(num)) {
+      value = num;
+    } else {
+      diagnostics.push(
+        makeDgmoError(lineNum, `value must be a number (got "${raw}")`, 'error')
+      );
+    }
+    delete metadata['value'];
+  }
+
   // TD-18 alias is now peeled by splitNameAndMeta — re-register if set.
   if (split.alias) {
     nameAliasMap?.set(normalizeName(split.alias), label);
@@ -796,6 +834,7 @@ function parseNodeLine(
     lineNumber: lineNum,
     metadata,
     ...(description !== undefined && { description }),
+    ...(value !== undefined && { value }),
   };
 }
 

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

@@ -11,6 +11,7 @@ import type {
   LegendConfig,
   LegendState,
   LegendCallbacks,
+  LegendGroupData,
   ControlsGroupToggle,
 } from '../utils/legend-types';
 import {
@@ -19,7 +20,8 @@ import {
   TITLE_Y,
 } from '../utils/title-constants';
 import { contrastText, mix, shapeFill } from '../palettes/color-utils';
-import { resolveTagColor, resolveActiveTagGroup } from '../utils/tag-groups';
+import { resolveColor } from '../colors';
+import { resolveTagColor } from '../utils/tag-groups';
 import type { TagGroup } from '../utils/tag-groups';
 import type { PaletteColors } from '../palettes';
 import { renderInlineText } from '../utils/inline-markdown';
@@ -33,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;
@@ -50,6 +54,9 @@ const NODE_TEXT_PADDING = 12;
 const GROUP_RX = 8;
 const GROUP_LABEL_FONT_SIZE = 14;
 const GROUP_LABEL_ZONE = 32;
+// % tint floor so the ramp minimum still reads as "low, present" (mirror map).
+const RAMP_FLOOR = 15;
+const VALUE_FONT_SIZE = 11;
 
 type D3G = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
 type D3Svg = d3Selection.Selection<SVGSVGElement, unknown, null, undefined>;
@@ -184,8 +191,30 @@ function nodeColors(
   activeGroupName: string | null,
   palette: PaletteColors,
   isDark: boolean,
+  value: {
+    active: boolean;
+    hue: string;
+    fillForValue: (v: number) => string;
+  },
   solid?: boolean
 ): { fill: string; stroke: string; text: string } {
+  // Untagged-neutral fill, reused by the value path for no-value boxes.
+  const neutralFill = mix(palette.bg, palette.text, isDark ? 90 : 95);
+  // Value dimension active: choropleth tint by the node's value, neutral when a
+  // box has no value (mirror map: `value !== undefined ? fillForValue : neutral`).
+  if (value.active) {
+    const fill =
+      node.value !== undefined ? value.fillForValue(node.value) : neutralFill;
+    // Stroke = the ramp hue (NOT a tag color — there may be none); a present
+    // stroke is required for the app's --bl-node-stroke hover-dim to work.
+    const stroke = value.hue;
+    const text = contrastText(
+      fill,
+      palette.textOnFillLight,
+      palette.textOnFillDark
+    );
+    return { fill, stroke, text };
+  }
   const tagColor = resolveTagColor(
     node.metadata,
     [...tagGroups],
@@ -368,6 +397,83 @@ export function renderBoxesAndLines(
   const sGroupLabelZone = sctx.structural(GROUP_LABEL_ZONE);
   const sTitleFontSize = sctx.text(TITLE_FONT_SIZE);
   const sTitleY = sctx.structural(TITLE_Y);
+
+  // ── Value ramp + active-dimension resolution (mirror of map's value model) ──
+  // The ramp is computed in the renderer (architectural divergence from the
+  // map, which precomputes in layout) — node sizes are value-independent, and
+  // this file already owns all colouring + the legend build. Hoisted ONCE
+  // before the node loop so `fillForValue` is not recomputed per node.
+  const nodeValues = parsed.nodes
+    .filter((n) => n.value !== undefined)
+    .map((n) => n.value!);
+  const hasRamp = nodeValues.length > 0;
+  const allNonNegative = hasRamp && nodeValues.every((v) => v >= 0);
+  const rampMin = allNonNegative ? 0 : Math.min(...nodeValues);
+  const rampMax = Math.max(...nodeValues);
+  // Default hue = palette.primary (NOT red like the map — boxes have no water to
+  // stand out against, and red reads as alarm on a neutral metric). A trailing
+  // color on `box-metric` overrides.
+  const rampHue =
+    resolveColor(parsed.boxMetricColor ?? '', palette) ?? palette.primary;
+  // Lift the ramp anchor off the near-black surface on dark themes so the
+  // lowest values read as a clear muted tint rather than sinking to the surface.
+  const rampBase = isDark ? mix(palette.surface, palette.text, 28) : palette.bg;
+  const fillForValue = (v: number): string => {
+    const t = rampMax > rampMin ? (v - rampMin) / (rampMax - rampMin) : 1;
+    const pct = RAMP_FLOOR + Math.max(0, Math.min(1, t)) * (100 - RAMP_FLOOR);
+    return mix(rampHue, rampBase, pct);
+  };
+  const VALUE_NAME = hasRamp ? parsed.boxMetric?.trim() || 'Value' : null;
+
+  // Local active-dimension resolver — mirror map's inline matchColorGroup /
+  // activeIsScore. Do NOT extend the shared resolveActiveTagGroup (it has a
+  // fixed 3-arg signature consumed by 7 chart types). On a name collision
+  // 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 === '' || 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;
+    return v; // unknown name passes through → renders neutral
+  };
+  const override = activeTagGroup; // string | null | undefined
+  let activeGroup: string | null;
+  if (override !== undefined) {
+    activeGroup = override === null ? null : matchColorGroup(override);
+  } else if (parsed.options['active-tag'] !== undefined) {
+    activeGroup = matchColorGroup(parsed.options['active-tag']);
+  } else {
+    // Default-active dimension: value ramp when any box has a value, else the
+    // first declared tag group, else none.
+    activeGroup =
+      VALUE_NAME ??
+      (parsed.tagGroups.length > 0 ? parsed.tagGroups[0]!.name : null);
+  }
+  const activeIsValue = VALUE_NAME !== null && activeGroup === VALUE_NAME;
+
+  // Synthetic legend group for the value ramp (empty entries + gradient),
+  // prepended to the tag groups handed to renderLegendD3 — exactly like the
+  // map's VALUE_NAME group. The shared legend infra renders the gradient capsule
+  // ONLY when it is the active group (legendState.activeGroup === its name).
+  const valueGroup: LegendGroupData | null =
+    VALUE_NAME !== null
+      ? {
+          name: VALUE_NAME,
+          entries: [],
+          gradient: {
+            min: rampMin,
+            max: rampMax,
+            hue: rampHue,
+            base: rampBase,
+          },
+        }
+      : null;
+  const legendGroups: readonly LegendGroupData[] = [
+    ...(valueGroup ? [valueGroup] : []),
+    ...parsed.tagGroups,
+  ];
+
   // Reserve legend height only when a legend will actually render. App-hosted
   // controls move the Descriptions toggle to the app overlay, so a
   // descriptions-only chart (no tag groups) reserves nothing.
@@ -375,13 +481,13 @@ export function renderBoxesAndLines(
     (n) => n.description && n.description.length > 0
   );
   const willRenderLegend =
-    parsed.tagGroups.length > 0 ||
+    legendGroups.length > 0 ||
     (reserveHasDescriptions && controlsHost !== 'app');
   const sLegendHeight = willRenderLegend
     ? sctx.structural(
         getMaxLegendReservedHeight(
           {
-            groups: parsed.tagGroups,
+            groups: legendGroups,
             position: { placement: 'top-center', titleRelation: 'below-title' },
             mode: exportMode ? 'export' : 'preview',
           },
@@ -390,12 +496,6 @@ export function renderBoxesAndLines(
       )
     : 0;
 
-  const activeGroup = resolveActiveTagGroup(
-    parsed.tagGroups,
-    parsed.options['active-tag'],
-    activeTagGroup
-  );
-
   // Build hidden set
   const hidden = hiddenTagValues ?? parsed.initialHiddenTagValues;
 
@@ -414,7 +514,7 @@ export function renderBoxesAndLines(
     (n) => n.description && n.description.length > 0
   );
   const needsLegend =
-    parsed.tagGroups.length > 0 || (hasAnyDescriptions && onToggleDescriptions);
+    legendGroups.length > 0 || (hasAnyDescriptions && onToggleDescriptions);
   const legendH = needsLegend ? sLegendHeight + 8 : 0;
 
   const groupLabelsSet = new Set(layout.groups.map((g) => g.label));
@@ -809,6 +909,7 @@ export function renderBoxesAndLines(
       activeGroup,
       palette,
       isDark,
+      { active: activeIsValue, hue: rampHue, fillForValue },
       parsed.options['solid-fill'] === 'on'
     );
 
@@ -826,6 +927,12 @@ export function renderBoxesAndLines(
       nodeG.attr(`data-tag-${key.toLowerCase()}`, val.toLowerCase());
     }
 
+    // Numeric value drives the gradient scrub; guard on !== undefined so a
+    // legitimate `value: 0` still emits data-value="0" (0 is falsy).
+    if (node.value !== undefined) {
+      nodeG.attr('data-value', node.value);
+    }
+
     if (onClickItem) {
       nodeG.on('click', (event: Event) => {
         // Don't intercept clicks on links in description text
@@ -982,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,
@@ -1004,6 +1166,48 @@ export function renderBoxesAndLines(
           .text(fitted.lines[li]!);
       }
     }
+
+    // ── 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 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);
+    }
   }
 
   // ── Render legend ──────────────────────────────────────
@@ -1011,9 +1215,10 @@ export function renderBoxesAndLines(
     (n) => n.description && n.description.length > 0
   );
   // App-hosted: the Descriptions control moves to the app overlay, so a
-  // descriptions-only legend (no tag groups) has nothing left to render.
+  // descriptions-only legend (no tag groups) has nothing left to render. The
+  // value ramp (a synthetic group in legendGroups) also forces a legend.
   const hasLegend =
-    parsed.tagGroups.length > 0 || (hasDescriptions && controlsHost !== 'app');
+    legendGroups.length > 0 || (hasDescriptions && controlsHost !== 'app');
 
   if (hasLegend) {
     // Build controls group for description toggle. App-hosted controls own the
@@ -1035,7 +1240,7 @@ export function renderBoxesAndLines(
     }
 
     const legendConfig: LegendConfig = {
-      groups: parsed.tagGroups,
+      groups: legendGroups,
       position: { placement: 'top-center', titleRelation: 'below-title' },
       mode: exportMode ? 'export' : 'preview',
       // Keep inactive sibling tag groups visible as collapsed pills so the user

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

@@ -6,6 +6,9 @@ export interface BLNode {
   readonly lineNumber: number;
   readonly metadata: Readonly<Record<string, string>>;
   readonly description?: readonly string[];
+  /** Numeric measure lifted from `value: X` metadata (mirror of map's
+   *  `region.value`). Drives the value ramp / choropleth tinting. */
+  readonly value?: number;
 }
 
 export interface BLEdge {
@@ -36,6 +39,12 @@ export interface ParsedBoxesAndLines {
   readonly options: Readonly<Record<string, string>>;
   readonly initialHiddenTagValues: ReadonlyMap<string, ReadonlySet<string>>;
   readonly direction: 'LR' | 'TB';
+  /** `box-metric <label> [color]` — names the value-ramp dimension and
+   *  optionally sets its hue. Mirror of map's `region-metric`. */
+  readonly boxMetric?: string;
+  readonly boxMetricColor?: string;
+  /** `show-values` — print each box's numeric value as text (opt-in). */
+  readonly showValues?: boolean;
   readonly diagnostics: readonly DgmoError[];
   readonly error: string | null;
 }

package/src/completion.ts

@@ -447,6 +447,8 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
       direction: { description: 'Layout direction', values: ['LR', 'TB'] },
       'active-tag': { description: 'Active tag group name' },
       hide: { description: 'Hide tag:value pairs' },
+      'box-metric': { description: 'Metric label for the value ramp' },
+      'show-values': { description: 'Print box values as text' },
     }),
   ],
   [
@@ -740,12 +742,9 @@ export const PIPE_METADATA = new Map<string, PipeContextMap>([
     {
       node: {
         description: { description: 'Node description text' },
+        value: { description: 'Numeric value for the metric ramp' },
       },
-      edge: {
-        width: { description: 'Edge stroke width in pixels' },
-        split: { description: 'Traffic split percentage' },
-        fanout: { description: 'Fanout multiplier (integer >= 1)' },
-      },
+      edge: {},
     },
   ],
   [

package/src/d3.ts

@@ -4238,7 +4238,6 @@ function renderTimelineHorizontalTimeSort(
 ): void {
   const {
     width,
-    height,
     tooltip,
     solid,
     textColor,
@@ -4301,8 +4300,20 @@ function renderTimelineHorizontalTimeSort(
     ? -(topScaleH + markerReserve + ERA_ROW_H / 2)
     : 0;
   const innerWidth = width - margin.left - margin.right;
-  const innerHeight = height - margin.top - margin.bottom;
-  const rowH = Math.min(ctx.structural(28), innerHeight / sorted.length);
+  // 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;
 
   const xScale = d3Scale
     .scaleLinear()
@@ -4313,8 +4324,8 @@ function renderTimelineHorizontalTimeSort(
     .select(container)
     .append('svg')
     .attr('width', width)
-    .attr('height', height)
-    .attr('viewBox', `0 0 ${width} ${height}`)
+    .attr('height', usedHeight)
+    .attr('viewBox', `0 0 ${width} ${usedHeight}`)
     .attr('preserveAspectRatio', 'xMidYMin meet')
     .style('background', bgColor);
 
@@ -7743,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;
@@ -8483,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/editor/keywords.ts

@@ -110,6 +110,9 @@ export const DIRECTIVE_KEYWORDS = new Set([
   'hide',
   'mode',
   'direction',
+  // Boxes-and-lines
+  'box-metric',
+  'show-values',
   // ER
   'notation',
   // Class

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)
 // ============================================================