dsh-model-everything 0.5.0 → 0.5.2

package/src/render/svg.ts

@@ -1,127 +1,274 @@
-/**
- * Shapes to SVG markup.
- *
- * The one module that knows tags, so it is also the one place where a shape can silently disappear if a
- * writer forgets a case: the writer table has an entry per shape kind, and the caller counts the drops
- * instead of hiding them.
- *
- * Three containers read this output - an inline card, a full-screen view, and a sidebar tab - so the markup
- * carries no size of its own beyond its `viewBox`: the container decides how large the drawing is, and the
- * same string serves a thumbnail and a whiteboard.
- *
- * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
- */
-
-import type { Canvas, Shape } from './paint.js'
-import type { Palette } from './palette.js'
-
-/** One decimal place is enough at any zoom, and it keeps the markup readable. */
-const n = (value: number): string => {
-  const rounded = Math.round(value * 10) / 10
-  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1)
-}
-
-const escape = (value: string): string =>
-  value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;')
-
-type Writer<K extends Shape['kind']> = (shape: Extract<Shape, { kind: K }>, colours: Palette) => string
-
-const writers: { [K in Shape['kind']]: Writer<K> } = {
-  // A boundary is a dashed rectangle with its name in the top-left corner, drawn under everything else.
-  group: (shape, colours) => {
-    const stroke = colours[shape.colour]
-    // The id travels in the markup so a container can fold a boundary by delegation, without re-deriving which
-    // group a click landed on from its position or its label.
-    return (
-      '<g data-group-id="' + escape(shape.id) + '" style="cursor:pointer">' +
-      '<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
-      '" rx="8" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-dasharray="4 3" />' +
-      '<text x="' + n(shape.x + 6) + '" y="' + n(shape.y + 12) + '" font-size="10" fill="' + stroke + '">' + escape(shape.label) + '</text>' +
-      '</g>'
-    )
-  },
-  box: (shape, colours) => {
-    const stroke = colours[shape.colour]
-    const width = shape.initial ? 2.5 : 1
-    return (
-      '<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
-      '" rx="6" fill="' + colours.surface + '" stroke="' + stroke + '" stroke-width="' + n(width) + '" />' +
-      '<text x="' + n(shape.x + shape.width / 2) + '" y="' + n(shape.y + shape.height / 2 + 4) +
-      '" font-size="11" text-anchor="middle" fill="' + stroke + '">' + escape(shape.label) + '</text>'
-    )
-  },
-  link: (shape, colours) => {
-    const stroke = colours[shape.colour]
-    const arrow = arrowHead(shape.x1, shape.y1, shape.x2, shape.y2, stroke)
-    return (
-      '<line x1="' + n(shape.x1) + '" y1="' + n(shape.y1) + '" x2="' + n(shape.x2) + '" y2="' + n(shape.y2) +
-      '" stroke="' + stroke + '" stroke-width="1" />' + arrow + edgeLabel(shape.label, shape.labelX, shape.labelY, colours)
-    )
-  },
-  path: (shape, colours) => {
-    const stroke = colours[shape.colour]
-    const points = shape.points.map((point) => n(point.x) + ',' + n(point.y)).join(' ')
-    const last = shape.points[shape.points.length - 1]
-    const before = shape.points[shape.points.length - 2] ?? last
-    return (
-      '<polyline points="' + points + '" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-linejoin="round" />' +
-      arrowHead(before.x, before.y, last.x, last.y, stroke) + edgeLabel(shape.label, shape.labelX, shape.labelY, colours)
-    )
-  },
-  title: (shape, colours) => {
-    return '<text x="' + n(shape.x) + '" y="' + n(shape.y) + '" font-size="12" fill="' + colours[shape.colour] + '">' + escape(shape.text) + '</text>'
-  },
-  caption: (shape, colours) => {
-    const colour = colours[shape.colour]
-    const lines = shape.lines
-      .map((line, index) => '<tspan x="' + n(shape.x) + '" dy="' + (index === 0 ? 0 : 15) + '">' + escape(line) + '</tspan>')
-      .join('')
-    return '<text x="' + n(shape.x) + '" y="' + n(shape.y + 11) + '" font-size="10" fill="' + colour + '">' + lines + '</text>'
-  },
-}
-
-/** A small filled triangle at the end of a segment, pointing along it. */
-function arrowHead(x1: number, y1: number, x2: number, y2: number, stroke: string): string {
-  const length = Math.hypot(x2 - x1, y2 - y1)
-  if (length < 1) return ''
-  const ux = (x2 - x1) / length
-  const uy = (y2 - y1) / length
-  const size = 7
-  const half = 3.2
-  const baseX = x2 - ux * size
-  const baseY = y2 - uy * size
-  const left = n(baseX - uy * half) + ',' + n(baseY + ux * half)
-  const right = n(baseX + uy * half) + ',' + n(baseY - ux * half)
-  return '<polygon points="' + n(x2) + ',' + n(y2) + ' ' + left + ' ' + right + '" fill="' + stroke + '" />'
-}
-
-/** An edge label, or nothing when the edge carries no event. */
-function edgeLabel(label: string, x: number, y: number, colours: Palette): string {
-  // Total on purpose: a malformed edge must lose its label, not the whole drawing.
-  if (typeof label !== 'string' || label === '') return ''
-  return '<text x="' + n(x) + '" y="' + n(y) + '" font-size="10" fill="' + colours.muted + '">' + escape(label) + '</text>'
-}
-
-export function toSvg(canvas: Canvas, colours: Palette, label?: string): { markup: string; dropped: number } {
-  let dropped = 0
-  const body: string[] = []
-  for (const shape of canvas.shapes) {
-    const writer = writers[shape.kind] as ((shape: Shape, colours: Palette) => string) | undefined
-    if (writer === undefined) {
-      dropped += 1
-      continue
-    }
-    body.push(writer(shape, colours))
-  }
-  const header =
-    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' + n(canvas.width) + ' ' + n(canvas.height) +
-    '" width="' + n(canvas.width) + '" height="' + n(canvas.height) + '" role="img"' +
-    (label === undefined ? '' : ' aria-label="' + escape(label) + '"') +
-    ' font-family="system-ui, -apple-system, Segoe UI, sans-serif">'
-  // The surface is part of the drawing, not the container's business: a page that paints its own layers - a
-  // wallpaper, a themed panel - would otherwise change the contrast of a picture it knows nothing about.
-  const background =
-    '<rect x="0" y="0" width="' + n(canvas.width) + '" height="' + n(canvas.height) +
-    '" fill="' + colours.background + '" />'
-  return { markup: header + background + body.join('') + '</svg>', dropped }
-}
+/**
+ * Shapes to SVG markup.
+ *
+ * The one module that knows tags, so it is also the one place where a shape can silently disappear if a
+ * writer forgets a case: the writer table has an entry per shape kind, and the caller counts the drops
+ * instead of hiding them.
+ *
+ * Three containers read this output - an inline card, a full-screen view, and a sidebar tab - so the markup
+ * carries no size of its own beyond its `viewBox`: the container decides how large the drawing is, and the
+ * same string serves a thumbnail and a whiteboard.
+ *
+ * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
+ */
+
+/**
+ * A box's label, one `tspan` per line.
+ *
+ * The lines were wrapped before the box was placed, so the text fits by construction; a single `<text>` with the
+ * whole label is what used to overflow the box and print on top of its neighbours.
+ */
+function boxText(shape: { x: number; y: number; width: number; height: number; label: string; lines?: string[] }, stroke: string): string {
+  const lines = shape.lines === undefined || shape.lines.length === 0 ? [shape.label] : shape.lines
+  const lineHeight = 15
+  const first = shape.y + shape.height / 2 - ((lines.length - 1) * lineHeight) / 2 + 4
+  const spans = lines
+    .map((line, index) => '<tspan x="' + n(shape.x + shape.width / 2) + '" y="' + n(first + index * lineHeight) + '">' + escape(line) + '</tspan>')
+    .join('')
+  return '<text font-size="11" text-anchor="middle" fill="' + stroke + '">' + spans + '</text>'
+}
+
+
+import { LABEL_HEIGHT, type Canvas, type Shape } from './paint.js'
+import { textWidth } from './text.js'
+import type { EdgeArrow } from './model.js'
+import type { Palette } from './palette.js'
+import { cylinderCaps, diamondPoints, hexagonPoints, stadiumRadius, type Cubic } from './symbol.js'
+
+/** One decimal place is enough at any zoom, and it keeps the markup readable. */
+const n = (value: number): string => {
+  const rounded = Math.round(value * 10) / 10
+  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1)
+}
+
+const escape = (value: string): string =>
+  value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;')
+
+type Writer<K extends Shape['kind']> = (shape: Extract<Shape, { kind: K }>, colours: Palette) => string
+
+const writers: { [K in Shape['kind']]: Writer<K> } = {
+  // A boundary is a dashed rectangle with its name in the top-left corner, drawn under everything else.
+  group: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    // The id travels in the markup so a container can fold a boundary by delegation, without re-deriving which
+    // group a click landed on from its position or its label.
+    return (
+      '<g data-group-id="' + escape(shape.id) + '" style="cursor:pointer">' +
+      '<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
+      '" rx="8" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-dasharray="4 3" />' +
+      '<text x="' + n(shape.x + 6) + '" y="' + n(shape.y + 12) + '" font-size="10" fill="' + stroke + '">' + escape(shape.label) + '</text>' +
+      '</g>'
+    )
+  },
+  box: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    const width = shape.initial ? 2.5 : 1
+    const tail = '" fill="' + colours.surface + '" stroke="' + stroke + '" stroke-width="' + n(width) + '" />'
+    const x = shape.x
+    const y = shape.y
+    const w = shape.width
+    const h = shape.height
+    // The symbol's own points come from `symbol.ts`, which is also where the painter reads a port from: one
+    // arithmetic for the outline, so an anchor cannot disagree with the shape it lands on.
+    const at = (point: { x: number; y: number }): string => n(point.x) + ' ' + n(point.y)
+    const points = (list: Array<{ x: number; y: number }>): string => list.map((point) => n(point.x) + ',' + n(point.y)).join(',')
+    const curve = (segment: Cubic): string => ' C' + at(segment.c1) + ' ' + at(segment.c2) + ' ' + at(segment.to)
+    switch (shape.shape) {
+      // A decision: the notation wrote `{…}`, and a rounded rectangle would say "step".
+      case 'diamond':
+        return '<polygon points="' + points(diamondPoints(shape)) + tail + boxText(shape, stroke)
+      case 'hexagon':
+        return '<polygon points="' + points(hexagonPoints(shape)) + tail + boxText(shape, stroke)
+      // A datastore: the cylinder UML draws for a stored collection.
+      case 'cylinder': {
+        const caps = cylinderCaps(shape)
+        const path = 'M' + at(caps.top.from) + curve(caps.top) + ' L' + at(caps.bottom.from) + curve(caps.bottom) + ' Z'
+        return '<path d="' + path + tail + boxText(shape, stroke)
+      }
+      // A start or end state: the stadium a terminal node is drawn as.
+      case 'stadium':
+        return '<rect x="' + n(x) + '" y="' + n(y) + '" width="' + n(w) + '" height="' + n(h) + '" rx="' + n(stadiumRadius(shape)) + tail + boxText(shape, stroke)
+      case 'circle':
+        return '<ellipse cx="' + n(x + w / 2) + '" cy="' + n(y + h / 2) + '" rx="' + n(w / 2) + '" ry="' + n(h / 2) + tail + boxText(shape, stroke)
+      // A subroutine carries its double side lines.
+      case 'subroutine':
+        return (
+          '<rect x="' + n(x) + '" y="' + n(y) + '" width="' + n(w) + '" height="' + n(h) + tail +
+          '<line x1="' + n(x + 6) + '" y1="' + n(y) + '" x2="' + n(x + 6) + '" y2="' + n(y + h) + '" stroke="' + stroke + '" stroke-width="1" />' +
+          '<line x1="' + n(x + w - 6) + '" y1="' + n(y) + '" x2="' + n(x + w - 6) + '" y2="' + n(y + h) + '" stroke="' + stroke + '" stroke-width="1" />' +
+          boxText(shape, stroke)
+        )
+      default:
+        return '<rect x="' + n(x) + '" y="' + n(y) + '" width="' + n(w) + '" height="' + n(h) + '" rx="6' + tail + boxText(shape, stroke)
+    }
+  },
+  link: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    const marks = edgeMarks(
+      { x: shape.x1, y: shape.y1 },
+      { x: shape.x2, y: shape.y2 },
+      { x: shape.x1, y: shape.y1 },
+      { x: shape.x2, y: shape.y2 },
+      shape.arrow,
+      stroke,
+      colours.background,
+    )
+    return (
+      '<line x1="' + n(shape.x1) + '" y1="' + n(shape.y1) + '" x2="' + n(shape.x2) + '" y2="' + n(shape.y2) +
+      '" stroke="' + stroke + '" stroke-width="1"' + dash(shape) + ' />' + marks + edgeLabel(shape.label, shape.labelX, shape.labelY, colours)
+    )
+  },
+  path: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    const points = shape.points.map((point) => n(point.x) + ',' + n(point.y)).join(' ')
+    const last = shape.points[shape.points.length - 1]
+    const before = shape.points[shape.points.length - 2] ?? last
+    const first = shape.points[0]
+    const after = shape.points[1] ?? first
+    return (
+      '<polyline points="' + points + '" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-linejoin="round"' + dash(shape) + ' />' +
+      edgeMarks(first, after, before, last, shape.arrow, stroke, colours.background) +
+      edgeLabel(shape.label, shape.labelX, shape.labelY, colours)
+    )
+  },
+  // A junction dot: the visible answer to "is this a join or a crossing?". Filled in the line's own colour, so it
+  // reads as the line thickening where a branch meets it rather than as a new mark on the page.
+  junction: (shape, colours) =>
+    '<circle cx="' + n(shape.x) + '" cy="' + n(shape.y) + '" r="2.5" fill="' + colours[shape.colour] + '" />',
+  title: (shape, colours) => {
+    return '<text x="' + n(shape.x) + '" y="' + n(shape.y) + '" font-size="12" fill="' + colours[shape.colour] + '">' + escape(shape.text) + '</text>'
+  },
+  caption: (shape, colours) => {
+    const colour = colours[shape.colour]
+    const lines = shape.lines
+      .map((line, index) => '<tspan x="' + n(shape.x) + '" dy="' + (index === 0 ? 0 : 15) + '">' + escape(line) + '</tspan>')
+      .join('')
+    return '<text x="' + n(shape.x) + '" y="' + n(shape.y + 11) + '" font-size="10" text-anchor="middle" fill="' + colour + '">' + lines + '</text>'
+  },
+}
+
+/** The dash pattern a route's source stated, or nothing for a solid line. */
+function dash(shape: { dashed?: boolean }): string {
+  return shape.dashed === true ? ' stroke-dasharray="4 3"' : ''
+}
+
+interface At {
+  x: number
+  y: number
+}
+
+/**
+ * The marks at an edge's two ends.
+ *
+ * `source`/`sourceNext` give the direction the line leaves the source, and `targetPrev`/`target` the direction it
+ * arrives at the target: the two ends of a polyline run in different directions. An edge with no arrow field keeps
+ * the plain arrow it has always been drawn with. A composition or an aggregation moves the mark to the source; a
+ * dependency and a realisation are told apart by the line, not by the head.
+ */
+function edgeMarks(source: At, sourceNext: At, targetPrev: At, target: At, arrow: EdgeArrow | undefined, stroke: string, background: string): string {
+  if (arrow === 'composition' || arrow === 'aggregation') {
+    return diamond(source, sourceNext, stroke, arrow === 'composition' ? stroke : background)
+  }
+  if (arrow === 'generalization' || arrow === 'realization') {
+    return hollowTriangle(targetPrev, target, stroke, background)
+  }
+  return arrowHead(targetPrev.x, targetPrev.y, target.x, target.y, stroke)
+}
+
+/** The tip and the two base corners of a head that points from `from` to `to`. */
+function tipAndBase(from: At, to: At): { tip: string; left: string; right: string } | undefined {
+  const length = Math.hypot(to.x - from.x, to.y - from.y)
+  if (length < 1) return undefined
+  const ux = (to.x - from.x) / length
+  const uy = (to.y - from.y) / length
+  const size = 7
+  const half = 3.2
+  const baseX = to.x - ux * size
+  const baseY = to.y - uy * size
+  return {
+    tip: n(to.x) + ',' + n(to.y),
+    left: n(baseX - uy * half) + ',' + n(baseY + ux * half),
+    right: n(baseX + uy * half) + ',' + n(baseY - ux * half),
+  }
+}
+
+/** A small filled triangle at the end of a segment, pointing along it. */
+function arrowHead(x1: number, y1: number, x2: number, y2: number, stroke: string): string {
+  const points = tipAndBase({ x: x1, y: y1 }, { x: x2, y: y2 })
+  if (points === undefined) return ''
+  return '<polygon points="' + points.tip + ' ' + points.left + ' ' + points.right + '" fill="' + stroke + '" />'
+}
+
+/** The open triangle a generalisation or a realisation ends in: the surface shows through it. */
+function hollowTriangle(from: At, to: At, stroke: string, background: string): string {
+  const points = tipAndBase(from, to)
+  if (points === undefined) return ''
+  return (
+    '<polygon points="' + points.tip + ' ' + points.left + ' ' + points.right +
+    '" fill="' + background + '" stroke="' + stroke + '" stroke-width="1" />'
+  )
+}
+
+/** The diamond a composition or an aggregation puts at its source, pointing back along the line. */
+function diamond(at: At, next: At, stroke: string, fill: string): string {
+  const length = Math.hypot(next.x - at.x, next.y - at.y)
+  if (length < 1) return ''
+  const ux = (next.x - at.x) / length
+  const uy = (next.y - at.y) / length
+  const size = 12
+  const half = 4
+  const back = { x: at.x + ux * size, y: at.y + uy * size }
+  const middle = { x: at.x + (ux * size) / 2, y: at.y + (uy * size) / 2 }
+  const left = { x: middle.x - uy * half, y: middle.y + ux * half }
+  const right = { x: middle.x + uy * half, y: middle.y - ux * half }
+  const points = [at, left, back, right].map((point) => n(point.x) + ',' + n(point.y)).join(' ')
+  return '<polygon points="' + points + '" fill="' + fill + '" stroke="' + stroke + '" stroke-width="1" />'
+}
+
+/**
+ * An edge label, or nothing when the edge carries no event.
+ *
+ * The text is centred on the point the painter chose - a point on the edge itself - and drawn over a rectangle in
+ * the page colour. The mask is the whole point of drawing it here: it hides the stretch of line behind the text,
+ * so the label interrupts its edge instead of floating beside it, which is the only way a reader can tell that
+ * the word names that line and not something it happens to sit next to. The label keeps its own colour: the mask
+ * is geometry, not emphasis.
+ */
+function edgeLabel(label: string, x: number, y: number, colours: Palette): string {
+  // Total on purpose: a malformed edge must lose its label, not the whole drawing.
+  if (typeof label !== 'string' || label === '') return ''
+  const width = textWidth(label)
+  const left = x - width / 2
+  const top = y - LABEL_HEIGHT / 2
+  // Ten point text sits on a baseline about a third of the mask above its centre, which centres the cap height.
+  const baseline = y + 3.5
+  return (
+    '<rect x="' + n(left) + '" y="' + n(top) + '" width="' + n(width) + '" height="' + n(LABEL_HEIGHT) +
+    '" fill="' + colours.background + '" />' +
+    '<text x="' + n(x) + '" y="' + n(baseline) + '" font-size="10" text-anchor="middle" fill="' + colours.muted + '">' + escape(label) + '</text>'
+  )
+}
+
+export function toSvg(canvas: Canvas, colours: Palette, label?: string): { markup: string; dropped: number } {
+  let dropped = 0
+  const body: string[] = []
+  for (const shape of canvas.shapes) {
+    const writer = writers[shape.kind] as ((shape: Shape, colours: Palette) => string) | undefined
+    if (writer === undefined) {
+      dropped += 1
+      continue
+    }
+    body.push(writer(shape, colours))
+  }
+  const header =
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' + n(canvas.width) + ' ' + n(canvas.height) +
+    '" width="' + n(canvas.width) + '" height="' + n(canvas.height) + '" role="img"' +
+    (label === undefined ? '' : ' aria-label="' + escape(label) + '"') +
+    ' font-family="system-ui, -apple-system, Segoe UI, sans-serif">'
+  // The surface is part of the drawing, not the container's business: a page that paints its own layers - a
+  // wallpaper, a themed panel - would otherwise change the contrast of a picture it knows nothing about.
+  const background =
+    '<rect x="0" y="0" width="' + n(canvas.width) + '" height="' + n(canvas.height) +
+    '" fill="' + colours.background + '" />'
+  return { markup: header + background + body.join('') + '</svg>', dropped }
+}

