@diagrammo/dgmo 0.26.0 → 0.27.0

package/src/graph/flowchart-renderer.ts

@@ -3,7 +3,8 @@
 // ============================================================
 
 import * as d3Selection from 'd3-selection';
-import * as d3Shape from 'd3-shape';
+import { appendArrowheadMarkers } from '../utils/arrow-markers';
+import { fitDiagramToCanvas } from '../utils/fit-canvas';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
 import { contrastText, shapeFill } from '../palettes/color-utils';
@@ -11,12 +12,21 @@ import type { ParsedGraph, GraphShape } from './types';
 import type { LayoutResult, LayoutNode } from './layout';
 import { parseFlowchart } from './flowchart-parser';
 import { layoutGraph } from './layout';
+import { edgeSplinePath } from './edge-spline';
 import {
   TITLE_FONT_SIZE,
   TITLE_FONT_WEIGHT,
   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';
 
 // ============================================================
 // Constants
@@ -427,16 +437,6 @@ function renderNodeShape(
   }
 }
 
-// ============================================================
-// Edge path generator
-// ============================================================
-
-const lineGenerator = d3Shape
-  .line<{ x: number; y: number }>()
-  .x((d) => d.x)
-  .y((d) => d.y)
-  .curve(d3Shape.curveBasis);
-
 // ============================================================
 // Main renderer
 // ============================================================
