@diagrammo/dgmo 0.8.20 → 0.8.22

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

@@ -7,7 +7,12 @@ import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import { LEGEND_HEIGHT } from '../utils/legend-constants';
 import { renderLegendD3 } from '../utils/legend-d3';
-import type { LegendConfig, LegendState } from '../utils/legend-types';
+import type {
+  LegendConfig,
+  LegendState,
+  LegendCallbacks,
+  ControlsGroupToggle,
+} from '../utils/legend-types';
 import {
   TITLE_FONT_SIZE,
   TITLE_FONT_WEIGHT,
@@ -17,6 +22,7 @@ import { contrastText, mix } from '../palettes/color-utils';
 import { resolveTagColor, resolveActiveTagGroup } from '../utils/tag-groups';
 import type { TagGroup } from '../utils/tag-groups';
 import type { PaletteColors } from '../palettes';
+import { renderInlineText } from '../utils/inline-markdown';
 import type { ParsedBoxesAndLines, BLNode } from './types';
 import type { BLLayoutResult, BLLayoutNode, BLLayoutEdge } from './layout';
 
@@ -24,7 +30,6 @@ import type { BLLayoutResult, BLLayoutNode, BLLayoutEdge } from './layout';
 const DIAGRAM_PADDING = 20;
 const NODE_FONT_SIZE = 13;
 const MIN_NODE_FONT_SIZE = 9;
-const META_FONT_SIZE = 10;
 const EDGE_LABEL_FONT_SIZE = 11;
 const EDGE_STROKE_WIDTH = 1.5;
 const NODE_STROKE_WIDTH = 1.5;
@@ -32,10 +37,14 @@ const NODE_RX = 8;
 const COLLAPSE_BAR_HEIGHT = 4;
 const ARROWHEAD_W = 5;
 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;
+const GROUP_LABEL_ZONE = 32;
 
 type D3G = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
 type D3Svg = d3Selection.Selection<SVGSVGElement, unknown, null, undefined>;
@@ -45,19 +54,13 @@ const lineGeneratorLR = d3Shape
   .line<{ x: number; y: number }>()
   .x((d) => d.x)
   .y((d) => d.y)
-  .curve(d3Shape.curveMonotoneX);
+  .curve(d3Shape.curveBasis);
 
 const lineGeneratorTB = d3Shape
   .line<{ x: number; y: number }>()
   .x((d) => d.x)
   .y((d) => d.y)
-  .curve(d3Shape.curveMonotoneY);
-
-const lineGeneratorLinear = d3Shape
-  .line<{ x: number; y: number }>()
-  .x((d) => d.x)
-  .y((d) => d.y)
-  .curve(d3Shape.curveLinear);
+  .curve(d3Shape.curveBasis);
 
 // ── Text fitting ───────────────────────────────────────────
 
@@ -86,13 +89,25 @@ function splitCamelCase(word: string): string[] {
   return parts.length > 1 ? parts : [word];
 }
 
-function fitTextToNode(
+/**
+ * Fit a label into a header zone for described nodes.
+ * Strategy: split first (spaces, dashes, camelCase), wrap into lines,
+ * shrink font if needed, truncate individual lines with "…" — never hard-break.
+ */
+function fitLabelToHeader(
   label: string,
   nodeWidth: number,
-  nodeHeight: number
+  maxLines: number
 ): { lines: string[]; fontSize: number } {
   const maxTextWidth = nodeWidth - NODE_TEXT_PADDING * 2;
-  const lineHeight = 1.3;
+
+  // Split on spaces and dashes, then camelCase split each part
+  const rawParts = label.split(/(\s+|-)/);
+  const words: string[] = [];
+  for (const part of rawParts) {
+    if (!part || /^\s+$/.test(part) || part === '-') continue;
+    words.push(...splitCamelCase(part));
+  }
 
   for (
     let fontSize = NODE_FONT_SIZE;
@@ -100,17 +115,15 @@ function fitTextToNode(
     fontSize--
   ) {
     const charWidth = fontSize * CHAR_WIDTH_RATIO;
-    const maxCharsPerLine = Math.floor(maxTextWidth / charWidth);
-    const maxLines = Math.floor((nodeHeight - 8) / (fontSize * lineHeight));
-    if (maxCharsPerLine < 2 || maxLines < 1) continue;
-    if (label.length <= maxCharsPerLine) return { lines: [label], fontSize };
+    const maxChars = Math.floor(maxTextWidth / charWidth);
+    if (maxChars < 2) continue;
 
-    const words = label.split(/\s+/);
+    // Wrap words into lines
     const lines: string[] = [];
     let current = '';
     for (const word of words) {
       const test = current ? `${current} ${word}` : word;
-      if (test.length <= maxCharsPerLine) {
+      if (test.length <= maxChars) {
         current = test;
       } else {
         if (current) lines.push(current);
@@ -118,54 +131,39 @@ function fitTextToNode(
       }
     }
     if (current) lines.push(current);
-    if (
-      lines.length <= maxLines &&
-      lines.every((l) => l.length <= maxCharsPerLine)
-    ) {
+
+    // All lines fit at this font? Done.
+    if (lines.length <= maxLines && lines.every((l) => l.length <= maxChars)) {
       return { lines, fontSize };
     }
 
-    // CamelCase split
-    const camelWords: string[] = [];
-    for (const word of words) {
-      if (word.length > maxCharsPerLine)
-        camelWords.push(...splitCamelCase(word));
-      else camelWords.push(word);
-    }
-    const camelLines: string[] = [];
-    let cc = '';
-    for (const word of camelWords) {
-      const test = cc ? `${cc} ${word}` : word;
-      if (test.length <= maxCharsPerLine) {
-        cc = test;
-      } else {
-        if (cc) camelLines.push(cc);
-        cc = word;
-      }
-    }
-    if (cc) camelLines.push(cc);
-    if (
-      camelLines.length <= maxLines &&
-      camelLines.every((l) => l.length <= maxCharsPerLine)
-    ) {
-      return { lines: camelLines, 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
+      );
+      return { lines: result, fontSize };
     }
 
-    if (fontSize > MIN_NODE_FONT_SIZE) continue;
-
-    // Hard-break
-    const hardLines: string[] = [];
-    for (const line of camelLines) {
-      if (line.length <= maxCharsPerLine) hardLines.push(line);
-      else
-        for (let i = 0; i < line.length; i += maxCharsPerLine)
-          hardLines.push(line.slice(i, i + maxCharsPerLine));
+    // 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
+      );
+    const last = result[maxLines - 1];
+    if (!last.endsWith('\u2026')) {
+      result[maxLines - 1] =
+        last.length >= maxChars
+          ? last.slice(0, maxChars - 1) + '\u2026'
+          : last + '\u2026';
     }
-    if (hardLines.length <= maxLines) return { lines: hardLines, fontSize };
+    return { lines: result, fontSize };
   }
 
+  // Fallback at min font
   const charWidth = MIN_NODE_FONT_SIZE * CHAR_WIDTH_RATIO;
-  const maxChars = Math.floor((nodeWidth - NODE_TEXT_PADDING * 2) / charWidth);
+  const maxChars = Math.floor(maxTextWidth / charWidth);
   const truncated =
     label.length > maxChars ? label.slice(0, maxChars - 1) + '\u2026' : label;
   return { lines: [truncated], fontSize: MIN_NODE_FONT_SIZE };
@@ -297,6 +295,10 @@ interface BLRenderOptions {
   exportDims?: { width?: number; height?: number };
   activeTagGroup?: string | null;
   hiddenTagValues?: Map<string, Set<string>>;
+  hideDescriptions?: boolean;
+  controlsExpanded?: boolean;
+  onToggleDescriptions?: (active: boolean) => void;
+  onToggleControlsExpand?: () => void;
 }
 
 export function renderBoxesAndLines(
@@ -307,8 +309,16 @@ export function renderBoxesAndLines(
   isDark: boolean,
   options?: BLRenderOptions
 ): void {
-  const { onClickItem, exportDims, activeTagGroup, hiddenTagValues } =
-    options ?? {};
+  const {
+    onClickItem,
+    exportDims,
+    activeTagGroup,
+    hiddenTagValues,
+    hideDescriptions,
+    controlsExpanded,
+    onToggleDescriptions,
+    onToggleControlsExpand,
+  } = options ?? {};
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
 
   const width = exportDims?.width ?? container.clientWidth;
@@ -335,9 +345,24 @@ export function renderBoxesAndLines(
 
   // Compute diagram bounds for scaling
   const titleOffset = parsed.title ? 40 : 0;
-  const legendH = parsed.tagGroups.length > 0 ? LEGEND_HEIGHT + 8 : 0;
+  const hasAnyDescriptions = parsed.nodes.some(
+    (n) => n.description && n.description.length > 0
+  );
+  const needsLegend =
+    parsed.tagGroups.length > 0 || (hasAnyDescriptions && onToggleDescriptions);
+  const legendH = needsLegend ? LEGEND_HEIGHT + 8 : 0;
+
+  // Account for group label zone extensions (renderer-only, not in layout.height)
+  const groupLabelsSet = new Set(layout.groups.map((g) => g.label));
+  let labelZoneExtension = 0;
+  for (const group of parsed.groups) {
+    if (group.children.some((c) => groupLabelsSet.has(c))) {
+      labelZoneExtension += GROUP_LABEL_ZONE;
+    }
+  }
+
   const contentW = layout.width;
-  const contentH = layout.height + titleOffset + legendH;
+  const contentH = layout.height + titleOffset + legendH + labelZoneExtension;
 
   const scaleX = width / (contentW + DIAGRAM_PADDING * 2);
   const scaleY = height / (contentH + DIAGRAM_PADDING * 2);
@@ -390,10 +415,29 @@ export function renderBoxesAndLines(
   }
   ensureArrowMarkers(defs, arrowColors);
 
-  // ── Render groups (bottom layer) ───────────────────────
-  for (const group of layout.groups) {
+  // ── Render groups (bottom layer, largest first for nesting) ──
+  const sortedGroups = [...layout.groups].sort(
+    (a, b) => b.width * b.height - a.width * a.height
+  );
+  // Identify groups that contain sub-groups — only those need extra label space
+  const groupLabels = new Set(layout.groups.map((g) => g.label));
+  const hasSubGroups = new Set<string>();
+  for (const group of parsed.groups) {
+    for (const child of group.children) {
+      if (groupLabels.has(child)) hasSubGroups.add(group.label);
+    }
+  }
+
+  for (const group of sortedGroups) {
     const gx = group.x - group.width / 2;
-    const gy = group.y - group.height / 2;
+    // Only extend top for groups that contain sub-groups (dagre under-pads these)
+    const needsExtra = !group.collapsed && hasSubGroups.has(group.label);
+    const gy = needsExtra
+      ? group.y - group.height / 2 - GROUP_LABEL_ZONE
+      : group.y - group.height / 2;
+    const groupHeight = needsExtra
+      ? group.height + GROUP_LABEL_ZONE
+      : group.height;
 
     const groupG = diagramG
       .append('g')
@@ -464,7 +508,7 @@ export function renderBoxesAndLines(
         .attr('x', gx)
         .attr('y', gy)
         .attr('width', group.width)
-        .attr('height', group.height)
+        .attr('height', groupHeight)
         .attr('rx', GROUP_RX)
         .attr('ry', GROUP_RX)
         .attr('fill', mix(palette.surface, palette.bg, 40))
@@ -516,8 +560,73 @@ export function renderBoxesAndLines(
       if (isHidden) continue;
     }
 
-    // Apply parallel y-offset to points
-    const points = le.points.map((p) => ({ x: p.x, y: p.y + le.yOffset }));
+    // Self-loop: render as a smooth circular arc below the node
+    if (le.source === le.target) {
+      const nodeLayout = layoutNodeMap.get(le.source);
+      if (nodeLayout) {
+        const edgeG = diagramG
+          .append('g')
+          .attr('class', 'bl-edge-group')
+          .attr('data-line-number', String(le.lineNumber));
+        edgeGroups.set(i, edgeG as unknown as D3G);
+
+        const markerId = `bl-arrow-${color.replace('#', '')}`;
+        const cx = nodeLayout.x;
+        const cy = nodeLayout.y;
+        const hw = nodeLayout.width / 2;
+        const hh = nodeLayout.height / 2;
+        const pad = 20; // clearance from node edge
+
+        // Arc exits from bottom of right side, swings wide, returns to right of bottom side
+        const startX = cx + hw;
+        const startY = cy + hh * 0.4;
+        const endX = cx + hw * 0.4;
+        const endY = cy + hh;
+
+        // Control points swing far out to create a smooth circular arc
+        const cp1x = startX + hw + pad;
+        const cp1y = startY;
+        const cp2x = endX;
+        const cp2y = endY + hh + pad;
+
+        edgeG
+          .append('path')
+          .attr('class', 'bl-edge')
+          .attr(
+            'd',
+            `M ${startX} ${startY} C ${cp1x} ${cp1y}, ${cp2x} ${cp2y}, ${endX} ${endY}`
+          )
+          .attr('fill', 'none')
+          .attr('stroke', color)
+          .attr('stroke-width', EDGE_STROKE_WIDTH)
+          .attr('marker-end', `url(#${markerId})`);
+      }
+      continue;
+    }
+
+    // Parallel edge fan: construct explicit 5-point geometry so lines
+    // bundle at ports and visibly spread apart in the middle.
+    let points: { x: number; y: number }[];
+    if (le.yOffset !== 0 && le.parallelCount > 1) {
+      const srcLayout = layoutNodeMap.get(le.source);
+      const tgtLayout = layoutNodeMap.get(le.target);
+      const srcY = srcLayout?.y ?? le.points[0]?.y ?? 0;
+      const tgtY = tgtLayout?.y ?? le.points[le.points.length - 1]?.y ?? 0;
+      const srcX = le.points[0]?.x ?? 0;
+      const tgtX = le.points[le.points.length - 1]?.x ?? 0;
+      const midX = (srcX + tgtX) / 2;
+      const midY = (srcY + tgtY) / 2;
+
+      points = [
+        { x: srcX, y: srcY }, // port (bundled)
+        { x: srcX + (midX - srcX) * 0.3, y: srcY + le.yOffset * 0.5 }, // separate
+        { x: midX, y: midY + le.yOffset }, // full spread
+        { x: tgtX - (tgtX - midX) * 0.3, y: tgtY + le.yOffset * 0.5 }, // converge
+        { x: tgtX, y: tgtY }, // port (bundled)
+      ];
+    } else {
+      points = le.points.map((p) => ({ x: p.x, y: p.y }));
+    }
     if (points.length < 2) continue;
 
     const edgeG = diagramG
@@ -527,11 +636,7 @@ export function renderBoxesAndLines(
     edgeGroups.set(i, edgeG as unknown as D3G);
 
     const markerId = `bl-arrow-${color.replace('#', '')}`;
-    const gen = le.deferred
-      ? lineGeneratorLinear
-      : parsed.direction === 'TB'
-        ? lineGeneratorTB
-        : lineGeneratorLR;
+    const gen = parsed.direction === 'TB' ? lineGeneratorTB : lineGeneratorLR;
     const path = edgeG
       .append('path')
       .attr('class', 'bl-edge')
@@ -546,14 +651,25 @@ export function renderBoxesAndLines(
       path.attr('marker-start', `url(#${revId})`);
     }
 
-    // Edge label
+    // 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 * EDGE_LABEL_FONT_SIZE * CHAR_WIDTH_RATIO;
+      const labelH = EDGE_LABEL_FONT_SIZE + 6;
+      let ly: number;
+      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;
+      }
       labelPositions.push({
         x: le.labelX,
-        y: le.labelY + le.yOffset,
+        y: ly,
         width: lw + 8,
-        height: EDGE_LABEL_FONT_SIZE + 6,
+        height: labelH,
         idx: i,
       });
     }
@@ -631,7 +747,12 @@ export function renderBoxesAndLines(
     }
 
     if (onClickItem) {
-      nodeG.on('click', () => onClickItem(node.lineNumber));
+      nodeG.on('click', (event: Event) => {
+        // Don't intercept clicks on links in description text
+        const target = event.target as Element | null;
+        if (target?.closest('a')) return;
+        onClickItem(node.lineNumber);
+      });
     }
 
     // Rectangle card
@@ -652,45 +773,146 @@ export function renderBoxesAndLines(
       .attr('stroke-width', NODE_STROKE_WIDTH);
 
     // All text centered vertically using dominant-baseline: central
-    if (node.description) {
-      const lineH = NODE_FONT_SIZE * 1.3;
-      const gap = 2;
-      const totalH = lineH + gap + META_FONT_SIZE;
-      const labelY = -totalH / 2 + lineH / 2;
-      const descY = labelY + lineH / 2 + gap + META_FONT_SIZE / 2;
+    const desc = node.description;
+    if (desc && desc.length > 0 && !hideDescriptions) {
+      // Label in header zone — split on spaces/dashes/camelCase, up to 3 lines
+      const MAX_LABEL_LINES = 3;
+      const fitted = fitLabelToHeader(node.label, ln.width, MAX_LABEL_LINES);
+      const labelLines = fitted.lines;
+      const labelLineH = fitted.fontSize * 1.3;
+      const labelTotalH = labelLines.length * labelLineH;
+      const headerH = labelTotalH + 12; // 12px padding
+      const headerCenterY = -ln.height / 2 + headerH / 2;
+      for (let li = 0; li < labelLines.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(labelLines[li]);
+      }
 
+      // Separator line (full width, matches infra style)
+      const sepY = -ln.height / 2 + headerH;
       nodeG
-        .append('text')
-        .attr('x', 0)
-        .attr('y', labelY)
-        .attr('text-anchor', 'middle')
-        .attr('dominant-baseline', 'central')
-        .attr('font-size', NODE_FONT_SIZE)
-        .attr('font-weight', '600')
-        .attr('fill', colors.text)
-        .text(node.label);
-
-      const maxChars = Math.floor(
-        (ln.width - NODE_TEXT_PADDING * 2) / (META_FONT_SIZE * CHAR_WIDTH_RATIO)
+        .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);
+
+      // Description lines with word wrapping and inline markdown
+      const descStartY = sepY + 4 + DESC_FONT_SIZE;
+      const maxTextWidth = ln.width - NODE_TEXT_PADDING * 2;
+      const charsPerLine = Math.floor(
+        maxTextWidth / (DESC_FONT_SIZE * CHAR_WIDTH_RATIO)
       );
-      const desc =
-        node.description.length > maxChars
-          ? node.description.slice(0, maxChars - 1) + '\u2026'
-          : node.description;
-      const descEl = nodeG
-        .append('text')
-        .attr('x', 0)
-        .attr('y', descY)
-        .attr('text-anchor', 'middle')
-        .attr('dominant-baseline', 'central')
-        .attr('font-size', META_FONT_SIZE)
-        .attr('fill', palette.textMuted)
-        .text(desc);
-      if (desc !== node.description) {
-        descEl.append('title').text(node.description);
+      const descLineH = DESC_FONT_SIZE * DESC_LINE_HEIGHT;
+
+      // Estimate display length — strip markdown syntax for measurement
+      const displayLen = (text: string): number =>
+        text
+          .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // [text](url) → text
+          .replace(/\*\*(.+?)\*\*/g, '$1') // **bold** → bold
+          .replace(/\*(.+?)\*/g, '$1') // *italic* → italic
+          .replace(/`(.+?)`/g, '$1') // `code` → code
+          .replace(/https?:\/\/\S+/g, (u) => u.slice(0, 20)).length; // bare URLs shortened
+      const hasMarkdown = (text: string): boolean =>
+        /\[.+?\]\(.+?\)|https?:\/\/|www\./.test(text);
+
+      // Build wrapped lines from description
+      const wrappedLines: string[] = [];
+      for (let descLine of desc) {
+        // Render `- ` as bullet
+        if (descLine.startsWith('- ')) descLine = '\u2022 ' + descLine.slice(2);
+        // Normalize bare URLs: `http example.com` → `http://example.com`
+        descLine = descLine.replace(
+          /\bhttps?\s+([\w][\w.-]+\.[a-z]{2,}(?:\/\S*)?)/gi,
+          (_, domain) => `https://${domain}`
+        );
+        if (displayLen(descLine) <= charsPerLine) {
+          wrappedLines.push(descLine);
+        } else {
+          // Word wrap using display lengths
+          // Keep bullet attached to first word
+          let words: string[];
+          if (descLine.startsWith('\u2022 ')) {
+            const rest = descLine.slice(2);
+            const restWords = rest.split(/\s+/);
+            words = [`\u2022 ${restWords[0]}`, ...restWords.slice(1)];
+          } else {
+            words = descLine.split(/\s+/);
+          }
+          let current = '';
+          for (const word of words) {
+            const test = current ? `${current} ${word}` : word;
+            if (displayLen(test) <= charsPerLine) {
+              current = test;
+            } else {
+              if (current) wrappedLines.push(current);
+              // Don't truncate words containing markdown/links
+              current =
+                !hasMarkdown(word) && word.length > charsPerLine
+                  ? word.slice(0, charsPerLine - 1) + '\u2026'
+                  : word;
+            }
+          }
+          if (current) wrappedLines.push(current);
+        }
+      }
+
+      const truncated = wrappedLines.length > MAX_DESC_LINES;
+      const visibleLines = truncated
+        ? wrappedLines.slice(0, MAX_DESC_LINES)
+        : wrappedLines;
+
+      for (let li = 0; li < visibleLines.length; li++) {
+        let lineText = visibleLines[li];
+        // 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'
+              : lineText + '\u2026';
+        }
+        // Bulleted lines left-align, plain lines center
+        const isBullet = lineText.startsWith('\u2022');
+        const textEl = nodeG
+          .append('text')
+          .attr('x', isBullet ? -ln.width / 2 + 6 : 0)
+          .attr('y', descStartY + li * descLineH)
+          .attr('text-anchor', isBullet ? 'start' : 'middle')
+          .attr('dominant-baseline', 'central')
+          .attr('font-size', DESC_FONT_SIZE)
+          .attr('fill', palette.textMuted);
+        renderInlineText(textEl, lineText, palette, DESC_FONT_SIZE);
+      }
+
+      // Tooltip when truncated
+      if (truncated) {
+        const fullText = desc.join(' ');
+        const tooltipText =
+          fullText.length > 200 ? fullText.slice(0, 199) + '\u2026' : fullText;
+        nodeG.append('title').text(tooltipText);
       }
     } else {
-      const fitted = fitTextToNode(node.label, ln.width - 16, ln.height);
+      // Compact label — use same split-first algorithm (camelCase, no hard-break)
+      // 16px vertical padding (8 top + 8 bottom) to keep text off borders
+      const maxLabelLines = Math.max(
+        2,
+        Math.floor((ln.height - 16) / (MIN_NODE_FONT_SIZE * 1.3))
+      );
+      const fitted = fitLabelToHeader(node.label, ln.width, maxLabelLines);
       const lineH = fitted.fontSize * 1.3;
       const totalH = fitted.lines.length * lineH;
       for (let li = 0; li < fitted.lines.length; li++) {
@@ -709,13 +931,46 @@ export function renderBoxesAndLines(
   }
 
   // ── Render legend ──────────────────────────────────────
-  if (parsed.tagGroups.length > 0) {
+  const hasDescriptions = parsed.nodes.some(
+    (n) => n.description && n.description.length > 0
+  );
+  const hasLegend = parsed.tagGroups.length > 0 || hasDescriptions;
+
+  if (hasLegend) {
+    // Build controls group for description toggle
+    let controlsGroup: { toggles: ControlsGroupToggle[] } | undefined;
+    if (hasDescriptions && onToggleDescriptions) {
+      controlsGroup = {
+        toggles: [
+          {
+            id: 'descriptions',
+            type: 'toggle',
+            label: 'Descriptions',
+            active: !hideDescriptions,
+            onToggle: () => {},
+          },
+        ],
+      };
+    }
+
     const legendConfig: LegendConfig = {
       groups: parsed.tagGroups,
       position: { placement: 'top-center', titleRelation: 'below-title' },
       mode: 'fixed',
+      controlsGroup,
+    };
+    const legendState: LegendState = {
+      activeGroup,
+      controlsExpanded,
+    };
+    const legendCallbacks: LegendCallbacks = {
+      onControlsExpand: onToggleControlsExpand,
+      onControlsToggle: (toggleId, active) => {
+        if (toggleId === 'descriptions' && onToggleDescriptions) {
+          onToggleDescriptions(active);
+        }
+      },
     };
-    const legendState: LegendState = { activeGroup };
     const legendG = svg
       .append('g')
       .attr('transform', `translate(0,${titleOffset + 4})`);
@@ -725,7 +980,7 @@ export function renderBoxesAndLines(
       legendState,
       palette,
       isDark,
-      undefined,
+      legendCallbacks,
       width
     );
     legendG.selectAll('[data-legend-group]').classed('bl-legend-group', true);
@@ -743,10 +998,12 @@ export function renderBoxesAndLinesForExport(
   options?: {
     exportDims?: { width: number; height: number };
     activeTagGroup?: string | null;
+    hiddenTagValues?: Map<string, Set<string>>;
   }
 ): void {
   renderBoxesAndLines(container, parsed, layout, palette, isDark, {
     exportDims: options?.exportDims,
     activeTagGroup: options?.activeTagGroup,
+    hiddenTagValues: options?.hiddenTagValues,
   });
 }