package/src/render/symbol.ts

@@ -0,0 +1,137 @@
+/**
+ * The geometry of a node's symbol, shared by the module that draws it and the module that attaches edges to it.
+ *
+ * A box is a rectangle, but a symbol is not: the diamond's side midpoints are its vertices, a circle has no side at
+ * all, and a cylinder's top is an arc. Any rule that decides where an edge may meet a node therefore needs the
+ * symbol's own points - and the module that draws the symbol needs the same numbers, or the anchor and the outline
+ * disagree and an edge ends in the air.
+ *
+ * So the arithmetic lives here once: the painter reads a port from it, the writer draws the shape from it, and a
+ * change to a symbol's outline moves both. Pure data and pure functions, no SVG markup.
+ */
+
+import type { Box, Point } from './place.js'
+import type { NodeShape } from './model.js'
+
+/** A cubic Bezier, as the writer draws a curve and the painter reads a point from it. */
+export interface Cubic {
+  from: Point
+  c1: Point
+  c2: Point
+  to: Point
+}
+
+/** Where the two caps of a cylinder start and end, and how deep each one is. */
+export interface CylinderCaps {
+  /** How far the cap reaches into the box: the writer's `min(10, h / 3)`. */
+  cap: number
+  /** The top cap, drawn from its left shoulder to its right shoulder. */
+  top: Cubic
+  /** The bottom cap, drawn from its right shoulder to its left shoulder. */
+  bottom: Cubic
+}
+
+/** A point on a cubic Bezier at parameter `t`, which is what makes "the top of the cap" a shared fact. */
+export function cubicPoint(curve: Cubic, t: number): Point {
+  const u = 1 - t
+  const a = u * u * u
+  const b = 3 * u * u * t
+  const c = 3 * u * t * t
+  const d = t * t * t
+  return {
+    x: a * curve.from.x + b * curve.c1.x + c * curve.c2.x + d * curve.to.x,
+    y: a * curve.from.y + b * curve.c1.y + c * curve.c2.y + d * curve.to.y,
+  }
+}
+
+/**
+ * A diamond's four points, in drawing order: top, right, bottom, left.
+ *
+ * These are the only four places an edge may meet a diamond: each side of the box meets the symbol at exactly that
+ * point, and every other point on the side is in the air inside or outside the outline.
+ */
+export function diamondPoints(box: Box): [Point, Point, Point, Point] {
+  return [
+    { x: box.x + box.width / 2, y: box.y },
+    { x: box.x + box.width, y: box.y + box.height / 2 },
+    { x: box.x + box.width / 2, y: box.y + box.height },
+    { x: box.x, y: box.y + box.height / 2 },
+  ]
+}
+
+/**
+ * Does this symbol meet each of its four sides at exactly one point?
+ *
+ * A diamond's side midpoints are its four vertices, and an ellipse's are its four cardinal points: both offer one legal
+ * port per side and no run to spread along. Every other symbol offers a run on at least one side - a rectangle along
+ * its whole side, a hexagon along the flat between its cut corners, a stadium between its end caps, a cylinder along
+ * its straight flank - so a port there has a place to sit rather than a point to take.
+ *
+ * This is the distinction the painter needs: a node with one legal point per side can give its edges a point each,
+ * and a node with a run can only give them places along it. The two points the discrete shapes offer are the same
+ * four points of the box, which is why one answer serves both.
+ */
+export function hasDiscretePorts(shape: NodeShape | undefined): boolean {
+  return shape === 'diamond' || shape === 'circle'
+}
+
+/** How much of each end of a hexagon the corner cuts away. */
+export function hexagonCut(width: number): number {
+  return Math.min(12, width / 4)
+}
+
+/**
+ * A hexagon's six points, in drawing order: top-left, top-right, right, bottom-right, bottom-left, left.
+ *
+ * The top and bottom are flat runs between the first two and the last two points; the left and right sides are the
+ * single points at index 5 and 2, because the corner cut removed everything else.
+ */
+export function hexagonPoints(box: Box): [Point, Point, Point, Point, Point, Point] {
+  const cut = hexagonCut(box.width)
+  return [
+    { x: box.x + cut, y: box.y },
+    { x: box.x + box.width - cut, y: box.y },
+    { x: box.x + box.width, y: box.y + box.height / 2 },
+    { x: box.x + box.width - cut, y: box.y + box.height },
+    { x: box.x + cut, y: box.y + box.height },
+    { x: box.x, y: box.y + box.height / 2 },
+  ]
+}
+
+/** The radius of a stadium's end caps: half its height, unless the box is narrower than that. */
+export function stadiumRadius(box: Box): number {
+  return Math.min(box.height / 2, box.width / 2)
+}
+
+/**
+ * A cylinder's two caps.
+ *
+ * The writer draws the top cap from the left shoulder to the right shoulder with the box's own top edge as the
+ * control line, and the bottom cap mirrored. The cap curve's apex - the point the painter attaches a top or bottom
+ * port to - is therefore a property of this curve, not a constant: it sits a quarter of the cap's depth inside the
+ * box, not `cap` inside it.
+ */
+export function cylinderCaps(box: Box): CylinderCaps {
+  const cap = Math.min(10, box.height / 3)
+  return {
+    cap,
+    top: {
+      from: { x: box.x, y: box.y + cap },
+      c1: { x: box.x, y: box.y },
+      c2: { x: box.x + box.width, y: box.y },
+      to: { x: box.x + box.width, y: box.y + cap },
+    },
+    bottom: {
+      from: { x: box.x + box.width, y: box.y + box.height - cap },
+      c1: { x: box.x + box.width, y: box.y + box.height },
+      c2: { x: box.x, y: box.y + box.height },
+      to: { x: box.x, y: box.y + box.height - cap },
+    },
+  }
+}
+
+/** The apex of a cylinder's top or bottom cap: the only point on that side an edge meets the outline at. */
+export function cylinderApex(box: Box, side: 'top' | 'bottom'): Point {
+  const caps = cylinderCaps(box)
+  return cubicPoint(side === 'top' ? caps.top : caps.bottom, 0.5)
+}

