@diagrammo/dgmo 0.25.5 → 0.27.0

package/src/sequence/renderer.ts

@@ -27,6 +27,7 @@ import {
   wrapDescriptionLines,
   type WrappedDescLine,
 } from '../utils/wrapped-desc';
+import { measureText, truncateText } from '../utils/text-measure';
 import { resolveSequenceTags } from './tag-resolution';
 import type { ResolvedTagMap } from './tag-resolution';
 import { resolveActiveTagGroup } from '../utils/tag-groups';
@@ -67,48 +68,57 @@ const NOTE_PAD_V = 6;
 const NOTE_FONT_SIZE = 10;
 const NOTE_LINE_H = 14;
 const NOTE_GAP = 15;
-const NOTE_CHAR_W = 6;
 const ACTIVATION_WIDTH = 10;
 const SELF_CALL_HEIGHT = 25;
 const SELF_CALL_WIDTH = 30;
 // Actors render their label below the stick figure (at boxH + 14). Their
 // lifeline starts this far below the box so the dashes clear the label text.
 const ACTOR_LABEL_CLEARANCE = 22;
-function wrapTextLines(text: string, maxChars: number): WrappedDescLine[] {
+function wrapTextLines(
+  text: string,
+  maxWidth: number,
+  fontSize: number
+): WrappedDescLine[] {
   // Convert leading "- " to the canonical bullet prefix so the shared wrap
   // helper can split bullet lines into bullet-first / bullet-cont kinds and
   // give us hanging-indent alignment on continuation lines.
   const rawLines = text
     .split('\n')
     .map((l) => (l.startsWith('- ') ? '• ' + l.slice(2) : l));
-  return wrapDescriptionLines(rawLines, maxChars);
+  // Drive the shared bullet-aware wrapper by pixel width: passing the note's
+  // available text width as the limit and a glyph-accurate measurer as the
+  // length function turns its char-count comparison into a true pixel wrap.
+  return wrapDescriptionLines(rawLines, maxWidth, (s) =>
+    measureText(s, fontSize)
+  );
 }
 
+/**
+ * Available pixel width for a participant label inside a box of the given
+ * width (the 10px accounts for the same left/right inset the layout uses).
+ */
+const labelTextWidth = (boxW: number): number => boxW - 10;
+
 /**
  * Split a participant label into multiple lines if it exceeds the box width.
  * Splits on spaces first, then dashes, then camelCase boundaries.
- * Approximate max chars based on font-size 13 (~7.5px per char average).
  */
-const LABEL_CHAR_WIDTH = 7.5;
-const LABEL_MAX_CHARS = Math.floor(
-  (PARTICIPANT_BOX_WIDTH - 10) / LABEL_CHAR_WIDTH
-); // ~14 chars
-
 function splitParticipantLabel(
   label: string,
-  maxChars: number = LABEL_MAX_CHARS
+  maxWidth: number,
+  fontSize: number
 ): string[] {
-  if (label.length <= maxChars) return [label];
+  if (measureText(label, fontSize) <= maxWidth) return [label];
 
   // Split on spaces
   if (label.includes(' ')) {
-    return wrapLabelWords(label.split(' '), maxChars);
+    return wrapLabelWords(label.split(' '), maxWidth, fontSize);
   }
 
   // Split on dashes/underscores/colons/slashes
   if (/[-_:/]/.test(label)) {
     const parts = label.split(/[-_:/]+/);
-    return wrapLabelWords(parts, maxChars);
+    return wrapLabelWords(parts, maxWidth, fontSize);
   }
 
   // Split on camelCase boundaries: "UserLookupCloudFx" → ["User", "Lookup", "Cloud", "Fx"]
@@ -117,19 +127,23 @@ function splitParticipantLabel(
     .replace(/([A-Z]+)([A-Z][a-z])/g, '$1\x00$2')
     .split('\x00');
   if (camelParts.length > 1) {
-    return wrapLabelWords(camelParts, maxChars);
+    return wrapLabelWords(camelParts, maxWidth, fontSize);
   }
 
   return [label];
 }
 
-/** Greedily join word parts into lines that fit within maxChars. */
-function wrapLabelWords(words: string[], maxChars: number): string[] {
+/** Greedily join word parts into lines that fit within maxWidth pixels. */
+function wrapLabelWords(
+  words: string[],
+  maxWidth: number,
+  fontSize: number
+): string[] {
   const lines: string[] = [];
   let current = '';
   for (const word of words) {
     const test = current ? current + word : word;
-    if (test.length > maxChars && current) {
+    if (measureText(test, fontSize) > maxWidth && current) {
       lines.push(current);
       current = word;
     } else {
@@ -929,10 +943,16 @@ export function renderSequenceDiagram(
   const MAX_BOX_WIDTH = 225;
   let uniformBoxWidth = PARTICIPANT_BOX_WIDTH;
   for (const p of participants) {
-    const lines = splitParticipantLabel(p.label, LABEL_MAX_CHARS);
+    const lines = splitParticipantLabel(
+      p.label,
+      labelTextWidth(PARTICIPANT_BOX_WIDTH),
+      LABEL_FONT_SIZE
+    );
     if (lines.length === 0) continue;
-    const widest = Math.max(...lines.map((l) => l.length));
-    const labelWidth = widest * LABEL_CHAR_WIDTH + 10;
+    const widest = Math.max(
+      ...lines.map((l) => measureText(l, LABEL_FONT_SIZE))
+    );
+    const labelWidth = widest + 10;
     uniformBoxWidth = Math.max(uniformBoxWidth, labelWidth);
   }
   uniformBoxWidth = Math.min(MAX_BOX_WIDTH, uniformBoxWidth);
@@ -964,17 +984,16 @@ export function renderSequenceDiagram(
   const sNoteFontSize = ctx.text(NOTE_FONT_SIZE);
   const sNoteLineH = ctx.structural(NOTE_LINE_H);
   const sNoteGap = ctx.structural(NOTE_GAP);
-  const sNoteCharW = ctx.text(NOTE_CHAR_W, 4);
   const sActivationWidth = ctx.structural(ACTIVATION_WIDTH);
   const sSelfCallHeight = SELF_CALL_HEIGHT;
   const sSelfCallWidth = ctx.structural(SELF_CALL_WIDTH);
-  const sNoteCharsPerLine = Math.floor(
-    (sNoteMaxW - sNotePadH * 2 - sNoteFold) / sNoteCharW
-  );
+  // Pixel width available for note text inside the widest allowed note box
+  // (box width minus the horizontal padding on both sides and the fold cut).
+  const sNoteTextWidthMax = sNoteMaxW - sNotePadH * 2 - sNoteFold;
   const sNoteLaneMax = sGap - sActivationWidth - sNoteGap;
-  const sLabelCharWidth = ctx.text(LABEL_CHAR_WIDTH, 5);
-  const sLabelMaxChars = Math.floor((sBoxW - 10) / sLabelCharWidth);
   const sLabelFontSize = ctx.text(LABEL_FONT_SIZE);
+  // Pixel width available for a participant label inside the scaled box.
+  const sLabelTextWidth = labelTextWidth(sBoxW);
 
   // Participant index lookup — used to clamp note width within one lane
   const participantIndexMap = new Map<string, number>();
@@ -1017,8 +1036,10 @@ export function renderSequenceDiagram(
     return Math.min(sNoteMaxW, laneMax);
   };
 
-  const charsForWidth = (maxW: number): number =>
-    Math.floor((maxW - sNotePadH * 2 - sNoteFold) / sNoteCharW);
+  // Pixel width available for note text inside a note box of the given outer
+  // width — outer width minus horizontal padding (both sides) and the fold cut.
+  const noteTextWidth = (maxW: number): number =>
+    maxW - sNotePadH * 2 - sNoteFold;
 
   const activationsOff = parsedOptions['activations']?.toLowerCase() === 'off';
 
@@ -1249,9 +1270,9 @@ export function renderSequenceDiagram(
   const NOTE_TRAILING_GAP = ctx.aesthetic(35);
   const computeNoteHeight = (
     text: string,
-    maxChars: number = sNoteCharsPerLine
+    textWidth: number = sNoteTextWidthMax
   ): number => {
-    const lines = wrapTextLines(text, maxChars);
+    const lines = wrapTextLines(text, textWidth, sNoteFontSize);
     return lines.length * sNoteLineH + sNotePadV * 2;
   };
   let trailingNoteSpace = 0; // extra space for notes at the end with no following message
@@ -1273,7 +1294,7 @@ export function renderSequenceDiagram(
           const note = els[j]! as SequenceNote;
           const sc = isNoteAfterSelfCall(note);
           const maxW = noteEffectiveMaxW(note.participantId, note.position, sc);
-          const noteH = computeNoteHeight(note.text, charsForWidth(maxW));
+          const noteH = computeNoteHeight(note.text, noteTextWidth(maxW));
           totalExtent += noteH + NOTE_OFFSET_BELOW;
           j++;
         }
@@ -1571,7 +1592,7 @@ export function renderSequenceDiagram(
             );
             const prevNoteH = computeNoteHeight(
               prevNote.text,
-              charsForWidth(prevMaxW)
+              noteTextWidth(prevMaxW)
             );
             noteTopY = prevNoteY + prevNoteH + NOTE_OFFSET_BELOW;
           } else {
@@ -1615,7 +1636,7 @@ export function renderSequenceDiagram(
       effectiveNotePosition(note),
       isNoteAfterSelfCall(note)
     );
-    const noteH = computeNoteHeight(note.text, charsForWidth(maxW));
+    const noteH = computeNoteHeight(note.text, noteTextWidth(maxW));
     contentBottomY = Math.max(
       contentBottomY,
       noteTopY + noteH + NOTE_TRAILING_GAP
@@ -1651,7 +1672,8 @@ export function renderSequenceDiagram(
       if (step.from === step.to && step.from === rightmostId) {
         const selfProj = sActivationWidth + sSelfCallWidth;
         let labelProj = 0;
-        if (step.label) labelProj = step.label.length * sLabelCharWidth + 15;
+        // Self-call labels render at the fixed 12px message-label size.
+        if (step.label) labelProj = measureText(step.label, 12) + 15;
         rightProjection = Math.max(rightProjection, selfProj + labelProj);
       }
     }
@@ -1726,12 +1748,11 @@ export function renderSequenceDiagram(
   // Post-layout content scan: detect labels/notes that overflow the SVG boundaries.
   // Message labels render at a fixed 12px font (unscaled) so they can extend past
   // the scaled participant grid at small scale factors.
-  const MSG_LABEL_CHAR_W = 7;
   let contentLeft = 0;
   let contentRight = svgWidth;
   for (const step of renderSteps) {
     if (!step.label) continue;
-    const labelW = step.label.length * MSG_LABEL_CHAR_W;
+    const labelW = measureText(step.label, 12);
     if (step.from === step.to) {
       const px = participantX.get(step.from);
       if (px !== undefined) {
@@ -2101,7 +2122,7 @@ export function renderSequenceDiagram(
       solid,
       sBoxW,
       sBoxH,
-      sLabelMaxChars,
+      sLabelTextWidth,
       sLabelFontSize
     );
 
@@ -2651,7 +2672,8 @@ export function renderSequenceDiagram(
 
     // Transparent hit area scoped to the label so the toggle stays clickable
     // without the band swallowing clicks across the full diagram width.
-    const labelHitW = Math.max(80, labelText.length * 7 + 24);
+    // Label renders at the fixed 11px section-label size.
+    const labelHitW = Math.max(80, measureText(labelText, 11) + 24);
     sectionG
       .append('rect')
       .attr('x', labelX - labelHitW / 2)
@@ -2915,13 +2937,15 @@ export function renderSequenceDiagram(
           position,
           afterSelfCall
         );
-        const maxChars = charsForWidth(maxW);
-        const wrappedLines = wrapTextLines(el.text, maxChars);
+        const textWidth = noteTextWidth(maxW);
+        const wrappedLines = wrapTextLines(el.text, textWidth, sNoteFontSize);
         const noteH = wrappedLines.length * sNoteLineH + sNotePadV * 2;
-        const maxLineLen = Math.max(...wrappedLines.map((l) => l.text.length));
+        const maxLineW = Math.max(
+          ...wrappedLines.map((l) => measureText(l.text, sNoteFontSize))
+        );
         const noteW = Math.min(
           maxW,
-          Math.max(80, maxLineLen * sNoteCharW + sNotePadH * 2 + sNoteFold)
+          Math.max(80, maxLineW + sNotePadH * 2 + sNoteFold)
         );
         // Shift notes past self-call loopback when applicable
         const rightOffset =
@@ -3089,7 +3113,7 @@ function renderParticipant(
   solid?: boolean,
   boxW: number = W,
   boxH: number = H,
-  labelMaxChars: number = LABEL_MAX_CHARS,
+  labelTextW: number = labelTextWidth(W),
   labelFontSize: number = LABEL_FONT_SIZE
 ): void {
   const g = svg
@@ -3124,7 +3148,11 @@ function renderParticipant(
 
   // Render label — below the shape for actors, centered inside for others
   const isActor = participant.type === 'actor';
-  const labelLines = splitParticipantLabel(participant.label, labelMaxChars);
+  const labelLines = splitParticipantLabel(
+    participant.label,
+    labelTextW,
+    labelFontSize
+  );
   const fontSize = labelFontSize;
   const lineHeight = fontSize + 2;
   const labelFill = isActor
@@ -3142,12 +3170,9 @@ function renderParticipant(
     .attr('font-size', fontSize)
     .attr('font-weight', 500);
 
-  const maxLabelW = boxW - 10;
-  const truncLine = (text: string): string => {
-    if (text.length * (fontSize * 0.6) <= maxLabelW) return text;
-    const maxCharsEst = Math.floor(maxLabelW / (fontSize * 0.6));
-    return maxCharsEst > 2 ? text.slice(0, maxCharsEst - 1) + '…' : text;
-  };
+  const maxLabelW = labelTextWidth(boxW);
+  const truncLine = (text: string): string =>
+    truncateText(text, fontSize, maxLabelW);
 
   if (labelLines.length === 1) {
     textEl

package/src/sitemap/layout.ts

@@ -10,8 +10,24 @@ import { resolveTagColor, injectDefaultTagMetadata } from '../utils/tag-groups';
 import {
   LEGEND_PILL_FONT_SIZE,
   LEGEND_ENTRY_FONT_SIZE,
+  LEGEND_HEIGHT,
+  LEGEND_PILL_PAD,
+  LEGEND_CAPSULE_PAD,
+  LEGEND_DOT_R,
+  LEGEND_ENTRY_DOT_GAP,
+  LEGEND_ENTRY_TRAIL,
+  LEGEND_GROUP_GAP,
+  LEGEND_EYE_SIZE,
+  LEGEND_EYE_GAP,
   measureLegendText,
 } from '../utils/legend-constants';
+import { measureText } from '../utils/text-measure';
+
+// Font sizes — must match the renderer (renderer.ts) so card sizing here
+// agrees pixel-for-pixel with what gets drawn.
+const LABEL_FONT_SIZE = 13;
+const META_FONT_SIZE = 11;
+const CONTAINER_LABEL_FONT_SIZE = 13;
 
 // ============================================================
 // Types
@@ -119,7 +135,6 @@ function clipToRectBorder(
 // Constants
 // ============================================================
 
-const CHAR_WIDTH = 7.5;
 const META_LINE_HEIGHT = 16;
 const HEADER_HEIGHT = 28;
 const SEPARATOR_GAP = 6;
@@ -134,15 +149,6 @@ const CONTAINER_LABEL_HEIGHT = 28;
 const CONTAINER_META_LINE_HEIGHT = 16;
 
 // Legend (kanban-style pills)
-const LEGEND_HEIGHT = 28;
-const LEGEND_PILL_PAD = 16;
-const LEGEND_CAPSULE_PAD = 4;
-const LEGEND_DOT_R = 4;
-const LEGEND_ENTRY_DOT_GAP = 4;
-const LEGEND_ENTRY_TRAIL = 8;
-const LEGEND_GROUP_GAP = 12;
-const LEGEND_EYE_SIZE = 14;
-const LEGEND_EYE_GAP = 6;
 
 // ============================================================
 // Helpers
@@ -167,20 +173,22 @@ function computeCardWidth(
   meta: Record<string, string>,
   descLines?: readonly string[]
 ): number {
-  let maxChars = label.length;
+  // Measure each text element at the font size the renderer draws it with so
+  // the card never under-sizes its content.
+  let maxContentWidth = measureText(label, LABEL_FONT_SIZE);
   for (const [key, value] of Object.entries(meta)) {
-    const lineChars = key.length + 2 + value.length;
-    if (lineChars > maxChars) maxChars = lineChars;
+    // Renderer draws meta as "key:" then the value, both at META_FONT_SIZE,
+    // with a space separating them.
+    const lineWidth = measureText(`${key}: ${value}`, META_FONT_SIZE);
+    if (lineWidth > maxContentWidth) maxContentWidth = lineWidth;
   }
   if (descLines) {
     for (const dl of descLines) {
-      if (dl.length > maxChars) maxChars = dl.length;
+      const dlWidth = measureText(dl, META_FONT_SIZE);
+      if (dlWidth > maxContentWidth) maxContentWidth = dlWidth;
     }
   }
-  return Math.max(
-    MIN_CARD_WIDTH,
-    Math.ceil(maxChars * CHAR_WIDTH) + CARD_H_PAD * 2
-  );
+  return Math.max(MIN_CARD_WIDTH, Math.ceil(maxContentWidth) + CARD_H_PAD * 2);
 }
 
 function computeCardHeight(
@@ -301,7 +309,7 @@ function flattenNodes(
         fullMeta: { ...node.metadata },
         width: Math.max(
           MIN_CARD_WIDTH,
-          node.label.length * CHAR_WIDTH + CARD_H_PAD * 2
+          measureText(node.label, CONTAINER_LABEL_FONT_SIZE) + CARD_H_PAD * 2
         ),
         height: labelHeight + CONTAINER_PAD_BOTTOM,
       });

package/src/sitemap/renderer.ts

@@ -11,6 +11,7 @@ import type { ParsedSitemap } from './types';
 import type { SitemapLayoutResult, SitemapLegendGroup } from './layout';
 import { renderInlineText } from '../utils/inline-markdown';
 import { preprocessDescriptionLine } from '../utils/description-helpers';
+import { measureText } from '../utils/text-measure';
 import {
   LEGEND_HEIGHT,
   LEGEND_GROUP_GAP,
@@ -347,8 +348,12 @@ export function renderSitemap(
       const metaDisplayKeys = metaEntries.map(
         ([k]) => displayNames.get(k) ?? k
       );
-      const maxKeyLen = Math.max(...metaDisplayKeys.map((k) => k.length));
-      const valueX = 10 + (maxKeyLen + 2) * (sContainerMetaFontSize * 0.6);
+      const maxKeyWidth = Math.max(
+        ...metaDisplayKeys.map((k) =>
+          measureText(`${k}: `, sContainerMetaFontSize)
+        )
+      );
+      const valueX = 10 + maxKeyWidth;
       const metaStartY = sContainerHeaderHeight + sContainerMetaFontSize - 2;
 
       for (let i = 0; i < metaEntries.length; i++) {
@@ -429,7 +434,7 @@ export function renderSitemap(
     // Edge label with background badge
     if (edge.label && edge.points.length >= 2) {
       const mid = edge.points[Math.floor(edge.points.length / 2)]!;
-      const labelW = edge.label.length * sEdgeLabelFontSize * 0.6 + 10;
+      const labelW = measureText(edge.label, sEdgeLabelFontSize) + 10;
       const labelH = sEdgeLabelFontSize + 6;
 
       edgeG
@@ -529,8 +534,10 @@ export function renderSitemap(
       const metaDisplayKeys = metaEntries.map(
         ([k]) => displayNames.get(k) ?? k
       );
-      const maxKeyLen = Math.max(...metaDisplayKeys.map((k) => k.length));
-      const valueX = 10 + (maxKeyLen + 2) * (sMetaFontSize * 0.6);
+      const maxKeyWidth = Math.max(
+        ...metaDisplayKeys.map((k) => measureText(`${k}: `, sMetaFontSize))
+      );
+      const valueX = 10 + maxKeyWidth;
 
       for (let i = 0; i < metaEntries.length; i++) {
         // In-bounds by loop guard.

package/src/tech-radar/renderer.ts

@@ -6,6 +6,11 @@ import type { D3ExportDimensions } from '../utils/d3-types';
 import type { CompactViewState } from '../sharing';
 import { parseInlineMarkdown } from '../utils/inline-markdown';
 import { safeHref } from '../utils/safe-href';
+import {
+  measureText,
+  truncateText,
+  wrapTextToWidth,
+} from '../utils/text-measure';
 import type {
   ParsedTechRadar,
   QuadrantPosition,
@@ -780,7 +785,7 @@ function renderBlipListing(
       const textX = colX + sListingBlipR * 2 + 6;
       const availableWidth = colWidth - sListingBlipR * 2 - 8;
       const fullLabel = `${blip.name} (${blip.ring})`;
-      const label = truncateLabel(fullLabel, availableWidth, sListingFontSize);
+      const label = truncateText(fullLabel, sListingFontSize, availableWidth);
 
       itemGroup
         .append('text')
@@ -834,20 +839,6 @@ function renderBlipListing(
   }
 }
 
-/** Estimate max characters that fit in `availablePx` at the given font size. */
-function truncateLabel(
-  text: string,
-  availablePx: number,
-  fontSize: number
-): string {
-  // Average character width ≈ 0.58 × fontSize for Helvetica/Inter
-  const avgCharWidth = fontSize * 0.58;
-  const maxChars = Math.floor(availablePx / avgCharWidth);
-  if (maxChars <= 0) return '';
-  if (text.length <= maxChars) return text;
-  return text.substring(0, maxChars - 1) + '\u2026';
-}
-
 // ============================================================
 // Ring×Quadrant Hover Interactivity
 // ============================================================
@@ -1164,28 +1155,13 @@ function renderQuadrantLabel(
   maxWidth: number,
   baseFontSize = QUADRANT_LABEL_FONT_SIZE
 ): void {
-  const avgCharWidth = baseFontSize * 0.58;
-  const maxCharsPerLine = Math.floor(maxWidth / avgCharWidth);
-
-  // Split into words and wrap
-  const words = name.split(/\s+/);
-  const lines: string[] = [];
-  let currentLine = '';
-
-  for (const word of words) {
-    const testLine = currentLine ? `${currentLine} ${word}` : word;
-    if (testLine.length > maxCharsPerLine && currentLine) {
-      lines.push(currentLine);
-      currentLine = word;
-    } else {
-      currentLine = testLine;
-    }
-  }
-  if (currentLine) lines.push(currentLine);
+  // Greedy word-wrap to the available pixel width.
+  const lines = wrapTextToWidth(name, baseFontSize, maxWidth);
 
   // Scale font down if any line is still too wide
-  const longestLine = Math.max(...lines.map((l) => l.length));
-  const estimatedWidth = longestLine * avgCharWidth;
+  const estimatedWidth = Math.max(
+    ...lines.map((l) => measureText(l, baseFontSize))
+  );
   const fontSize =
     estimatedWidth > maxWidth
       ? Math.max(12, baseFontSize * (maxWidth / estimatedWidth))

package/src/utils/arrow-markers.ts

@@ -0,0 +1,51 @@
+// ============================================================
+// Shared arrowhead <marker> defs
+// ============================================================
+// The flowchart and state renderers carried a byte-identical block
+// that appends a base arrowhead marker plus one per edge color. This
+// is the single source so they can't drift.
+
+import type { BaseType, Selection } from 'd3-selection';
+
+export interface ArrowheadMarkerOptions {
+  /** Marker id prefix, e.g. 'fc' → `fc-arrow`, `fc-arrow-<hex>`. */
+  idPrefix: string;
+  /** Marker width (already scaled by the caller's ScaleContext). */
+  width: number;
+  /** Marker height. */
+  height: number;
+  /** Fill for the base (uncolored) arrowhead. */
+  baseFill: string;
+  /** Edge colors needing their own tinted marker (hex strings). */
+  colors?: Iterable<string>;
+}
+
+/**
+ * Append an arrowhead `<marker>` (id `${idPrefix}-arrow`) to `defs`, plus
+ * one tinted marker per edge color (id `${idPrefix}-arrow-<hex-without-#>`).
+ */
+export function appendArrowheadMarkers<GElement extends BaseType>(
+  defs: Selection<GElement, unknown, null, undefined>,
+  opts: ArrowheadMarkerOptions
+): void {
+  const { idPrefix, width, height, baseFill, colors } = opts;
+  const appendMarker = (id: string, fill: string): void => {
+    defs
+      .append('marker')
+      .attr('id', id)
+      .attr('viewBox', `0 0 ${width} ${height}`)
+      .attr('refX', width)
+      .attr('refY', height / 2)
+      .attr('markerWidth', width)
+      .attr('markerHeight', height)
+      .attr('orient', 'auto')
+      .append('polygon')
+      .attr('points', `0,0 ${width},${height / 2} 0,${height}`)
+      .attr('fill', fill);
+  };
+
+  appendMarker(`${idPrefix}-arrow`, baseFill);
+  for (const color of colors ?? []) {
+    appendMarker(`${idPrefix}-arrow-${color.replace('#', '')}`, color);
+  }
+}

package/src/utils/fit-canvas.ts

@@ -0,0 +1,64 @@
+// ============================================================
+// Diagram → canvas fit
+// ============================================================
+// Shared by renderers that top-anchor a diagram and fit it to the
+// canvas with the same scale model. Each renderer with a *different*
+// model (legend-band reserves, vertical centering, content-padded
+// scale) keeps its own math on purpose — this is only for the ones
+// that were byte-identical.
+
+export interface CanvasFit {
+  scale: number;
+  offsetX: number;
+  offsetY: number;
+  canvasHeight: number;
+}
+
+export interface FitDiagramParams {
+  /** Canvas width. */
+  width: number;
+  /** Canvas height (interactive pane height; ignored for canvasHeight in export mode). */
+  height: number;
+  /** Laid-out diagram width / height. */
+  diagramW: number;
+  diagramH: number;
+  /** Scaled padding around the diagram. */
+  padding: number;
+  /** Reserved height above the diagram (title band), 0 if none. */
+  titleHeight: number;
+  /** Upper bound on scale. */
+  maxScale: number;
+  /** True when rendering to a fixed export canvas. */
+  exportMode: boolean;
+}
+
+/**
+ * Fit a top-anchored diagram into the canvas.
+ *
+ * Export renders a fixed canvas (e.g. 1200×800); fitting a small graph into it
+ * and top-anchoring leaves a tall dead band below. In export mode we scale to
+ * width (capped by maxScale) and size the canvas to the scaled content height.
+ * The interactive preview keeps fit-to-pane (min of width/height scale) so a
+ * small graph still fills its pane.
+ */
+export function fitDiagramToCanvas(p: FitDiagramParams): CanvasFit {
+  const scaleX = (p.width - p.padding * 2) / p.diagramW;
+  let scale: number;
+  let canvasHeight: number;
+  if (p.exportMode) {
+    scale = Math.min(p.maxScale, scaleX);
+    canvasHeight = p.titleHeight + p.diagramH * scale + p.padding * 2;
+  } else {
+    const availH = p.height - p.titleHeight;
+    const scaleY = (availH - p.padding * 2) / p.diagramH;
+    scale = Math.min(p.maxScale, scaleX, scaleY);
+    canvasHeight = p.height;
+  }
+  const scaledW = p.diagramW * scale;
+  return {
+    scale,
+    offsetX: (p.width - scaledW) / 2,
+    offsetY: p.titleHeight + p.padding,
+    canvasHeight,
+  };
+}