@diagrammo/dgmo 0.26.0 → 0.28.0

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

@@ -26,7 +26,7 @@ import {
   extractColor,
   parseFirstLine,
   OPTION_NOCOLON_RE,
-  peelTrailingColorName,
+  peelRampColors,
   splitNameAndMeta,
   tryParseSharedOption,
   warnUnknownMetaKeys,
@@ -35,6 +35,8 @@ import {
   BOXES_AND_LINES_REGISTRY,
   withTagAliases,
 } from '../utils/reserved-key-registry';
+import { tryCollectNote, resolveNotes, type DiagramNote } from '../utils/notes';
+import type { PaletteColors } from '../palettes';
 
 const MAX_GROUP_DEPTH = 2;
 
@@ -113,8 +115,12 @@ type MutBLGroup = Omit<Writable<BLGroup>, 'metadata' | 'children'> & {
   children: string[];
 };
 
-export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
+export function parseBoxesAndLines(
+  content: string,
+  palette?: PaletteColors
+): ParsedBoxesAndLines {
   const options: Record<string, string> = {};
+  const notes: DiagramNote[] = [];
   const initialHiddenTagValues = new Map<string, Set<string>>();
   const nodes: MutBLNode[] = [];
   const edges: MutBLEdge[] = [];
@@ -305,11 +311,10 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
         const metricMatch = trimmed.match(/^box-metric\s+(.+)$/i);
         if (metricMatch) {
           // Regex capture group present after successful match.
-          const { label, colorName } = peelTrailingColorName(
-            metricMatch[1]!.trim()
-          );
+          const { label, low, high } = peelRampColors(metricMatch[1]!.trim());
           result.boxMetric = label;
-          if (colorName !== undefined) result.boxMetricColor = colorName;
+          if (high !== undefined) result.boxMetricColor = high;
+          if (low !== undefined) result.boxMetricLowColor = low;
           continue;
         }
         if (/^show-values$/i.test(trimmed)) {
@@ -336,6 +341,24 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
       }
     }
 
+    // Note annotation (top-level): `note <Box> [inline body]` + an optional
+    // indented body. Checked before tag/group/node/edge matching so a note is
+    // never mistaken for a box; gated to indent 0. `note -> X` is excluded.
+    if (indent === 0) {
+      const noteResult = tryCollectNote(
+        lines,
+        i,
+        indent,
+        palette,
+        result.diagnostics
+      );
+      if (noteResult) {
+        if (noteResult.note) notes.push(noteResult.note);
+        i = noteResult.lastIndex;
+        continue;
+      }
+    }
+
     // Tag group heading — must be checked BEFORE group/node/edge matching
     const tagBlockMatch = matchTagBlockHeading(trimmed);
     if (tagBlockMatch && indent === 0) {
@@ -721,6 +744,17 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
   }
   result.edges = validEdges;
 
+  // Resolve note refs against box labels (forward refs OK). The id→note
+  // binding is recomputed in layout; this pass surfaces diagnostics.
+  if (notes.length > 0) {
+    result.notes = notes;
+    resolveNotes(
+      notes,
+      result.nodes.map((n) => ({ id: n.label, label: n.label })),
+      result.diagnostics
+    );
+  }
+
   // Post-parse: inject default tag metadata and validate tag values
   if (result.tagGroups.length > 0) {
     injectDefaultTagMetadata(result.nodes, result.tagGroups);
@@ -1007,8 +1041,9 @@ function parseEdgeLine(
     };
   }
 
-  // Check for labeled arrow: `Source -label-> Target`
-  const labeledMatch = trimmed.match(/^(.+?)\s+-(.+)->\s*(.+)$/);
+  // Check for labeled arrow: `Source -label-> Target` (label lazy → split
+  // at the first arrow, consistent with the other parsers).
+  const labeledMatch = trimmed.match(/^(.+?)\s+-(.+?)->\s*(.+)$/);
   if (labeledMatch) {
     // Regex capture groups present after successful match.
     const rawSource = labeledMatch[1]!.trim();

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

@@ -3,6 +3,13 @@
 // ============================================================
 
 import * as d3Selection from 'd3-selection';
+import {
+  renderNoteBox,
+  renderNoteConnector,
+  renderNoteBadge,
+  noteConnectorPoints,
+  NOTE_BADGE_RADIUS,
+} from '../utils/note-box';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import { renderLegendD3 } from '../utils/legend-d3';
@@ -19,7 +26,13 @@ import {
   TITLE_FONT_WEIGHT,
   TITLE_Y,
 } from '../utils/title-constants';
-import { contrastText, mix, shapeFill } from '../palettes/color-utils';
+import {
+  contrastText,
+  mix,
+  relativeLuminance,
+  shapeFill,
+  valueRampColor,
+} from '../palettes/color-utils';
 import { resolveColor } from '../colors';
 import { resolveTagColor } from '../utils/tag-groups';
 import type { TagGroup } from '../utils/tag-groups';
@@ -32,6 +45,11 @@ import {
 import type { ParsedBoxesAndLines, BLNode } from './types';
 import type { BLLayoutResult, BLLayoutNode, BLLayoutEdge } from './layout';
 import { ScaleContext } from '../utils/scaling';
+import {
+  CHAR_WIDTH_RATIO,
+  measureText,
+  truncateText,
+} from '../utils/text-measure';
 
 // ── Constants (aligned with infra pattern) ─────────────────
 const DIAGRAM_PADDING = 20;
@@ -49,7 +67,6 @@ const ARROWHEAD_H = 4;
 const DESC_FONT_SIZE = 10; // matches infra META_FONT_SIZE
 const DESC_LINE_HEIGHT = 1.4; // 14px row height at 10px font (matches infra META_LINE_HEIGHT)
 const MAX_DESC_LINES = 6;
-const CHAR_WIDTH_RATIO = 0.6;
 const NODE_TEXT_PADDING = 12;
 const GROUP_RX = 8;
 const GROUP_LABEL_FONT_SIZE = 14;
@@ -127,16 +144,14 @@ function fitLabelToHeader(
     fontSize >= MIN_NODE_FONT_SIZE;
     fontSize--
   ) {
-    const charWidth = fontSize * CHAR_WIDTH_RATIO;
-    const maxChars = Math.floor(maxTextWidth / charWidth);
-    if (maxChars < 2) continue;
+    if (maxTextWidth < measureText('MM', fontSize)) continue;
 
-    // Wrap words into lines
+    // Wrap words into lines (greedy, by measured pixel width)
     const lines: string[] = [];
     let current = '';
     for (const word of words) {
       const test = current ? `${current} ${word}` : word;
-      if (test.length <= maxChars) {
+      if (measureText(test, fontSize) <= maxTextWidth) {
         current = test;
       } else {
         if (current) lines.push(current);
@@ -145,15 +160,18 @@ function fitLabelToHeader(
     }
     if (current) lines.push(current);
 
+    const fits = (l: string): boolean =>
+      measureText(l, fontSize) <= maxTextWidth;
+
     // All lines fit at this font? Done.
-    if (lines.length <= maxLines && lines.every((l) => l.length <= maxChars)) {
+    if (lines.length <= maxLines && lines.every(fits)) {
       return { lines, fontSize };
     }
 
     // Lines fit in count but some are too wide? Truncate those lines.
     if (lines.length <= maxLines) {
       const result = lines.map((l) =>
-        l.length > maxChars ? l.slice(0, maxChars - 1) + '\u2026' : l
+        fits(l) ? l : truncateText(l, fontSize, maxTextWidth)
       );
       return { lines: result, fontSize };
     }
@@ -161,25 +179,21 @@ function fitLabelToHeader(
     // Too many lines — take first maxLines, truncate last + any oversized
     const result = lines
       .slice(0, maxLines)
-      .map((l) =>
-        l.length > maxChars ? l.slice(0, maxChars - 1) + '\u2026' : l
-      );
+      .map((l) => (fits(l) ? l : truncateText(l, fontSize, maxTextWidth)));
     // In-bounds: result has exactly maxLines entries (from .slice(0, maxLines)).
     const last = result[maxLines - 1]!;
     if (!last.endsWith('\u2026')) {
-      result[maxLines - 1] =
-        last.length >= maxChars
-          ? last.slice(0, maxChars - 1) + '\u2026'
-          : last + '\u2026';
+      result[maxLines - 1] = truncateText(
+        last + '\u2026',
+        fontSize,
+        maxTextWidth
+      );
     }
     return { lines: result, fontSize };
   }
 
   // Fallback at min font
-  const charWidth = MIN_NODE_FONT_SIZE * CHAR_WIDTH_RATIO;
-  const maxChars = Math.floor(maxTextWidth / charWidth);
-  const truncated =
-    label.length > maxChars ? label.slice(0, maxChars - 1) + '\u2026' : label;
+  const truncated = truncateText(label, MIN_NODE_FONT_SIZE, maxTextWidth);
   return { lines: [truncated], fontSize: MIN_NODE_FONT_SIZE };
 }
 
@@ -194,20 +208,40 @@ function nodeColors(
   value: {
     active: boolean;
     hue: string;
+    /** Two explicit endpoint colours (`box-metric Risk green red`). When set, the
+     *  value's position on the ramp is carried by HUE, so the box follows the
+     *  STANDARD box convention (solid colour outline + 25% faded fill) rather than
+     *  the map's saturated choropleth fill. A single-colour ramp encodes value by
+     *  saturation/lightness and keeps the choropleth fill (no hue to spare). */
+    twoColor: boolean;
     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;
+    if (node.value === undefined) {
+      // No-value box: neutral fill, ramp-hue stroke (present so the app's
+      // --bl-node-stroke hover-dim still works).
+      const text = contrastText(
+        neutralFill,
+        palette.textOnFillLight,
+        palette.textOnFillDark
+      );
+      return { fill: neutralFill, stroke: value.hue, text };
+    }
+    // Value box: render the ramp colour like any tagged box — a 25% faded
+    // (muted) fill + a solid colour outline; `solid-fill` opts into the full
+    // fill. The outline differs by ramp kind: a two-colour ramp carries value by
+    // HUE, so each box's outline is its own ramp colour (red→green); a
+    // single-colour ramp has one hue, so the outline is the constant ramp hue and
+    // value reads from the muted fill depth.
+    const rampColor = value.fillForValue(node.value);
+    const fill = shapeFill(palette, rampColor, isDark, {
+      ...(solid !== undefined && { solid }),
+    });
+    const stroke = value.twoColor ? rampColor : value.hue;
     const text = contrastText(
       fill,
       palette.textOnFillLight,
@@ -306,6 +340,43 @@ function ensureArrowMarkers(
   }
 }
 
+// ── Edge label placement ───────────────────────────────────
+
+/** Point at the half-way arc length along an edge polyline — the geometric
+ *  centre of the connector, so a label sits in the gap BETWEEN the two nodes
+ *  (ELK's own label anchor drifts toward the target and ends up clipped under
+ *  it). Falls back gracefully for degenerate point lists. */
+function edgePolylineMidpoint(
+  points: ReadonlyArray<{ readonly x: number; readonly y: number }>
+): { x: number; y: number } {
+  if (points.length === 0) return { x: 0, y: 0 };
+  if (points.length === 1) return { x: points[0]!.x, y: points[0]!.y };
+  let total = 0;
+  const segLen: number[] = [];
+  for (let k = 1; k < points.length; k++) {
+    const len = Math.hypot(
+      points[k]!.x - points[k - 1]!.x,
+      points[k]!.y - points[k - 1]!.y
+    );
+    segLen.push(len);
+    total += len;
+  }
+  let half = total / 2;
+  for (let k = 1; k < points.length; k++) {
+    const len = segLen[k - 1]!;
+    if (half <= len || k === points.length - 1) {
+      const t = len === 0 ? 0 : Math.min(1, half / len);
+      return {
+        x: points[k - 1]!.x + (points[k]!.x - points[k - 1]!.x) * t,
+        y: points[k - 1]!.y + (points[k]!.y - points[k - 1]!.y) * t,
+      };
+    }
+    half -= len;
+  }
+  const last = points[points.length - 1]!;
+  return { x: last.x, y: last.y };
+}
+
 // ── Edge label overlap resolution ──────────────────────────
 
 function resolveEdgeLabelOverlaps(
@@ -407,19 +478,32 @@ export function renderBoxesAndLines(
     .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);
+  // Anchor the low end at the lowest value (not 0) to maximise within-diagram
+  // dynamic range; mirrors the map's region-metric ramp. Equal-value data
+  // (rampMin === rampMax) falls back to t = 1 in fillForValue below.
+  const rampMin = hasRamp ? Math.min(...nodeValues) : 0;
   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;
+  // Explicit LOW endpoint (`box-metric Risk green red`); absent ⇒ single-colour
+  // (neutral low). Only recognized names peel, so resolveColor always succeeds.
+  const rampLow = parsed.boxMetricLowColor
+    ? (resolveColor(parsed.boxMetricLowColor, palette) ?? undefined)
+    : undefined;
   // 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 rampLowFloor = mix(rampHue, rampBase, RAMP_FLOOR);
   const fillForValue = (v: number): string => {
     const t = rampMax > rampMin ? (v - rampMin) / (rampMax - rampMin) : 1;
+    // Two-colour ramp: shared low→high interpolation (direct or via midpoint).
+    if (rampLow !== undefined)
+      return valueRampColor(rampLow, rampHue, t, { isDark });
+    // Single/zero-colour: byte-identical to pre-change (same numeric pct, no
+    // float round-trip).
     const pct = RAMP_FLOOR + Math.max(0, Math.min(1, t)) * (100 - RAMP_FLOOR);
     return mix(rampHue, rampBase, pct);
   };
@@ -464,8 +548,8 @@ export function renderBoxesAndLines(
           gradient: {
             min: rampMin,
             max: rampMax,
-            hue: rampHue,
-            base: rampBase,
+            low: rampLow ?? rampLowFloor,
+            high: rampHue,
           },
         }
       : null;
@@ -829,22 +913,19 @@ export function renderBoxesAndLines(
       path.attr('marker-start', `url(#${revId})`);
     }
 
-    // Edge label — for parallel edges, place relative to each line:
-    // negative offset (top line) → label above, zero → on line, positive → below
-    if (le.label && le.labelX != null && le.labelY != null) {
-      const lw = le.label.length * sEdgeLabelFontSize * CHAR_WIDTH_RATIO;
+    // Edge label — centred on the connector's polyline midpoint (the gap
+    // between the two nodes), NOT ELK's target-biased anchor. For parallel
+    // edges, nudge above/below so each line's label clears the line.
+    if (le.label && le.points.length > 0) {
+      const lw = measureText(le.label, sEdgeLabelFontSize);
       const labelH = sEdgeLabelFontSize + 6;
-      let ly: number;
+      const mid = edgePolylineMidpoint(le.points);
+      let ly = mid.y;
       if (le.parallelCount > 1 && le.yOffset !== 0) {
-        // Position label on the line at midpoint, shifted above/below based on offset sign
-        const lineY = le.labelY + 10 + le.yOffset; // +10 to undo the -10 in layout
-        const labelShift = le.yOffset < 0 ? -labelH : labelH;
-        ly = lineY + labelShift * 0.5;
-      } else {
-        ly = le.labelY + le.yOffset;
+        ly += (le.yOffset < 0 ? -labelH : labelH) * 0.5;
       }
       labelPositions.push({
-        x: le.labelX,
+        x: mid.x,
         y: ly,
         width: lw + 8,
         height: labelH,
@@ -903,15 +984,24 @@ export function renderBoxesAndLines(
       if (isHidden) continue;
     }
 
+    const solid = parsed.options['solid-fill'] === 'on';
     const colors = nodeColors(
       node,
       parsed.tagGroups,
       activeGroup,
       palette,
       isDark,
-      { active: activeIsValue, hue: rampHue, fillForValue },
-      parsed.options['solid-fill'] === 'on'
+      {
+        active: activeIsValue,
+        hue: rampHue,
+        twoColor: rampLow !== undefined,
+        fillForValue,
+      },
+      solid
     );
+    // Divider matches the org-card convention: the box stroke normally, but the
+    // contrast text colour in solid mode (where stroke == fill and would vanish).
+    const dividerStroke = solid ? colors.text : colors.stroke;
 
     const nodeG = diagramG
       .append('g')
@@ -980,13 +1070,14 @@ export function renderBoxesAndLines(
           .attr('text-anchor', 'middle')
           .attr('dominant-baseline', 'central')
           .attr('font-size', fitted.fontSize)
-          .attr('font-weight', '600')
+          .attr('font-weight', 'bold')
           .attr('fill', colors.text)
           // In-bounds by loop guard.
           .text(labelLines[li]!);
       }
 
-      // Separator line (full width, matches infra style)
+      // Single divider under the title (org-card convention) — everything else
+      // renders below it as one body section (no second divider / footer band).
       const sepY = -ln.height / 2 + headerH;
       nodeG
         .append('line')
@@ -994,12 +1085,15 @@ export function renderBoxesAndLines(
         .attr('y1', sepY)
         .attr('x2', ln.width / 2)
         .attr('y2', sepY)
-        .attr('stroke', colors.stroke)
+        .attr('stroke', dividerStroke)
         .attr('stroke-opacity', 0.3)
         .attr('stroke-width', 1);
 
       const descStartY = sepY + 4 + sDescFontSize;
       const maxTextWidth = ln.width - NODE_TEXT_PADDING * 2;
+      // Char budget for the shared (char-based) bullet-aware wrapper. Derived
+      // from the shared average glyph ratio so it stays in step with the
+      // pixel measurer used everywhere else here.
       const charsPerLine = Math.floor(
         maxTextWidth / (sDescFontSize * CHAR_WIDTH_RATIO)
       );
@@ -1046,6 +1140,16 @@ export function renderBoxesAndLines(
       const BULLET_GLYPH_X = -ln.width / 2 + 6;
       const BULLET_BODY_X = BULLET_GLYPH_X + 10;
 
+      // Description must stay legible on ANY fill. On the default light/tinted
+      // fills keep the subtle muted grey; on a dark/saturated fill (e.g.
+      // solid-fill) the fixed grey sinks in — switch to a muted tint of the
+      // box's contrast-correct text colour so it reads while staying
+      // subordinate to the title.
+      const descColor =
+        relativeLuminance(colors.fill) > 0.5
+          ? palette.textMuted
+          : mix(colors.text, colors.fill, 75);
+
       for (let li = 0; li < visibleLines.length; li++) {
         // In-bounds by loop guard.
         const line = visibleLines[li]!;
@@ -1053,8 +1157,8 @@ export function renderBoxesAndLines(
         // Truncate last line if there are more lines beyond the cap
         if (truncated && li === visibleLines.length - 1) {
           lineText =
-            lineText.length >= charsPerLine
-              ? lineText.slice(0, charsPerLine - 1) + '\u2026'
+            measureText(lineText, sDescFontSize) >= maxTextWidth
+              ? truncateText(lineText, sDescFontSize, maxTextWidth)
               : lineText + '\u2026';
         }
         const y = descStartY + li * descLineH;
@@ -1066,7 +1170,7 @@ export function renderBoxesAndLines(
             .attr('text-anchor', 'start')
             .attr('dominant-baseline', 'central')
             .attr('font-size', sDescFontSize)
-            .attr('fill', palette.textMuted)
+            .attr('fill', descColor)
             .text('\u2022');
         }
         const isBullet =
@@ -1078,7 +1182,7 @@ export function renderBoxesAndLines(
           .attr('text-anchor', isBullet ? 'start' : 'middle')
           .attr('dominant-baseline', 'central')
           .attr('font-size', DESC_FONT_SIZE)
-          .attr('fill', palette.textMuted);
+          .attr('fill', descColor);
         renderInlineText(textEl, lineText, palette, sDescFontSize);
       }
 
@@ -1089,6 +1193,25 @@ export function renderBoxesAndLines(
           fullText.length > 200 ? fullText.slice(0, 199) + '\u2026' : fullText;
         nodeG.append('title').text(tooltipText);
       }
+
+      // Value sits in the SAME body section, directly after the description \u2014
+      // no second divider / footer band (org-card: title, one line, body).
+      if (parsed.showValues && node.value !== undefined) {
+        const valueLabel = parsed.boxMetric
+          ? `${parsed.boxMetric}: ${node.value}`
+          : String(node.value);
+        nodeG
+          .append('text')
+          .attr('class', 'bl-node-value')
+          .attr('x', 0)
+          .attr('y', descStartY + visibleLines.length * descLineH)
+          .attr('text-anchor', 'middle')
+          .attr('dominant-baseline', 'central')
+          .attr('font-size', VALUE_FONT_SIZE)
+          .attr('font-weight', '600')
+          .attr('fill', colors.text)
+          .text(valueLabel);
+      }
     } 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
@@ -1116,20 +1239,20 @@ export function renderBoxesAndLines(
           .attr('text-anchor', 'middle')
           .attr('dominant-baseline', 'central')
           .attr('font-size', fitted.fontSize)
-          .attr('font-weight', '600')
+          .attr('font-weight', 'bold')
           .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.
+      // Single divider under the title (org-card convention; solid-aware so it
+      // stays visible when stroke == fill).
       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', dividerStroke)
         .attr('stroke-opacity', 0.3)
         .attr('stroke-width', 1);
       // "Metric: value" centered in the space below the divider.
@@ -1167,46 +1290,50 @@ export function renderBoxesAndLines(
       }
     }
 
-    // ── 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);
+    // ── Note (floated beside the box, or a collapsed corner badge) ──
+    // The box keeps its layout position; the note floats in adjacent space.
+    // Coords are node-center-local (the node `<g>` is at the box center).
+    if (ln.note) {
+      if (ln.note.collapsed) {
+        renderNoteBadge(
+          nodeG,
+          {
+            x: ln.width / 2 - NOTE_BADGE_RADIUS - 3,
+            y: -ln.height / 2 + NOTE_BADGE_RADIUS + 3,
+          },
+          palette,
+          {
+            isDark,
+            ...(ln.note.color && { color: ln.note.color }),
+            lineNumber: ln.note.lineNumber,
+            endLineNumber: ln.note.endLineNumber,
+          }
+        );
+      } else {
+        const [cx1, cy1, cx2, cy2] = noteConnectorPoints(
+          { width: ln.width, height: ln.height },
+          ln.note
+        );
+        renderNoteConnector(nodeG, cx1, cy1, cx2, cy2, palette);
+        renderNoteBox(
+          nodeG,
+          {
+            x: ln.note.x,
+            y: ln.note.y,
+            width: ln.note.width,
+            height: ln.note.height,
+          },
+          ln.note.lines,
+          palette,
+          {
+            isDark,
+            ...(ln.note.color && { color: ln.note.color }),
+            lineNumber: ln.note.lineNumber,
+            endLineNumber: ln.note.endLineNumber,
+            interactive: true,
+          }
+        );
+      }
     }
   }
 

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

@@ -1,5 +1,6 @@
 import type { TagGroup } from '../utils/tag-groups';
 import type { DgmoError } from '../diagnostics';
+import type { DiagramNote } from '../utils/notes';
 
 export interface BLNode {
   readonly label: string;
@@ -37,12 +38,18 @@ export interface ParsedBoxesAndLines {
   readonly groups: readonly BLGroup[];
   readonly tagGroups: readonly TagGroup[];
   readonly options: Readonly<Record<string, string>>;
+  /** Generic node notes (`note <Box> …`); resolved in layout. */
+  readonly notes?: readonly DiagramNote[];
   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`. */
+  /** `box-metric <label> [low] [high]` — names the value-ramp dimension and
+   *  optionally sets its endpoint colours. One color = high hue over a neutral
+   *  low; two = explicit `low high`. Mirror of map's `region-metric`. */
   readonly boxMetric?: string;
+  /** Recognized color NAME for the ramp HIGH endpoint. */
   readonly boxMetricColor?: string;
+  /** Recognized color NAME for the ramp LOW endpoint (two-colour form). */
+  readonly boxMetricLowColor?: string;
   /** `show-values` — print each box's numeric value as text (opt-in). */
   readonly showValues?: boolean;
   readonly diagnostics: readonly DgmoError[];