package/src/render/text.ts

@@ -0,0 +1,86 @@
+/**
+ * Text as the layout sees it: measured, broken into lines, and turned into a box.
+ *
+ * Mermaid and Graphviz both measure a label in the platform's own text engine and then lay out around that
+ * measurement - a node's size is its text plus padding, and a label too long for its maximum width is wrapped
+ * before anything is placed. There is no DOM here, so the measurement is an estimate over a per-character width
+ * table; what matters is that the *order* is the same: text first, geometry second. A renderer that fixes the box
+ * and pours text into it cannot help overflowing.
+ *
+ * Explicit breaks (`<br>`, `<br/>`, `<br />`, a real newline) are honoured as written, because a source that put
+ * one there wanted that line to end.
+ */
+
+/** Average advance per character, in the drawing's units, at the 11px font the writer emits. */
+const CHAR_WIDTH = 6.6
+
+/** A line longer than this wraps on a space, or breaks in the middle when it has none. */
+export const MAX_LINE_CHARS = 30
+
+/** Height of one line of box text, and the breathing room around the block. */
+export const LINE_HEIGHT = 15
+export const TEXT_PADDING = 12
+
+/** The smallest and largest box a label may produce. */
+export const MIN_NODE_WIDTH = 88
+export const MAX_NODE_WIDTH = 260
+
+/** `<br>`, `<br/>`, `<br />` and a real newline all end a line. */
+const BREAK = /<br\s*\/?>|\r?\n/gi
+
+/** The lines a label asks for, before wrapping: an explicit break is a line end, not a space. */
+export function explicitLines(label: string): string[] {
+  return label.split(BREAK).map((line) => line.trim())
+}
+
+/**
+ * Wrap one line to the maximum width.
+ *
+ * A word longer than the limit is broken rather than allowed to overflow: a single token with no spaces is the
+ * common case in identifiers, and letting it run off the box is the defect this function exists to prevent.
+ */
+export function wrapLine(line: string, limit: number = MAX_LINE_CHARS): string[] {
+  if (line === '') return ['']
+  const out: string[] = []
+  let current = ''
+  for (const word of line.split(/\s+/).filter((part) => part !== '')) {
+    const candidate = current === '' ? word : current + ' ' + word
+    if (candidate.length <= limit) {
+      current = candidate
+      continue
+    }
+    if (current !== '') out.push(current)
+    if (word.length <= limit) {
+      current = word
+      continue
+    }
+    let rest = word
+    while (rest.length > limit) {
+      out.push(rest.slice(0, limit))
+      rest = rest.slice(limit)
+    }
+    current = rest
+  }
+  if (current !== '') out.push(current)
+  return out.length === 0 ? [''] : out
+}
+
+export interface Measured {
+  lines: string[]
+  width: number
+  height: number
+}
+
+/** The text block a label produces: its lines, and the box it needs. */
+export function measure(label: string): Measured {
+  const lines = explicitLines(label).flatMap((line) => wrapLine(line))
+  const longest = lines.reduce((max, line) => Math.max(max, line.length), 0)
+  const width = Math.min(MAX_NODE_WIDTH, Math.max(MIN_NODE_WIDTH, longest * CHAR_WIDTH + TEXT_PADDING * 2))
+  const height = lines.length * LINE_HEIGHT + TEXT_PADDING
+  return { lines, width, height }
+}
+
+/** Rough width of a single-line piece of text, for placing an edge label without a box. */
+export function textWidth(text: string): number {
+  return text.length * CHAR_WIDTH
+}