@@ -476,28 +476,16 @@ export function renderFlowchart(
 
   const diagramW = layout.width;
   const diagramH = layout.height;
-  const scaleX = (width - sDiagramPadding * 2) / diagramW;
-
-  // Export renders a fixed canvas (e.g. 1200×800). Fitting a small graph into
-  // it and top-anchoring leaves a tall band of dead space below. In export
-  // mode, scale to width (capped by MAX_SCALE) and size the canvas to the
-  // scaled content height. The interactive preview keeps the fit-to-pane
-  // behaviour so a small graph still fills its pane.
-  let scale: number;
-  let canvasHeight: number;
-  if (exportDims) {
-    scale = Math.min(MAX_SCALE, scaleX);
-    canvasHeight = titleHeight + diagramH * scale + sDiagramPadding * 2;
-  } else {
-    const availH = height - titleHeight;
-    const scaleY = (availH - sDiagramPadding * 2) / diagramH;
-    scale = Math.min(MAX_SCALE, scaleX, scaleY);
-    canvasHeight = height;
-  }
-
-  const scaledW = diagramW * scale;
-  const offsetX = (width - scaledW) / 2;
-  const offsetY = titleHeight + sDiagramPadding;
+  const { scale, offsetX, offsetY, canvasHeight } = fitDiagramToCanvas({
+    width,
+    height,
+    diagramW,
+    diagramH,
+    padding: sDiagramPadding,
+    titleHeight,
+    maxScale: MAX_SCALE,
+    exportMode: !!exportDims,
+  });
 
   const svg = d3Selection
     .select(container)
@@ -514,35 +502,14 @@ export function renderFlowchart(
 
   const defs = svg.append('defs');
 
-  defs
-    .append('marker')
-    .attr('id', 'fc-arrow')
-    .attr('viewBox', `0 0 ${sArrowheadW} ${sArrowheadH}`)
-    .attr('refX', sArrowheadW)
-    .attr('refY', sArrowheadH / 2)
-    .attr('markerWidth', sArrowheadW)
-    .attr('markerHeight', sArrowheadH)
-    .attr('orient', 'auto')
-    .append('polygon')
-    .attr('points', `0,0 ${sArrowheadW},${sArrowheadH / 2} 0,${sArrowheadH}`)
-    .attr('fill', palette.textMuted);
-
   const edgeColors = new Set<string>();
-  for (const color of edgeColors) {
-    const id = `fc-arrow-${color.replace('#', '')}`;
-    defs
-      .append('marker')
-      .attr('id', id)
-      .attr('viewBox', `0 0 ${sArrowheadW} ${sArrowheadH}`)
-      .attr('refX', sArrowheadW)
-      .attr('refY', sArrowheadH / 2)
-      .attr('markerWidth', sArrowheadW)
-      .attr('markerHeight', sArrowheadH)
-      .attr('orient', 'auto')
-      .append('polygon')
-      .attr('points', `0,0 ${sArrowheadW},${sArrowheadH / 2} 0,${sArrowheadH}`)
-      .attr('fill', color);
-  }
+  appendArrowheadMarkers(defs, {
+    idPrefix: 'fc',
+    width: sArrowheadW,
+    height: sArrowheadH,
+    baseFill: palette.textMuted,
+    colors: edgeColors,
+  });
 
   if (showTitle) {
     const titleEl = svg
@@ -579,7 +546,6 @@ export function renderFlowchart(
     .append('g')
     .attr('transform', `translate(${offsetX}, ${offsetY}) scale(${scale})`);
 
-  const LABEL_CHAR_W = 7;
   const LABEL_PAD = 8;
   const LABEL_H = 16;
   const PERP_OFFSET = 10;
@@ -598,7 +564,7 @@ export function renderFlowchart(
     if (!edge.label || edge.points.length < 2) continue;
     const midIdx = Math.floor(edge.points.length / 2);
     const midPt = edge.points[midIdx]!;
-    const bgW = edge.label.length * LABEL_CHAR_W + LABEL_PAD;
+    const bgW = measureText(edge.label, sEdgeLabelFontSize) + LABEL_PAD;
 
     const prev = edge.points[Math.max(0, midIdx - 1)]!;
     const next = edge.points[Math.min(edge.points.length - 1, midIdx + 1)]!;
@@ -642,7 +608,7 @@ export function renderFlowchart(
     const edgeColor = palette.textMuted;
     const markerId = 'fc-arrow';
 
-    const pathD = lineGenerator(edge.points);
+    const pathD = edgeSplinePath(edge.points);
     if (pathD) {
       edgeG
         .append('path')
@@ -690,6 +656,7 @@ export function renderFlowchart(
 
   const colorOff = graph.options?.['color'] === 'off';
   const solid = graph.options?.['solid-fill'] === 'on';
+  const noNotes = graph.options?.['no-notes'] === 'on';
   for (const node of layout.nodes) {
     const nodeG = contentG
       .append('g')
@@ -704,6 +671,10 @@ export function renderFlowchart(
       });
     }
 
+    // The shape is drawn at its dagre position — a note never moves it,
+    // so its edges stay connected. The note floats beside it.
+    const hasNote = !!node.note && !noNotes;
+
     renderNodeShape(
       nodeG as GSelection,
       node,
@@ -744,6 +715,49 @@ export function renderFlowchart(
       )
       .attr('font-size', sNodeFontSize)
       .text(node.label);
+
+    if (hasNote && node.note) {
+      if (node.note.collapsed) {
+        // Collapsed → comment-bubble badge in the node's top-right corner.
+        renderNoteBadge(
+          nodeG as GSelection,
+          {
+            x: node.width / 2 - NOTE_BADGE_RADIUS - 3,
+            y: -node.height / 2 + NOTE_BADGE_RADIUS + 3,
+          },
+          palette,
+          {
+            isDark,
+            ...(node.note.color && { color: node.note.color }),
+            lineNumber: node.note.lineNumber,
+            endLineNumber: node.note.endLineNumber,
+          }
+        );
+      } else {
+        // Solid tether from the shape edge to the floated note, on whichever
+        // side the collision-aware placement chose.
+        const [cx1, cy1, cx2, cy2] = noteConnectorPoints(node, 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/graph/layout.ts

@@ -6,6 +6,33 @@ import type {
   GraphGroup,
   GraphShape,
 } from './types';
+import { resolveNotes } from './notes';
+import { noteBoxSize } from '../utils/note-box';
+import { placeNotes, noteCanvasShift } from '../utils/notes';
+import type { WrappedDescLine } from '../utils/wrapped-desc';
+
+export type NoteSide = 'above' | 'below' | 'left' | 'right';
+
+/** A note box positioned relative to its anchor node's center. */
+export interface NoteLayout {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  /** Which side of the node the box sits on (drives the connector). */
+  readonly side: NoteSide;
+  /** Resolved hex accent (border + faded fill); default yellow if absent. */
+  readonly color?: string;
+  readonly lines: readonly WrappedDescLine[];
+  readonly lineNumber: number;
+  readonly endLineNumber: number;
+  /**
+   * When true the note is collapsed: the renderer draws a small badge at
+   * the node corner instead of the floated box, and `x/y/width/height/side/
+   * lines` are unused. Collapsed notes reserve no layout space.
+   */
+  readonly collapsed?: boolean;
+}
 
 export interface LayoutNode {
   readonly id: string;
@@ -18,6 +45,13 @@ export interface LayoutNode {
   readonly y: number;
   readonly width: number;
   readonly height: number;
+  /**
+   * A note floated beside this node. The shape keeps its natural dagre
+   * position and dimensions (so its edges stay connected) — the note is
+   * placed in adjacent space and the canvas bounds are expanded to fit
+   * it. Absent on un-annotated nodes.
+   */
+  readonly note?: NoteLayout;
 }
 
 export interface LayoutEdge {
@@ -45,6 +79,11 @@ export interface LayoutOptions {
   collapsedChildCounts?: Map<string, number>;
   /** Original groups before collapse (includes collapsed ones) */
   originalGroups?: readonly GraphGroup[];
+  /**
+   * 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 LayoutResult {
@@ -75,6 +114,7 @@ export function layoutGraph(
 ): LayoutResult {
   const collapsedChildCounts = options?.collapsedChildCounts;
   const originalGroups = options?.originalGroups;
+  const collapsedNotes = options?.collapsedNotes;
 
   // Collapsed groups become synthetic nodes in the graph
   const collapsedGroupNodes: GraphNode[] = [];
@@ -124,12 +164,48 @@ export function layoutGraph(
     }
   }
 
-  // Add nodes with computed dimensions
+  // Resolve note anchors (no diagnostics here — the parser already
+  // emitted them). `no-notes` drops the reserved footprint entirely so
+  // layout matches an un-annotated diagram (ADR-4 / AC8).
+  const notesSuppressed = graph.options?.['no-notes'] === 'on';
+  const noteByNode =
+    notesSuppressed || !graph.notes
+      ? new Map()
+      : resolveNotes(graph.notes, graph.nodes);
+
+  // Pre-computed note geometry, keyed by node id, threaded into LayoutNode.
+  // The note does NOT change the node's dagre dims — the shape keeps its
+  // position and its edge connections; the note floats beside it and the
+  // canvas bounds are expanded to fit it.
+  interface NoteGeom {
+    noteW: number;
+    noteH: number;
+    color?: string;
+    lines: WrappedDescLine[];
+    lineNumber: number;
+    endLineNumber: number;
+  }
+  const noteGeoms = new Map<string, NoteGeom>();
+
+  // Add nodes with their natural dimensions (notes never inflate them).
   for (const node of allNodes) {
     const width = computeNodeWidth(node.label, node.shape);
     const height = computeNodeHeight(node.shape);
     g.setNode(node.id, { label: node.label, width, height });
 
+    const note = noteByNode.get(node.id);
+    if (note) {
+      const size = noteBoxSize(note.body);
+      noteGeoms.set(node.id, {
+        noteW: size.width,
+        noteH: size.height,
+        ...(note.color && { color: note.color }),
+        lines: size.lines,
+        lineNumber: note.lineNumber,
+        endLineNumber: note.endLineNumber,
+      });
+    }
+
     // Set parent for grouped nodes (only for non-collapsed groups)
     if (node.group && graph.groups?.some((gr) => gr.id === node.group)) {
       g.setParent(node.id, node.group);
@@ -154,8 +230,44 @@ export function layoutGraph(
     ? new Set(collapsedChildCounts.keys())
     : new Set<string>();
 
-  const layoutNodes: LayoutNode[] = allNodes.map((node): LayoutNode => {
+  // Positioned nodes (no notes yet) — feeds collision-aware placement.
+  const basePositioned = allNodes.map((node) => {
     const pos = g.node(node.id);
+    return { node, x: pos.x, y: pos.y, width: pos.width, height: pos.height };
+  });
+
+  // ── Collision-aware note placement (shared `utils/notes`) ───
+  // The note floats beside its node WITHOUT moving it: try the default
+  // side, flip to the opposite, then push outward past blockers — each
+  // placed note becoming an obstacle for later notes. Collapsed notes
+  // reserve no space (drawn as a corner badge).
+  const noteRequests = basePositioned
+    .filter((p) => noteGeoms.has(p.node.id))
+    .map((p) => {
+      const ng = noteGeoms.get(p.node.id)!;
+      return {
+        key: p.node.id,
+        node: { x: p.x, y: p.y, width: p.width, height: p.height },
+        noteW: ng.noteW,
+        noteH: ng.noteH,
+        collapsed: collapsedNotes?.has(ng.lineNumber) ?? false,
+      };
+    });
+  const placements = placeNotes(
+    basePositioned.map((p) => ({
+      x: p.x,
+      y: p.y,
+      width: p.width,
+      height: p.height,
+    })),
+    noteRequests,
+    graph.direction === 'LR' ? 'LR' : 'TB'
+  );
+
+  const layoutNodes: LayoutNode[] = basePositioned.map((p): LayoutNode => {
+    const node = p.node;
+    const ng = noteGeoms.get(node.id);
+    const placed = placements.get(node.id);
     return {
       id: node.id,
       label: node.label,
@@ -163,10 +275,38 @@ export function layoutGraph(
       ...(node.color !== undefined && { color: node.color }),
       ...(node.group !== undefined && { group: node.group }),
       lineNumber: node.lineNumber,
-      x: pos.x,
-      y: pos.y,
-      width: pos.width,
-      height: pos.height,
+      x: p.x,
+      y: p.y,
+      width: p.width,
+      height: p.height,
+      ...(ng &&
+        placed && {
+          // Local coords relative to the node center (translate origin).
+          note: placed.collapsed
+            ? {
+                x: 0,
+                y: 0,
+                width: 0,
+                height: 0,
+                side: 'right' as NoteSide,
+                ...(ng.color && { color: ng.color }),
+                lines: [],
+                lineNumber: ng.lineNumber,
+                endLineNumber: ng.endLineNumber,
+                collapsed: true,
+              }
+            : {
+                x: placed.x,
+                y: placed.y,
+                width: ng.noteW,
+                height: ng.noteH,
+                side: placed.side,
+                ...(ng.color && { color: ng.color }),
+                lines: ng.lines,
+                lineNumber: ng.lineNumber,
+                endLineNumber: ng.endLineNumber,
+              },
+        }),
     };
   });
 
@@ -260,29 +400,72 @@ export function layoutGraph(
     }
   }
 
-  // Compute total diagram dimensions
-  let totalWidth = 0;
-  let totalHeight = 0;
+  // Content bounding box over nodes, their (floated) notes, and groups.
+  // Notes placed above/left of a node can land at negative coordinates;
+  // when they do, everything is shifted so nothing clips on export. Edges
+  // are intentionally excluded (matching the prior bounds behavior) so
+  // un-annotated layouts are byte-for-byte unchanged.
+  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) {
+      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 group of layoutGroups) {
-    const right = group.x + group.width;
-    const bottom = group.y + group.height;
-    if (right > totalWidth) totalWidth = right;
-    if (bottom > totalHeight) totalHeight = bottom;
+    extend(group.x, group.y, group.x + group.width, group.y + group.height);
+  }
+  if (!Number.isFinite(bbMinX)) {
+    bbMinX = 0;
+    bbMinY = 0;
+    bbMaxX = 0;
+    bbMaxY = 0;
   }
-  // Add margin
-  totalWidth += 40;
-  totalHeight += 40;
+
+  // Shift only when content runs off the top/left (note placed above/left).
+  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;
+  const finalGroups = shifted
+    ? layoutGroups.map((gr) => ({ ...gr, x: gr.x + shiftX, y: gr.y + shiftY }))
+    : layoutGroups;
+
+  // Add margin (matches prior behavior: max-edge + 40).
+  const totalWidth = bbMaxX + shiftX + 40;
+  const totalHeight = bbMaxY + shiftY + 40;
 
   return {
-    nodes: layoutNodes,
-    edges: layoutEdges,
-    groups: layoutGroups,
+    nodes: finalNodes,
+    edges: finalEdges,
+    groups: finalGroups,
     width: totalWidth,
     height: totalHeight,
   };

package/src/graph/notes.ts

@@ -0,0 +1,21 @@
+// ============================================================
+// Graph notes — thin re-export over the shared note pipeline
+// ============================================================
+//
+// The note model, grammar, and resolver are now chart-neutral and live in
+// `utils/notes/`. This module stays as the graph family's import site so
+// the flowchart/state parsers (and their tests) keep one stable path. New
+// charts should import from `utils/notes` directly.
+
+export {
+  parseNoteHeader,
+  collectNoteBody,
+  tryCollectNote,
+  resolveNotes,
+} from '../utils/notes';
+export type {
+  DiagramNote,
+  CollectedNoteBody,
+  TryCollectNoteResult,
+  NoteTarget,
+} from '../utils/notes';

package/src/graph/state-parser.ts

@@ -18,7 +18,8 @@ import {
 } from '../utils/parsing';
 import { normalizeName, displayName } from '../utils/name-normalize';
 import type { Writable } from '../utils/brand';
-import type { ParsedGraph, GraphNode, GraphGroup } from './types';
+import type { ParsedGraph, GraphNode, GraphGroup, GraphNote } from './types';
+import { tryCollectNote, resolveNotes } from './notes';
 
 // ============================================================
 // Constants
@@ -203,6 +204,7 @@ export function parseState(
 
   const nodeMap = new Map<string, Writable<GraphNode>>();
   const indentStack: { nodeId: string; indent: number }[] = [];
+  const notes: GraphNote[] = [];
   let currentGroup: Writable<GraphGroup> | null = null;
   let groupIndent = -1;
   const groups: Writable<GraphGroup>[] = [];
@@ -309,6 +311,23 @@ export function parseState(
       }
     }
 
+    // Note annotation: `note <ref> [inline body]` + optional indented
+    // body. Only `note -> X` (arrow immediately after `note`) is excluded
+    // so a transition FROM a state named "note" still parses; 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;
+    }
+
     // Group brackets: [Name] or [Name](color)
     const groupMatch = trimmed.match(GROUP_BRACKET_RE);
     // Regex capture group 1 is mandatory in GROUP_BRACKET_RE.
@@ -492,6 +511,12 @@ export function parseState(
 
   if (groups.length > 0) result.groups = groups;
 
+  // Resolve note refs against the state node map (forward refs OK).
+  if (notes.length > 0) {
+    result.notes = notes;
+    resolveNotes(notes, result.nodes, result.diagnostics);
+  }
+
   // Validation: no nodes found
   if (result.nodes.length === 0 && !result.error) {
     const diag = makeDgmoError(