@diagrammo/dgmo 0.26.0 → 0.27.0

package/src/er/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 { ParsedERDiagram, ERTable, ERRelationship } from './types';
 
 // ============================================================
@@ -12,6 +19,13 @@ export interface ERLayoutNode extends ERTable {
   readonly height: number;
   readonly headerHeight: number;
   readonly columnsHeight: number;
+  /** A note floated beside this table (never moves the box). */
+  readonly note?: PlacedNote;
+}
+
+export interface ERLayoutOptions {
+  /** 1-based source lines of notes the user collapsed (corner badge). */
+  collapsedNotes?: ReadonlySet<number>;
 }
 
 export interface ERLayoutEdge {
@@ -35,9 +49,15 @@ export interface ERLayoutResult {
 // ============================================================
 
 const MIN_WIDTH = 140;
-const CHAR_WIDTH = 7.5;
 const PADDING_X = 24;
 const HEADER_BASE = 36;
+// Font sizes mirror the renderer: table name at TABLE_FONT_SIZE, columns at
+// COLUMN_FONT_SIZE. Keep these in sync with renderer.ts.
+const TABLE_FONT_SIZE = 13;
+const COLUMN_FONT_SIZE = 11;
+const EDGE_LABEL_FONT_SIZE = 11;
+// Renderer offsets column text by 16px when a constraint icon is present.
+const CONSTRAINT_ICON_WIDTH = 16;
 const MEMBER_LINE_HEIGHT = 18;
 const COMPARTMENT_PADDING_Y = 8;
 const SEPARATOR_HEIGHT = 1;
@@ -55,14 +75,18 @@ function computeNodeDimensions(table: ERTable): {
   headerHeight: number;
   columnsHeight: number;
 } {
-  let maxTextLen = table.name.length;
+  // Width: max rendered pixel width of table name and column rows. Measure
+  // each at the font size the renderer draws it with; reserve the constraint
+  // icon's horizontal offset when a column carries one.
+  let maxTextWidth = measureText(table.name, TABLE_FONT_SIZE);
   for (const col of table.columns) {
     let colText = col.name;
-    if (col.type) colText += `  ${col.type}`;
-    if (col.constraints.length > 0) colText += `  XX`; // icon space
-    maxTextLen = Math.max(maxTextLen, colText.length);
+    if (col.type) colText += `: ${col.type}`;
+    let colWidth = measureText(colText, COLUMN_FONT_SIZE);
+    if (col.constraints.length > 0) colWidth += CONSTRAINT_ICON_WIDTH;
+    maxTextWidth = Math.max(maxTextWidth, colWidth);
   }
-  const width = Math.max(MIN_WIDTH, maxTextLen * CHAR_WIDTH + PADDING_X);
+  const width = Math.max(MIN_WIDTH, maxTextWidth + PADDING_X);
   const headerHeight = HEADER_BASE;
 
   let columnsHeight = 0;
@@ -227,7 +251,7 @@ function layoutComponent(
     if (rel.label && (ed?.points ?? []).length > 0) {
       const pts = ed!.points;
       const mid = pts[Math.floor(pts.length / 2)];
-      const hw = (rel.label.length * 7 + 8) / 2;
+      const hw = (measureText(rel.label, EDGE_LABEL_FONT_SIZE) + 8) / 2;
       minX = Math.min(minX, mid.x - hw);
       maxX = Math.max(maxX, mid.x + hw);
     }
@@ -333,7 +357,10 @@ function packComponents(
 // Layout engine
 // ============================================================
 
-export function layoutERDiagram(parsed: ParsedERDiagram): ERLayoutResult {
+export function layoutERDiagram(
+  parsed: ParsedERDiagram,
+  options?: ERLayoutOptions
+): ERLayoutResult {
   if (parsed.tables.length === 0) {
     return { nodes: [], edges: [], width: 0, height: 0 };
   }
@@ -415,24 +442,89 @@ export function layoutERDiagram(parsed: ParsedERDiagram): ERLayoutResult {
     };
   });
 
-  // ── 6. Total canvas dimensions ───────────────────────────────────────────────
-  let maxX = 0;
-  let maxY = 0;
-  for (const node of layoutNodes) {
-    maxX = Math.max(maxX, node.x + node.width / 2);
-    maxY = Math.max(maxY, node.y + node.height / 2);
+  // ── 6. Notes ─────────────────────────────────────────────────────────────────
+  // Resolve note anchors (no diagnostics — the parser already emitted them).
+  // `no-notes` drops the footprint so layout matches an un-annotated diagram.
+  // The note floats beside its table WITHOUT moving it (ER nodes are center
+  // -positioned → default side right).
+  const notesSuppressed = parsed.options?.['no-notes'] === 'on';
+  const noteByNode =
+    notesSuppressed || !parsed.notes
+      ? new Map()
+      : resolveNotes(
+          parsed.notes,
+          parsed.tables.map((t) => ({ id: t.id, label: t.name }))
+        );
+  const placedNotes = buildPlacedNotes(
+    layoutNodes.map((n) => ({
+      id: n.id,
+      x: n.x,
+      y: n.y,
+      width: n.width,
+      height: n.height,
+    })),
+    noteByNode,
+    'TB',
+    options?.collapsedNotes
+  );
+  const notedNodes: ERLayoutNode[] = layoutNodes.map((n) => {
+    const note = placedNotes.get(n.id);
+    return note ? { ...n, note } : n;
+  });
+
+  // ── 7. Content bbox (incl. floated notes) + off-canvas 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 notedNodes) {
+    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
+      );
+    }
   }
   for (const edge of layoutEdges) {
-    for (const pt of edge.points) {
-      maxX = Math.max(maxX, pt.x);
-      maxY = Math.max(maxY, pt.y);
-    }
+    for (const pt of edge.points) extend(pt.x, pt.y, pt.x, pt.y);
   }
+  if (!Number.isFinite(bbMinX)) {
+    bbMinX = 0;
+    bbMinY = 0;
+    bbMaxX = 0;
+    bbMaxY = 0;
+  }
+
+  const { shiftX, shiftY } = noteCanvasShift(bbMinX, bbMinY);
+  const shifted = shiftX !== 0 || shiftY !== 0;
+  const finalNodes = shifted
+    ? notedNodes.map((n) => ({ ...n, x: n.x + shiftX, y: n.y + shiftY }))
+    : notedNodes;
+  const finalEdges = shifted
+    ? layoutEdges.map((e) => ({
+        ...e,
+        points: e.points.map((pt) => ({ x: pt.x + shiftX, y: pt.y + shiftY })),
+      }))
+    : layoutEdges;
 
   return {
-    nodes: layoutNodes,
-    edges: layoutEdges,
-    width: maxX + HALF_MARGIN,
-    height: maxY + HALF_MARGIN,
+    nodes: finalNodes,
+    edges: finalEdges,
+    width: bbMaxX + shiftX + HALF_MARGIN,
+    height: bbMaxY + shiftY + HALF_MARGIN,
   };
 }

package/src/er/parser.ts

@@ -31,6 +31,7 @@ import {
   stripDefaultModifier,
 } from '../utils/tag-groups';
 import type { TagGroup } from '../utils/tag-groups';
+import { tryCollectNote, resolveNotes, type DiagramNote } from '../utils/notes';
 import type { Writable } from '../utils/brand';
 import type {
   ParsedERDiagram,
@@ -252,6 +253,7 @@ export function parseERDiagram(
   // assign into it (table.metadata is `Readonly<Record<...>>` per the spec).
   const tableMetadataMap = new Map<string, Record<string, string>>();
   let currentTable: Writable<ERTable> | null = null;
+  const notes: DiagramNote[] = [];
   let contentStarted = false;
   let currentTagGroup: Writable<TagGroup> | null = null;
   // metaAliasMap: tag-group metadata-key aliases (per A1 convention).
@@ -466,6 +468,21 @@ export function parseERDiagram(
     currentTable = null;
     contentStarted = true;
 
+    // Note annotation (top-level): `note <Table> [inline body]` + an optional
+    // indented body. `note -> X` is excluded so it can still parse as content.
+    const noteResult = tryCollectNote(
+      lines,
+      i,
+      indent,
+      palette,
+      result.diagnostics
+    );
+    if (noteResult) {
+      if (noteResult.note) notes.push(noteResult.note);
+      i = noteResult.lastIndex;
+      continue;
+    }
+
     // Reject top-level relationships — must be indented under source table
     const rel = parseRelationship(trimmed, lineNumber, pushError);
     if (rel) {
@@ -596,6 +613,17 @@ export function parseERDiagram(
     }
   }
 
+  // Resolve note refs against table names (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.tables.map((t) => ({ id: t.id, label: t.name })),
+      result.diagnostics
+    );
+  }
+
   // Warn about isolated tables (not in any relationship)
   if (
     result.tables.length >= 2 &&

package/src/er/renderer.ts

@@ -18,6 +18,14 @@ import {
   TITLE_Y,
 } from '../utils/title-constants';
 import { ScaleContext } from '../utils/scaling';
+import { measureText } from '../utils/text-measure';
+import {
+  renderNoteBox,
+  renderNoteConnector,
+  renderNoteBadge,
+  noteConnectorPoints,
+  NOTE_BADGE_RADIUS,
+} from '../utils/note-box';
 import type { ParsedERDiagram, ERConstraint } from './types';
 import type { ERLayoutResult } from './layout';
 import { parseERDiagram } from './parser';
@@ -388,8 +396,7 @@ export function renderERDiagram(
       const midIdx = Math.floor(pts.length / 2);
       // In-bounds: midIdx is in [0, pts.length-1] since pts.length >= 2.
       const midPt = pts[midIdx]!;
-      const labelLen = edge.label.length;
-      const bgW = labelLen * 7 + 8;
+      const bgW = measureText(edge.label, sEdgeLabelFontSize) + 8;
       const bgH = 16;
 
       edgeG
@@ -549,6 +556,52 @@ export function renderERDiagram(
         memberY += sMemberLineHeight;
       }
     }
+
+    // ── Note (floated beside the table, or a collapsed corner badge) ──
+    // The table keeps its layout position; the note floats in adjacent
+    // space. Coords are node-center-local (the node `<g>` is at the center).
+    if (node.note) {
+      if (node.note.collapsed) {
+        renderNoteBadge(
+          nodeG,
+          {
+            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, cx1, cy1, cx2, cy2, palette);
+        renderNoteBox(
+          nodeG,
+          {
+            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,
+          }
+        );
+      }
+    }
   }
 
   // ── Tag Legend ──

package/src/er/types.ts

@@ -35,6 +35,7 @@ export interface ERRelationship {
 
 import type { DgmoError } from '../diagnostics';
 import type { TagGroup } from '../utils/tag-groups';
+import type { DiagramNote } from '../utils/notes';
 
 export interface ParsedERDiagram {
   readonly type: 'er';
@@ -44,6 +45,8 @@ export interface ParsedERDiagram {
   readonly tables: readonly ERTable[];
   readonly relationships: readonly ERRelationship[];
   readonly tagGroups: readonly TagGroup[];
+  /** Generic node notes (`note <Table> …`); resolved in layout. */
+  readonly notes?: readonly DiagramNote[];
   readonly diagnostics: readonly DgmoError[];
   readonly error: string | null;
 }

package/src/gantt/renderer.ts

@@ -10,7 +10,12 @@ import { contrastText, mix, shapeFill } from '../palettes/color-utils';
 import { normalizeName } from '../utils/name-normalize';
 import { resolveTagColor, resolveActiveTagGroup } from '../utils/tag-groups';
 import { ScaleContext } from '../utils/scaling';
-import { computeTimeTicks } from '../utils/time-ticks';
+import { computeTimeTicks, MONTH_ABBR } from '../utils/time-ticks';
+import {
+  measureText,
+  truncateText,
+  CHAR_WIDTH_RATIO,
+} from '../utils/text-measure';
 import {
   LEGEND_HEIGHT,
   LEGEND_PILL_PAD,
@@ -60,7 +65,6 @@ const MILESTONE_SIZE = 10;
 const MIN_LEFT_MARGIN = 120;
 const BOTTOM_MARGIN = 40;
 const RIGHT_MARGIN = 20;
-const CHAR_W = 6.5; // estimated px per character for bar labels
 const LABEL_PAD = 8; // inner padding to decide if label fits inside bar
 const LABEL_GAP = 5; // gap between bar edge and external label
 
@@ -80,11 +84,11 @@ function computeBarLabel(
   innerWidth: number,
   textColor: string,
   onFillColor?: string,
-  charW = CHAR_W,
+  fontSize = 10,
   labelPad = LABEL_PAD,
   labelGap = LABEL_GAP
 ): BarLabelPlacement | null {
-  const textWidth = label.length * charW;
+  const textWidth = measureText(label, fontSize);
   const x2 = x1 + barWidth;
 
   if (textWidth < barWidth - labelPad) {
@@ -105,13 +109,15 @@ function computeBarLabel(
   }
 
   const availWidth = x1 - labelGap;
-  if (availWidth > charW * 3) {
-    const maxChars = Math.floor(availWidth / charW) - 1;
+  // Roughly three average glyphs' worth of room before truncation is worthwhile.
+  if (availWidth > fontSize * CHAR_WIDTH_RATIO * 3) {
+    const truncated = truncateText(label, fontSize, availWidth);
+    if (!truncated) return null;
     return {
       x: x1 - labelGap,
       anchor: 'end',
       fill: textColor,
-      text: label.slice(0, maxChars) + '\u2026',
+      text: truncated,
     };
   }
 
@@ -270,25 +276,34 @@ export function renderGantt(
   const rows = tagRows ?? buildRowList(resolved, collapsedGroups);
   const isTagMode = tagRows !== null;
 
-  // Compute left margin based on longest visible label (include ● /◆  prefix for tasks)
-  const allLabels = isTagMode
+  // Compute left margin based on longest visible label (include ● /◆  prefix
+  // for tasks). Labels render at font 11; group labels carry a pixel indent.
+  const LABEL_FONT = 11;
+  const labelWidths = isTagMode
     ? [
         ...rows
           .filter((r): r is LaneHeaderRow => r.type === 'lane-header')
-          .map((r) => r.laneName),
+          .map((r) => measureText(r.laneName, LABEL_FONT)),
         ...rows
           .filter((r): r is TaskRow => r.type === 'task')
-          .map((r) => '● ' + r.task.task.label),
+          .map((r) => measureText('● ' + r.task.task.label, LABEL_FONT)),
       ]
     : [
-        ...resolved.tasks.map((t) => '● ' + t.task.label),
+        ...resolved.tasks.map((t) =>
+          measureText('● ' + t.task.label, LABEL_FONT)
+        ),
         ...resolved.groups.map((g) => {
-          const px = g.depth <= 2 ? g.depth * 14 : 2 * 14 + (g.depth - 2) * 8;
-          return ' '.repeat(Math.ceil(px / 7)) + g.name;
+          const indentPx =
+            g.depth <= 2 ? g.depth * 14 : 2 * 14 + (g.depth - 2) * 8;
+          return indentPx + measureText(g.name, LABEL_FONT);
         }),
       ];
-  const maxLabelLen = Math.max(...allLabels.map((l) => l.length), 10);
-  const leftMargin = Math.max(MIN_LEFT_MARGIN, maxLabelLen * 7 + 30);
+  // Floor on a 10-char label so very short schedules still get a usable gutter.
+  const maxLabelWidth = Math.max(
+    ...labelWidths,
+    measureText('0000000000', LABEL_FONT)
+  );
+  const leftMargin = Math.max(MIN_LEFT_MARGIN, maxLabelWidth + 30);
 
   const totalRows = rows.length;
 
@@ -356,7 +371,6 @@ export function renderGantt(
   const sMilestoneSize = ctx.structural(MILESTONE_SIZE);
   const sBottomMargin = ctx.aesthetic(BOTTOM_MARGIN);
   const sRightMargin = ctx.aesthetic(RIGHT_MARGIN);
-  const sCharW = ctx.text(CHAR_W, 4);
   const sLabelPad = ctx.structural(LABEL_PAD);
   const sLabelGap = ctx.structural(LABEL_GAP);
   const sBandAccentW = ctx.structural(BAND_ACCENT_W);
@@ -923,7 +937,7 @@ export function renderGantt(
               palette.textOnFillLight,
               palette.textOnFillDark
             ),
-            sCharW,
+            sFont10,
             sLabelPad,
             sLabelGap
           );
@@ -1007,7 +1021,7 @@ export function renderGantt(
               palette.textOnFillLight,
               palette.textOnFillDark
             ),
-            sCharW,
+            sFont10,
             sLabelPad,
             sLabelGap
           );
@@ -1311,7 +1325,7 @@ export function renderGantt(
             palette.textOnFillLight,
             palette.textOnFillDark
           ),
-          sCharW,
+          sFont10,
           sLabelPad,
           sLabelGap
         );
@@ -1625,7 +1639,7 @@ function drawHolidayBand(
   // Hover label in SVG-space (date header row) — hidden by default
   // Background rect to mask date labels underneath
   const labelX = chartLeftMargin + x1 + bandW / 2;
-  const textLen = label.length * 6 + 8;
+  const textLen = measureText(label, 10) + 8;
   const labelBg = svg
     .append('rect')
     .attr('class', 'gantt-holiday-hover-bg')
@@ -1957,6 +1971,15 @@ function drawSwimlaneIcon(
     .attr('class', 'gantt-swimlane-icon')
     .attr('transform', `translate(${x}, ${y})`);
 
+  // Transparent hit area so the whole icon (not just the 2px bars) is clickable
+  iconG
+    .append('rect')
+    .attr('x', -5)
+    .attr('y', -5)
+    .attr('width', 22)
+    .attr('height', 18)
+    .attr('fill', 'transparent');
+
   const color = isActive ? palette.primary : palette.textMuted;
   const opacity = isActive ? 1 : 0.35;
   const barWidths = [8, 12, 6];
@@ -2342,7 +2365,7 @@ function renderTagLegend(
 
 // ── Era & Marker Rendering ──────────────────────────────────
 
-const ERA_COLORS = ['#5e81ac', '#a3be8c', '#ebcb8b', '#d08770', '#b48ead'];
+const ERA_COLORS = ['#3b6ea5', '#5b9357', '#c9a227', '#cc7a33', '#7d5ba6'];
 
 function renderErasAndMarkers(
   g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
@@ -2467,7 +2490,7 @@ function renderErasAndMarkers(
   for (let i = 0; i < resolved.markers.length; i++) {
     const marker = resolved.markers[i];
     if (!marker) continue; // In-bounds by loop guard; appeases TS.
-    const color = marker.color || palette.accent || '#d08770';
+    const color = marker.color || palette.accent || '#3a9188';
     // In-bounds: markerXs.length === resolved.markers.length.
     const mx = markerXs[i]!;
     const markerDate = parseDateStringToDate(marker.date);
@@ -3499,21 +3522,6 @@ function diamondPoints(cx: number, cy: number, size: number): string {
 
 // ── Hover Date Indicators ───────────────────────────────────
 
-const MONTH_ABBR = [
-  'Jan',
-  'Feb',
-  'Mar',
-  'Apr',
-  'May',
-  'Jun',
-  'Jul',
-  'Aug',
-  'Sep',
-  'Oct',
-  'Nov',
-  'Dec',
-];
-
 function formatGanttDate(d: Date): string {
   const base = `${MONTH_ABBR[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`;
   if (d.getHours() === 0 && d.getMinutes() === 0) return base;

package/src/gantt/resolver.ts

@@ -55,6 +55,13 @@ export function collectTasks(nodes: readonly GanttNode[]): GanttTask[] {
 /** Strip bracket syntax: `[Backend].API Design` → `Backend.API Design` */
 const BRACKET_GROUP_RE = /^\[(.+?)\]\.(.+)$/;
 
+/** Disambiguation message when a name matches more than one task. */
+function ambiguousTaskMessage(trimmed: string, suggestions: string[]): string {
+  return `Multiple tasks match "${trimmed}". Did you mean ${suggestions
+    .map((s) => `\`${s}\``)
+    .join(' or ')}?`;
+}
+
 export function resolveTaskName(
   name: string,
   allTasks: GanttTask[]
@@ -86,7 +93,7 @@ export function resolveTaskName(
     );
     return {
       kind: 'ambiguous',
-      message: `Multiple tasks match "${trimmed}". Did you mean ${suggestions.map((s) => `\`${s}\``).join(' or ')}?`,
+      message: ambiguousTaskMessage(trimmed, suggestions),
     };
   }
 
@@ -113,7 +120,7 @@ export function resolveTaskName(
       );
       return {
         kind: 'ambiguous',
-        message: `Multiple tasks match "${trimmed}". Did you mean ${suggestions.map((s) => `\`${s}\``).join(' or ')}?`,
+        message: ambiguousTaskMessage(trimmed, suggestions),
       };
     }
 

package/src/graph/edge-spline.ts

@@ -0,0 +1,29 @@
+// ============================================================
+// Edge spline — basis curve clamped to its endpoints
+// ============================================================
+
+import * as d3Shape from 'd3-shape';
+
+const lineGenerator = d3Shape
+  .line<{ x: number; y: number }>()
+  .x((d) => d.x)
+  .y((d) => d.y)
+  .curve(d3Shape.curveBasis);
+
+/**
+ * Build a smooth edge path through dagre waypoints.
+ *
+ * `d3.curveBasis` already begins with `moveTo(P0)` and ends with
+ * `lineTo(Pn)`, so the path reaches both node borders and its final
+ * segment carries a real direction (correct `marker-end` orientation).
+ *
+ * NOTE: do NOT clamp by triplicating the endpoints — that appends
+ * zero-length trailing segments, and WebKit then computes a degenerate
+ * tangent for the arrowhead, rendering it at the wrong angle (resvg and
+ * Chromium tolerate it; WKWebView does not).
+ */
+export function edgeSplinePath(
+  points: ReadonlyArray<{ readonly x: number; readonly y: number }>
+): string | null {
+  return lineGenerator(points as { x: number; y: number }[]);
+}

package/src/graph/flowchart-parser.ts

@@ -17,7 +17,14 @@ import {
 } from '../utils/parsing';
 import { normalizeName, displayName } from '../utils/name-normalize';
 import type { Writable } from '../utils/brand';
-import type { ParsedGraph, GraphNode, GraphEdge, GraphShape } from './types';
+import type {
+  ParsedGraph,
+  GraphNode,
+  GraphEdge,
+  GraphShape,
+  GraphNote,
+} from './types';
+import { tryCollectNote, resolveNotes } from './notes';
 
 // ============================================================
 // Helpers
@@ -260,6 +267,7 @@ export function parseFlowchart(
 
   const nodeMap = new Map<string, GraphNode>();
   const indentStack: { nodeId: string; indent: number }[] = [];
+  const notes: GraphNote[] = [];
   let contentStarted = false;
   let firstLineParsed = false;
 
@@ -499,6 +507,23 @@ export function parseFlowchart(
       }
     }
 
+    // Note annotation: `note <ref> [inline body]` + optional indented
+    // body. Handled before options so `note foo bar` is never mistaken
+    // for an option. Only `note -> X` (arrow immediately after `note`) is
+    // excluded so it can edge; arrows are allowed inside a note body.
+    const noteResult = tryCollectNote(
+      lines,
+      i,
+      indent,
+      palette,
+      result.diagnostics
+    );
+    if (noteResult) {
+      if (noteResult.note) notes.push(noteResult.note);
+      i = noteResult.lastIndex;
+      continue;
+    }
+
     // Options (space-separated, before content)
     if (!contentStarted) {
       // Bare boolean: direction-lr
@@ -559,6 +584,14 @@ export function parseFlowchart(
     result.error = formatDgmoError(diag);
   }
 
+  // Resolve note refs (forward refs OK — runs after all nodes parsed).
+  // Emits diagnostics for unknown/ambiguous/duplicate refs; the resolved
+  // binding is recomputed in layout from `result.notes`.
+  if (notes.length > 0) {
+    result.notes = notes;
+    resolveNotes(notes, result.nodes, result.diagnostics);
+  }
+
   // Warn about orphaned nodes (not referenced in any edge)
   if (result.nodes.length >= 2 && result.edges.length >= 1 && !result.error) {
     const connectedIds = new Set<string>();