@diagrammo/dgmo 0.26.0 → 0.27.0

package/src/c4/layout.ts

@@ -21,8 +21,15 @@ type MutableC4LayoutEdge = Writable<C4LayoutEdge> & {
 import {
   LEGEND_PILL_FONT_SIZE,
   LEGEND_ENTRY_FONT_SIZE,
+  LEGEND_HEIGHT,
+  LEGEND_PILL_PAD,
+  LEGEND_DOT_R,
+  LEGEND_ENTRY_DOT_GAP,
+  LEGEND_ENTRY_TRAIL,
+  LEGEND_CAPSULE_PAD,
   measureLegendText,
 } from '../utils/legend-constants';
+import { measureText, wrapTextToWidth } from '../utils/text-measure';
 
 /** dagre node label shape after layout(). */
 interface DagreNodeLabel {
@@ -115,29 +122,23 @@ export interface C4LayoutResult {
 // Constants
 // ============================================================
 
-const CHAR_WIDTH = 8;
 const MIN_NODE_WIDTH = 160;
 const MAX_NODE_WIDTH = 260;
 const TYPE_LABEL_HEIGHT = 18;
 const DIVIDER_GAP = 6;
 const NAME_HEIGHT = 20;
+const NAME_FONT_SIZE = 14;
 const DESC_LINE_HEIGHT = 16;
-const DESC_CHAR_WIDTH = 6.5;
+const DESC_FONT_SIZE = 11;
 const CARD_V_PAD = 14;
 const CARD_H_PAD = 20;
 const META_LINE_HEIGHT = 16;
-const META_CHAR_WIDTH = 6.5;
+const META_FONT_SIZE = 11;
 const MARGIN = 40;
 const BOUNDARY_PAD = 40;
 const GROUP_BOUNDARY_PAD = 24;
 
 // Legend constants (match org)
-const LEGEND_HEIGHT = 28;
-const LEGEND_PILL_PAD = 16;
-const LEGEND_DOT_R = 4;
-const LEGEND_ENTRY_DOT_GAP = 4;
-const LEGEND_ENTRY_TRAIL = 8;
-const LEGEND_CAPSULE_PAD = 4;
 
 // ============================================================
 // Post-Layout Crossing Reduction
@@ -640,24 +641,6 @@ function resolveNodeColor(
 // Node Sizing
 // ============================================================
 
-function wrapText(text: string, maxWidth: number, charWidth: number): string[] {
-  const words = text.split(/\s+/);
-  const lines: string[] = [];
-  let current = '';
-
-  for (const word of words) {
-    const test = current ? `${current} ${word}` : word;
-    if (test.length * charWidth > maxWidth && current) {
-      lines.push(current);
-      current = word;
-    } else {
-      current = test;
-    }
-  }
-  if (current) lines.push(current);
-  return lines;
-}
-
 /** Keys to exclude from the below-divider metadata display. */
 const META_EXCLUDE_KEYS = new Set([
   'description',
@@ -689,7 +672,7 @@ export function computeC4NodeDimensions(
   options?: { showTechnology?: boolean }
 ): { width: number; height: number } {
   // Width: based on name length, clamped
-  const nameWidth = el.name.length * CHAR_WIDTH + CARD_H_PAD * 2;
+  const nameWidth = measureText(el.name, NAME_FONT_SIZE) + CARD_H_PAD * 2;
   let width = Math.max(MIN_NODE_WIDTH, Math.min(MAX_NODE_WIDTH, nameWidth));
 
   if (options?.showTechnology) {
@@ -700,7 +683,7 @@ export function computeC4NodeDimensions(
     const desc = el.description?.join('\n');
     if (desc) {
       const contentWidth = width - CARD_H_PAD * 2;
-      const lines = wrapText(desc, contentWidth, DESC_CHAR_WIDTH);
+      const lines = wrapTextToWidth(desc, DESC_FONT_SIZE, contentWidth);
       height += lines.length * DESC_LINE_HEIGHT;
     }
 
@@ -713,8 +696,7 @@ export function computeC4NodeDimensions(
       const maxMetaWidth = Math.max(
         ...metaEntries.map(
           (e) =>
-            (e.key.length + 2 + e.value.length) * META_CHAR_WIDTH +
-            CARD_H_PAD * 2
+            measureText(`${e.key}: ${e.value}`, META_FONT_SIZE) + CARD_H_PAD * 2
         )
       );
       if (maxMetaWidth > width) width = Math.min(MAX_NODE_WIDTH, maxMetaWidth);
@@ -730,7 +712,7 @@ export function computeC4NodeDimensions(
   const desc = el.description?.join('\n');
   if (desc) {
     const contentWidth = width - CARD_H_PAD * 2;
-    const lines = wrapText(desc, contentWidth, DESC_CHAR_WIDTH);
+    const lines = wrapTextToWidth(desc, DESC_FONT_SIZE, contentWidth);
     height += lines.length * DESC_LINE_HEIGHT;
   }
 

package/src/c4/parser.ts

@@ -63,11 +63,15 @@ const C4_IS_A_RE =
 /** Matches relationship arrows: `->`, `~>`, `<->`, `<~>` */
 const RELATIONSHIP_RE = /^(<?-?>|<?~?>)\s*(.+)$/;
 
-/** Labeled arrow relationships: -label->, ~label~>, <-label->, <~label~> */
-const C4_LABELED_SYNC_RE = /^-(.+)->\s*(.+)$/;
-const C4_LABELED_ASYNC_RE = /^~(.+)~>\s*(.+)$/;
-const C4_LABELED_BIDI_SYNC_RE = /^<-(.+)->\s*(.+)$/;
-const C4_LABELED_BIDI_ASYNC_RE = /^<~(.+)~>\s*(.+)$/;
+/**
+ * Labeled arrow relationships: -label->, ~label~>, <-label->, <~label~>.
+ * Label captured lazily so a line splits at the FIRST arrow — matches every
+ * other chart parser (which use lazy `.+?`); greedy `.+` split at the last.
+ */
+const C4_LABELED_SYNC_RE = /^-(.+?)->\s*(.+)$/;
+const C4_LABELED_ASYNC_RE = /^~(.+?)~>\s*(.+)$/;
+const C4_LABELED_BIDI_SYNC_RE = /^<-(.+?)->\s*(.+)$/;
+const C4_LABELED_BIDI_ASYNC_RE = /^<~(.+?)~>\s*(.+)$/;
 
 /** Matches section headers: `containers`, `components`, `deployment` (bare keyword) */
 const SECTION_HEADER_RE = /^(containers|components|deployment)\s*$/i;

package/src/c4/renderer.ts

@@ -9,6 +9,7 @@ import type { PaletteColors } from '../palettes';
 import { contrastText, mix, shapeFill } from '../palettes/color-utils';
 import { renderInlineText } from '../utils/inline-markdown';
 import { preprocessDescriptionLine } from '../utils/description-helpers';
+import { measureText, wrapTextToWidth } from '../utils/text-measure';
 import type { ParsedC4 } from './types';
 import type { C4LayoutResult, C4LayoutEdge } from './layout';
 import { parseC4 } from './parser';
@@ -35,7 +36,6 @@ const TYPE_FONT_SIZE = 10;
 const NAME_FONT_SIZE = 14;
 const DESC_FONT_SIZE = 11;
 const DESC_LINE_HEIGHT = 16;
-const DESC_CHAR_WIDTH = 6.5;
 const EDGE_LABEL_FONT_SIZE = 11;
 const TECH_FONT_SIZE = 10;
 const EDGE_STROKE_WIDTH = 1.5;
@@ -47,7 +47,6 @@ const TYPE_LABEL_HEIGHT = 18;
 const DIVIDER_GAP = 6;
 const NAME_HEIGHT = 20;
 const META_FONT_SIZE = 11;
-const META_CHAR_WIDTH = 6.5;
 const META_LINE_HEIGHT = 16;
 const BOUNDARY_LABEL_FONT_SIZE = 12;
 const BOUNDARY_STROKE_WIDTH = 1.5;
@@ -111,28 +110,6 @@ function nodeStroke(
   return typeColor(type, palette, nodeColor);
 }
 
-// ============================================================
-// Text wrapping helper
-// ============================================================
-
-function wrapText(text: string, maxWidth: number, charWidth: number): string[] {
-  const words = text.split(/\s+/);
-  const lines: string[] = [];
-  let current = '';
-
-  for (const word of words) {
-    const test = current ? `${current} ${word}` : word;
-    if (test.length * charWidth > maxWidth && current) {
-      lines.push(current);
-      current = word;
-    } else {
-      current = test;
-    }
-  }
-  if (current) lines.push(current);
-  return lines;
-}
-
 // ============================================================
 // Edge path generator
 // ============================================================
@@ -394,8 +371,11 @@ export function renderC4Context(
       const techText = edge.technology ? `[${edge.technology}]` : '';
 
       // Background rect
-      const textLen = Math.max(labelText.length, techText.length);
-      const bgW = textLen * 7 + 12;
+      const textW = Math.max(
+        measureText(labelText, EDGE_LABEL_FONT_SIZE),
+        measureText(techText, TECH_FONT_SIZE)
+      );
+      const bgW = textW + 12;
       const bgH = (labelText ? 16 : 0) + (techText ? 14 : 0) + 4;
 
       edgeG
@@ -522,8 +502,7 @@ export function renderC4Context(
     // Name (bold) — above divider
     if (node.type === 'person') {
       // Person icon to the left of name
-      const nameCharWidth = NAME_FONT_SIZE * 0.6;
-      const textWidth = node.name.length * nameCharWidth;
+      const textWidth = measureText(node.name, NAME_FONT_SIZE);
       const gap = 6;
       const totalWidth = PERSON_ICON_W + gap + textWidth;
       const iconCx = -totalWidth / 2 + PERSON_ICON_W / 2;
@@ -577,7 +556,11 @@ export function renderC4Context(
     // Description (wrapping, inline markdown) — must contrast against fill
     if (node.description) {
       const contentWidth = w - CARD_H_PAD * 2;
-      const lines = wrapText(node.description, contentWidth, DESC_CHAR_WIDTH);
+      const lines = wrapTextToWidth(
+        node.description,
+        DESC_FONT_SIZE,
+        contentWidth
+      );
       for (const line of lines) {
         const textEl = nodeG
           .append('text')
@@ -840,8 +823,11 @@ function renderEdges(
     if (edge.label || edge.technology) {
       const labelText = edge.label ?? '';
       const techText = edge.technology ? `[${edge.technology}]` : '';
-      const textLen = Math.max(labelText.length, techText.length);
-      const bgW = textLen * 7 + 12;
+      const textW = Math.max(
+        measureText(labelText, EDGE_LABEL_FONT_SIZE),
+        measureText(techText, TECH_FONT_SIZE)
+      );
+      const bgW = textW + 12;
       const bgH = (labelText ? 16 : 0) + (techText ? 14 : 0) + 4;
 
       pendingLabels.push({
@@ -1508,12 +1494,12 @@ export function renderC4Containers(
   if (layout.boundary) {
     const b = layout.boundary;
     const labelText = `${b.label} \u2014 ${b.typeLabel}`;
-    const w = labelText.length * 7 + 12;
+    const w = measureText(labelText, BOUNDARY_LABEL_FONT_SIZE) + 12;
     const h = BOUNDARY_LABEL_FONT_SIZE + 4;
     boundaryLabelObstacles.push({ x: b.x + 12, y: b.y + 16 - h + 4, w, h });
   }
   for (const gb of layout.groupBoundaries) {
-    const w = gb.label.length * 7 + 12;
+    const w = measureText(gb.label, BOUNDARY_LABEL_FONT_SIZE) + 12;
     const h = BOUNDARY_LABEL_FONT_SIZE + 4;
     boundaryLabelObstacles.push({ x: gb.x + 10, y: gb.y + 14 - h + 4, w, h });
   }
@@ -1621,8 +1607,7 @@ export function renderC4Containers(
 
     // Name (bold)
     if (node.type === 'person') {
-      const nameCharWidth = NAME_FONT_SIZE * 0.6;
-      const textWidth = node.name.length * nameCharWidth;
+      const textWidth = measureText(node.name, NAME_FONT_SIZE);
       const gap = 6;
       const totalWidth = PERSON_ICON_W + gap + textWidth;
       const iconCx = -totalWidth / 2 + PERSON_ICON_W / 2;
@@ -1666,7 +1651,11 @@ export function renderC4Containers(
       // Description (above divider, inline markdown) — contrast against fill
       if (node.description) {
         const contentWidth = w - CARD_H_PAD * 2;
-        const lines = wrapText(node.description, contentWidth, DESC_CHAR_WIDTH);
+        const lines = wrapTextToWidth(
+          node.description,
+          DESC_FONT_SIZE,
+          contentWidth
+        );
         for (const line of lines) {
           const textEl = nodeG
             .append('text')
@@ -1702,8 +1691,10 @@ export function renderC4Containers(
 
         yPos += DIVIDER_GAP;
 
-        const maxKeyLen = Math.max(...metaEntries.map((e) => e.key.length));
-        const valueX = -w / 2 + CARD_H_PAD + (maxKeyLen + 2) * META_CHAR_WIDTH;
+        const maxKeyWidth = Math.max(
+          ...metaEntries.map((e) => measureText(`${e.key}: `, META_FONT_SIZE))
+        );
+        const valueX = -w / 2 + CARD_H_PAD + maxKeyWidth;
 
         for (const entry of metaEntries) {
           // Key — contrast against fill (textMuted is illegible on solid fills)
@@ -1750,7 +1741,11 @@ export function renderC4Containers(
       // Description (inline markdown) — contrast against fill
       if (node.description) {
         const contentWidth = w - CARD_H_PAD * 2;
-        const lines = wrapText(node.description, contentWidth, DESC_CHAR_WIDTH);
+        const lines = wrapTextToWidth(
+          node.description,
+          DESC_FONT_SIZE,
+          contentWidth
+        );
         for (const line of lines) {
           const textEl = nodeG
             .append('text')

package/src/class/layout.ts

@@ -1,4 +1,11 @@
 import dagre from '@dagrejs/dagre';
+import { measureText } from '../utils/text-measure';
+import {
+  resolveNotes,
+  buildPlacedNotes,
+  noteCanvasShift,
+  type PlacedNote,
+} from '../utils/notes';
 import type { ParsedClassDiagram, ClassNode, RelationshipType } from './types';
 
 // ============================================================
@@ -13,6 +20,16 @@ export interface ClassLayoutNode extends ClassNode {
   readonly headerHeight: number;
   readonly fieldsHeight: number;
   readonly methodsHeight: number;
+  /** A note floated beside this class (never moves the box). */
+  readonly note?: PlacedNote;
+}
+
+export interface ClassLayoutOptions {
+  /**
+   * 1-based source line numbers of notes the user has collapsed. A
+   * collapsed note renders as a corner badge and reserves no space.
+   */
+  collapsedNotes?: ReadonlySet<number>;
 }
 
 export interface ClassLayoutEdge {
@@ -36,9 +53,12 @@ export interface ClassLayoutResult {
 // ============================================================
 
 const MIN_WIDTH = 140;
-const CHAR_WIDTH = 7.5;
 const PADDING_X = 24;
 const HEADER_BASE = 36;
+// Font sizes mirror the renderer: class name at CLASS_FONT_SIZE, members and
+// the modifier badge at MEMBER_FONT_SIZE. Keep these in sync with renderer.ts.
+const CLASS_FONT_SIZE = 13;
+const MEMBER_FONT_SIZE = 11;
 const MODIFIER_BADGE = 16; // extra height for <<interface>> etc.
 const MEMBER_LINE_HEIGHT = 18;
 const COMPARTMENT_PADDING_Y = 8;
@@ -59,10 +79,15 @@ function computeNodeDimensions(node: ClassNode): {
   const methods = node.members.filter((m) => m.isMethod);
   const isEnum = node.modifier === 'enum';
 
-  // Width: max of class name, member text lengths
-  let maxTextLen = node.name.length;
+  // Width: max rendered pixel width of class name, modifier badge, and members.
+  // Measure each at the font size the renderer draws it with.
+  let maxTextWidth = measureText(node.name, CLASS_FONT_SIZE);
   if (node.modifier) {
-    maxTextLen = Math.max(maxTextLen, `<<${node.modifier}>>`.length);
+    // Renderer draws the badge as «modifier» at MEMBER_FONT_SIZE.
+    maxTextWidth = Math.max(
+      maxTextWidth,
+      measureText(`«${node.modifier}»`, MEMBER_FONT_SIZE)
+    );
   }
   for (const m of node.members) {
     let memberText = m.name;
@@ -74,9 +99,12 @@ function computeNodeDimensions(node: ClassNode): {
     }
     // Add visibility prefix width
     memberText = `+ ${memberText}`;
-    maxTextLen = Math.max(maxTextLen, memberText.length);
+    maxTextWidth = Math.max(
+      maxTextWidth,
+      measureText(memberText, MEMBER_FONT_SIZE)
+    );
   }
-  const width = Math.max(MIN_WIDTH, maxTextLen * CHAR_WIDTH + PADDING_X);
+  const width = Math.max(MIN_WIDTH, maxTextWidth + PADDING_X);
 
   // Header height
   const headerHeight = HEADER_BASE + (node.modifier ? MODIFIER_BADGE : 0);
@@ -130,7 +158,8 @@ function computeNodeDimensions(node: ClassNode): {
 // ============================================================
 
 export function layoutClassDiagram(
-  parsed: ParsedClassDiagram
+  parsed: ParsedClassDiagram,
+  options?: ClassLayoutOptions
 ): ClassLayoutResult {
   if (parsed.classes.length === 0) {
     return { nodes: [], edges: [], width: 0, height: 0 };
@@ -175,10 +204,40 @@ export function layoutClassDiagram(
   // Run layout
   dagre.layout(g);
 
+  // ── Notes ──────────────────────────────────────────────────
+  // Resolve note anchors (no diagnostics here — the parser already emitted
+  // them). `no-notes` drops the reserved footprint so layout matches an
+  // un-annotated diagram. The note floats beside its class WITHOUT moving
+  // it (class TB layout → default side right).
+  const notesSuppressed = parsed.options?.['no-notes'] === 'on';
+  const noteByNode =
+    notesSuppressed || !parsed.notes
+      ? new Map()
+      : resolveNotes(
+          parsed.notes,
+          parsed.classes.map((c) => ({ id: c.id, label: c.name }))
+        );
+  const placedNotes = buildPlacedNotes(
+    parsed.classes.map((node) => {
+      const pos = g.node(node.id);
+      return {
+        id: node.id,
+        x: pos.x,
+        y: pos.y,
+        width: pos.width,
+        height: pos.height,
+      };
+    }),
+    noteByNode,
+    'TB',
+    options?.collapsedNotes
+  );
+
   // Extract positioned nodes
   const layoutNodes: ClassLayoutNode[] = parsed.classes.map((node) => {
     const pos = g.node(node.id);
     const dims = dimMap.get(node.id)!;
+    const note = placedNotes.get(node.id);
     return {
       ...node,
       x: pos.x,
@@ -188,6 +247,7 @@ export function layoutClassDiagram(
       headerHeight: dims.headerHeight,
       fieldsHeight: dims.fieldsHeight,
       methodsHeight: dims.methodsHeight,
+      ...(note && { note }),
     };
   });
 
@@ -205,21 +265,61 @@ export function layoutClassDiagram(
     return layoutEdge;
   });
 
-  // Compute total dimensions
-  let totalWidth = 0;
-  let totalHeight = 0;
+  // Content bbox over nodes and their (floated) notes. A note placed
+  // above/left can land at negative coords; when it does, shift everything
+  // so nothing clips. Un-annotated diagrams keep min ≥ 0 → no shift.
+  let bbMinX = Infinity;
+  let bbMinY = Infinity;
+  let bbMaxX = -Infinity;
+  let bbMaxY = -Infinity;
+  const extend = (l: number, t: number, r: number, b: number): void => {
+    if (l < bbMinX) bbMinX = l;
+    if (t < bbMinY) bbMinY = t;
+    if (r > bbMaxX) bbMaxX = r;
+    if (b > bbMaxY) bbMaxY = b;
+  };
   for (const node of layoutNodes) {
-    const right = node.x + node.width / 2;
-    const bottom = node.y + node.height / 2;
-    if (right > totalWidth) totalWidth = right;
-    if (bottom > totalHeight) totalHeight = bottom;
+    extend(
+      node.x - node.width / 2,
+      node.y - node.height / 2,
+      node.x + node.width / 2,
+      node.y + node.height / 2
+    );
+    if (node.note && !node.note.collapsed) {
+      extend(
+        node.x + node.note.x,
+        node.y + node.note.y,
+        node.x + node.note.x + node.note.width,
+        node.y + node.note.y + node.note.height
+      );
+    }
+  }
+  if (!Number.isFinite(bbMinX)) {
+    bbMinX = 0;
+    bbMinY = 0;
+    bbMaxX = 0;
+    bbMaxY = 0;
   }
-  totalWidth += 40;
-  totalHeight += 40;
+
+  const { shiftX, shiftY } = noteCanvasShift(bbMinX, bbMinY);
+  const shifted = shiftX !== 0 || shiftY !== 0;
+  const finalNodes = shifted
+    ? layoutNodes.map((n) => ({ ...n, x: n.x + shiftX, y: n.y + shiftY }))
+    : layoutNodes;
+  const finalEdges = shifted
+    ? layoutEdges.map((e) => ({
+        ...e,
+        points: e.points.map((pt) => ({ x: pt.x + shiftX, y: pt.y + shiftY })),
+      }))
+    : layoutEdges;
+
+  // Totals: max extent (incl. notes) + the prior 40 px margin.
+  const totalWidth = bbMaxX + shiftX + 40;
+  const totalHeight = bbMaxY + shiftY + 40;
 
   return {
-    nodes: layoutNodes,
-    edges: layoutEdges,
+    nodes: finalNodes,
+    edges: finalEdges,
     width: totalWidth,
     height: totalHeight,
   };

package/src/class/parser.ts

@@ -14,6 +14,7 @@ import {
   tryParseSharedOption,
 } from '../utils/parsing';
 import { normalizeName, displayName } from '../utils/name-normalize';
+import { tryCollectNote, resolveNotes, type DiagramNote } from '../utils/notes';
 import type { Writable } from '../utils/brand';
 import type {
   ParsedClassDiagram,
@@ -192,6 +193,7 @@ export function parseClassDiagram(
   };
 
   const classMap = new Map<string, Writable<ClassNode>>();
+  const notes: DiagramNote[] = [];
 
   // Per-parse alias literal → canonical class id (TD-18). Per C8.
   const nameAliasMap = new Map<string, string>();
@@ -266,6 +268,27 @@ export function parseClassDiagram(
     // Skip comments
     if (trimmed.startsWith('//')) continue;
 
+    // Note annotation (top-level): `note <ClassName> [inline body]` + an
+    // optional indented body. Checked before options so a note is never
+    // swallowed as an option; gated to indent 0 so an indented member
+    // starting with "note" stays a member. `note -> X` is excluded.
+    if (indent === 0) {
+      const noteResult = tryCollectNote(
+        lines,
+        i,
+        indent,
+        palette,
+        result.diagnostics
+      );
+      if (noteResult) {
+        currentClass = null;
+        contentStarted = true;
+        if (noteResult.note) notes.push(noteResult.note);
+        i = noteResult.lastIndex;
+        continue;
+      }
+    }
+
     // First line: bare chart type + optional title (new syntax)
     if (!contentStarted && indent === 0 && i === 0) {
       const firstLine = parseFirstLine(trimmed);
@@ -439,6 +462,18 @@ export function parseClassDiagram(
     );
   }
 
+  // Resolve note refs against class names (forward refs OK — runs after all
+  // classes parsed). The id→note binding is recomputed in layout; this pass
+  // only surfaces unknown/ambiguous/duplicate diagnostics.
+  if (notes.length > 0) {
+    result.notes = notes;
+    resolveNotes(
+      notes,
+      result.classes.map((c) => ({ id: c.id, label: c.name })),
+      result.diagnostics
+    );
+  }
+
   // Validation
   if (result.classes.length === 0 && !result.error) {
     const diag = makeDgmoError(

package/src/class/renderer.ts

@@ -28,6 +28,16 @@ import type { ClassLayoutResult } from './layout';
 import { parseClassDiagram } from './parser';
 import { layoutClassDiagram } from './layout';
 import { ScaleContext } from '../utils/scaling';
+import { measureText } from '../utils/text-measure';
+import {
+  renderNoteBox,
+  renderNoteConnector,
+  renderNoteBadge,
+  noteConnectorPoints,
+  NOTE_BADGE_RADIUS,
+} from '../utils/note-box';
+
+type GSelection = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
 
 // ============================================================
 // Constants
@@ -468,8 +478,7 @@ export function renderClassDiagram(
       const midIdx = Math.floor(edge.points.length / 2);
       // Edges are always non-empty (drawn from a valid graph layout).
       const midPt = edge.points[midIdx]!;
-      const labelLen = edge.label.length;
-      const bgW = labelLen * 7 + 8;
+      const bgW = measureText(edge.label, sEdgeLabelFontSize) + 8;
       const bgH = 16;
 
       edgeG
@@ -693,6 +702,53 @@ export function renderClassDiagram(
         }
       }
     }
+
+    // ── Note (floated beside the class, or a collapsed corner badge) ──
+    // The class keeps its layout position; the note floats in adjacent
+    // space chosen by the collision-aware placer. Coords are node-center
+    // -local (the node `<g>` is translated to the center).
+    if (node.note) {
+      if (node.note.collapsed) {
+        renderNoteBadge(
+          nodeG as GSelection,
+          {
+            x: w / 2 - NOTE_BADGE_RADIUS - 3,
+            y: -h / 2 + NOTE_BADGE_RADIUS + 3,
+          },
+          palette,
+          {
+            isDark,
+            ...(node.note.color && { color: node.note.color }),
+            lineNumber: node.note.lineNumber,
+            endLineNumber: node.note.endLineNumber,
+          }
+        );
+      } else {
+        const [cx1, cy1, cx2, cy2] = noteConnectorPoints(
+          { width: w, height: h },
+          node.note
+        );
+        renderNoteConnector(nodeG as GSelection, cx1, cy1, cx2, cy2, palette);
+        renderNoteBox(
+          nodeG as GSelection,
+          {
+            x: node.note.x,
+            y: node.note.y,
+            width: node.note.width,
+            height: node.note.height,
+          },
+          node.note.lines,
+          palette,
+          {
+            isDark,
+            ...(node.note.color && { color: node.note.color }),
+            lineNumber: node.note.lineNumber,
+            endLineNumber: node.note.endLineNumber,
+            interactive: true,
+          }
+        );
+      }
+    }
   }
 }
 

package/src/class/types.ts

@@ -42,6 +42,7 @@ export interface ClassRelationship {
 }
 
 import type { DgmoError } from '../diagnostics';
+import type { DiagramNote } from '../utils/notes';
 
 export interface ParsedClassDiagram {
   readonly type: 'class';
@@ -50,6 +51,8 @@ export interface ParsedClassDiagram {
   readonly classes: readonly ClassNode[];
   readonly relationships: readonly ClassRelationship[];
   readonly options: Readonly<Record<string, string>>;
+  /** Generic node notes (`note <ClassName> …`); resolved in layout. */
+  readonly notes?: readonly DiagramNote[];
   readonly diagnostics: readonly DgmoError[];
   readonly error: string | null;
 }