dsh-model-everything 0.5.0 → 0.5.2

package/lib/render/route.js

@@ -0,0 +1,225 @@
+/**
+ * Orthogonal edge routing around boxes.
+ *
+ * A straight line between two boxes is right until a third box sits between them; then it is a line drawn through a
+ * component, which reads as a connection that is not there. Graphviz solves this by routing along a visibility
+ * graph and then fitting splines; ELK, yFiles and mxGraph build a *sparse* grid from the boxes' own edges and run
+ * A* over it with a bend penalty. Sparse is the whole trick: a pixel grid is O(pixels²), while the candidate lines
+ * are the coordinate of every box edge plus a margin - O(boxes) per axis.
+ *
+ * So this module does exactly that, in the two steps those routers use:
+ *
+ * 1. **Candidate lines.** Every box contributes four: one lane just outside each side. Together with the anchor
+ *    coordinates they form the grid a route may travel on.
+ * 2. **A* with bends.** Moving along a candidate line costs its length; changing direction costs extra, because a
+ *    route that zig-zags to save three points is harder to follow than one that goes around.
+ *
+ * A route is only computed for an edge that needs it: the cheap straight segment is tried first, and routing is the
+ * fallback. That keeps the common case - a box directly above another - at two points and no search.
+ *
+ * The layered painter mostly does not ask: an edge between two rows and an edge with a lane are both built from the
+ * channel stage's answer, because a route searched on its own cannot know which lanes the other edges already hold.
+ * What is left for this router is the drawing the layers do not describe - an edge across two wrapped columns, an
+ * edge one of whose ends is a boundary - and the fallback when a channel route would meet a box.
+ */
+/** How far outside a box a lane runs, so a route does not graze the border. */
+const LANE_GAP = 10;
+/** The length of the straight run an edge takes before it is allowed to turn. */
+export const ROUTE_STUB = 16;
+/** The outward normal of a side: the direction an edge leaves along. */
+export function normalOf(side) {
+    switch (side) {
+        case 'top':
+            return { x: 0, y: -1 };
+        case 'bottom':
+            return { x: 0, y: 1 };
+        case 'left':
+            return { x: -1, y: 0 };
+        case 'right':
+            return { x: 1, y: 0 };
+    }
+}
+/** What a bend costs, in points of length: a route prefers one long detour to three small ones. */
+const BEND_COST = 24;
+/** A segment crossing a box at all, with a little slack so a route does not shave a corner. */
+export function crossesBox(x1, y1, x2, y2, box) {
+    const minX = box.x + 0.5;
+    const maxX = box.x + box.width - 0.5;
+    const minY = box.y + 0.5;
+    const maxY = box.y + box.height - 0.5;
+    // Axis-aligned segments are the ones this router emits; test them exactly rather than by sampling.
+    if (Math.abs(y1 - y2) < 0.001) {
+        const y = y1;
+        if (y <= minY || y >= maxY)
+            return false;
+        return Math.max(x1, x2) > minX && Math.min(x1, x2) < maxX;
+    }
+    if (Math.abs(x1 - x2) < 0.001) {
+        const x = x1;
+        if (x <= minX || x >= maxX)
+            return false;
+        return Math.max(y1, y2) > minY && Math.min(y1, y2) < maxY;
+    }
+    // A diagonal (the fallback, and the straight segment): sample it. Cheap, and only ever used for one segment.
+    const steps = Math.max(8, Math.round(Math.hypot(x2 - x1, y2 - y1)));
+    for (let index = 0; index <= steps; index += 1) {
+        const x = x1 + ((x2 - x1) * index) / steps;
+        const y = y1 + ((y2 - y1) * index) / steps;
+        if (x > minX && x < maxX && y > minY && y < maxY)
+            return true;
+    }
+    return false;
+}
+/** The point on a side of a box, in the middle of that side. */
+export function anchor(box, side) {
+    switch (side) {
+        case 'top':
+            return { x: box.x + box.width / 2, y: box.y };
+        case 'bottom':
+            return { x: box.x + box.width / 2, y: box.y + box.height };
+        case 'left':
+            return { x: box.x, y: box.y + box.height / 2 };
+        case 'right':
+            return { x: box.x + box.width, y: box.y + box.height / 2 };
+    }
+}
+/**
+ * Which side of `from` an edge leaves by, and which side of `to` it arrives at.
+ *
+ * The side is a property of the drawing, not of the distance between two centres. A layered drawing puts its boxes
+ * in horizontal rows, and an edge between two rows approaches vertically: out of the bottom, into the top, and the
+ * other way round for an edge drawn against the flow. Only two boxes in the same row are joined sideways, and then
+ * the direction of travel decides which side.
+ *
+ * This replaces the old rule, which compared the two centres' dx and dy and picked the larger axis - so an edge
+ * between two rows left through a box's side as soon as the target was far enough sideways, which is the hook a
+ * top-down drawing is read as a defect.
+ */
+export function approachSides(from, to) {
+    const fromCy = from.y + from.height / 2;
+    const toCy = to.y + to.height / 2;
+    if (Math.abs(toCy - fromCy) > 0.5)
+        return toCy > fromCy ? { exit: 'bottom', entry: 'top' } : { exit: 'top', entry: 'bottom' };
+    const fromCx = from.x + from.width / 2;
+    const toCx = to.x + to.width / 2;
+    return toCx >= fromCx ? { exit: 'right', entry: 'left' } : { exit: 'left', entry: 'right' };
+}
+/** The lane coordinates a route may use: both sides of every obstacle, plus the anchors themselves. */
+function lanes(obstacles, extra) {
+    const values = new Set(extra);
+    for (const box of obstacles) {
+        values.add(box.x - LANE_GAP);
+        values.add(box.x + box.width + LANE_GAP);
+        values.add(box.y - LANE_GAP);
+        values.add(box.y + box.height + LANE_GAP);
+    }
+    return [...values].sort((left, right) => left - right);
+}
+/**
+ * Does this port face away from the box the edge is heading for?
+ *
+ * A side is usually picked from the direction of travel, so its outward normal points at the other box. A discrete
+ * port may break that: when the four points of a diamond are taken, the last edge leaves by the one that is left, and
+ * that side can face the wrong way. The route then has to come back round the box it just left.
+ */
+function facesAway(side, port, other) {
+    const normal = normalOf(side);
+    return normal.x * (other.x + other.width / 2 - port.x) + normal.y * (other.y + other.height / 2 - port.y) < 0;
+}
+export function routeEdge(from, to, obstacles, anchors) {
+    const sides = approachSides(from, to);
+    const exitSide = anchors?.exitSide ?? sides.exit;
+    const entrySide = anchors?.entrySide ?? sides.entry;
+    const exit = anchors?.exit ?? anchor(from, exitSide);
+    const entry = anchors?.entry ?? anchor(to, entrySide);
+    // The stub: an edge leaves square to its side and arrives square at the target's side. Without it a route may
+    // slide sideways out of a box, which is what made the line look like it was glued to whatever box was nearest.
+    const others = obstacles.filter((box) => box !== from && box !== to);
+    // A port that faces away from its target makes the box it belongs to an obstacle of its own: the route has to wrap
+    // round that box, and a search that does not know this cuts straight through it. It is an obstacle only then, so
+    // every route whose sides point the way it travels is decided exactly as it was.
+    const own = [];
+    if (facesAway(exitSide, exit, to))
+        own.push(from);
+    if (facesAway(entrySide, entry, from))
+        own.push(to);
+    const blockers = own.length === 0 ? others : [...others, ...own];
+    // A stub that lands inside another box is no stub: keep the plain anchors and let the search decide.
+    const blockedStub = (point) => blockers.some((box) => point.x > box.x && point.x < box.x + box.width && point.y > box.y && point.y < box.y + box.height);
+    const outNormal = normalOf(exitSide);
+    const inNormal = normalOf(entrySide);
+    let exitStub = { x: exit.x + outNormal.x * ROUTE_STUB, y: exit.y + outNormal.y * ROUTE_STUB };
+    let entryStub = { x: entry.x + inNormal.x * ROUTE_STUB, y: entry.y + inNormal.y * ROUTE_STUB };
+    if (blockedStub(exitStub) || blockedStub(entryStub)) {
+        exitStub = exit;
+        entryStub = entry;
+    }
+    const straight = [exit, exitStub, entryStub, entry];
+    // A straight line is only offered when it is axis-aligned and clear. A diagonal is clear often enough and still
+    // wrong: in a layered drawing it reads as a connection that skips the layers it crosses.
+    const axisAligned = Math.abs(exitStub.x - entryStub.x) < 0.5 || Math.abs(exitStub.y - entryStub.y) < 0.5;
+    if (axisAligned && !blockers.some((box) => crossesBox(exitStub.x, exitStub.y, entryStub.x, entryStub.y, box))) {
+        return { points: simplify(straight), routed: false };
+    }
+    // The grid: one axis is x-lane values, the other y-lane values, and the routes are their intersections.
+    const xs = lanes(blockers, [exitStub.x, entryStub.x]);
+    const ys = lanes(blockers, [exitStub.y, entryStub.y]);
+    const blocked = (x1, y1, x2, y2) => blockers.some((box) => crossesBox(x1, y1, x2, y2, box));
+    const start = { point: exitStub, axis: -1, cost: 0, bends: 0, path: exitStub === exit ? [exit] : [exit, exitStub] };
+    const queue = [start];
+    const best = new Map();
+    const key = (point) => String(Math.round(point.x)) + ',' + String(Math.round(point.y));
+    while (queue.length > 0) {
+        // Small graphs: a linear scan for the cheapest open node is simpler than a heap and just as correct.
+        let index = 0;
+        for (let cursor = 1; cursor < queue.length; cursor += 1)
+            if (queue[cursor].cost < queue[index].cost)
+                index = cursor;
+        const current = queue.splice(index, 1)[0];
+        if (current.cost > (best.get(key(current.point)) ?? Infinity))
+            continue;
+        if (Math.abs(current.point.x - entryStub.x) < 0.5 && Math.abs(current.point.y - entryStub.y) < 0.5) {
+            return { points: simplify([...current.path, entryStub, entry]), routed: true };
+        }
+        const options = [];
+        for (const x of xs)
+            if (Math.abs(x - current.point.x) > 0.5)
+                options.push({ x, y: current.point.y });
+        for (const y of ys)
+            if (Math.abs(y - current.point.y) > 0.5)
+                options.push({ x: current.point.x, y });
+        for (const next of options) {
+            if (blocked(current.point.x, current.point.y, next.x, next.y))
+                continue;
+            const axis = Math.abs(next.y - current.point.y) < 0.5 ? 0 : 1;
+            const bend = current.axis === -1 || current.axis === axis ? 0 : 1;
+            const cost = current.cost + Math.abs(next.x - current.point.x) + Math.abs(next.y - current.point.y) + bend * BEND_COST;
+            const state = key(next);
+            if (cost >= (best.get(state) ?? Infinity))
+                continue;
+            best.set(state, cost);
+            queue.push({ point: next, axis, cost, bends: current.bends + bend, path: [...current.path, next] });
+        }
+    }
+    // Nothing found: the sparse grid connects every box to the lane outside the obstacles, so a search that finds
+    // nothing is a graph this router cannot help. The straight line is still an edge, and drawing it straight is
+    // more honest than dropping it.
+    return { points: simplify(straight), routed: false };
+}
+/** Drop the points in the middle of a straight run: three collinear points are one segment. */
+export function simplify(points) {
+    if (points.length <= 2)
+        return points;
+    const out = [points[0]];
+    for (let index = 1; index < points.length - 1; index += 1) {
+        const previous = out[out.length - 1];
+        const current = points[index];
+        const next = points[index + 1];
+        const collinear = (Math.abs(previous.x - current.x) < 0.5 && Math.abs(current.x - next.x) < 0.5) ||
+            (Math.abs(previous.y - current.y) < 0.5 && Math.abs(current.y - next.y) < 0.5);
+        if (!collinear)
+            out.push(current);
+    }
+    out.push(points[points.length - 1]);
+    return out;
+}

package/lib/render/svg.js

@@ -11,6 +11,24 @@
  *
  * 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, stroke) {
+    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 } from './paint.js';
+import { textWidth } from './text.js';
+import { cylinderCaps, diamondPoints, hexagonPoints, stadiumRadius } from './symbol.js';
 /** One decimal place is enough at any zoom, and it keeps the markup readable. */
 const n = (value) => {
     const rounded = Math.round(value * 10) / 10;
@@ -32,25 +50,63 @@ const writers = {
     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>');
+        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) => n(point.x) + ' ' + n(point.y);
+        const points = (list) => list.map((point) => n(point.x) + ',' + n(point.y)).join(',');
+        const curve = (segment) => ' 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 arrow = arrowHead(shape.x1, shape.y1, shape.x2, shape.y2, stroke);
+        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" />' + arrow + edgeLabel(shape.label, shape.labelX, shape.labelY, colours));
+            '" 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;
-        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));
+        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>';
     },
@@ -59,30 +115,99 @@ const writers = {
         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>';
+        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) {
+    return shape.dashed === true ? ' stroke-dasharray="4 3"' : '';
+}
+/**
+ * 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, sourceNext, targetPrev, target, arrow, stroke, background) {
+    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, to) {
+    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, y1, x2, y2, stroke) {
-    const length = Math.hypot(x2 - x1, y2 - y1);
+    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, to, stroke, background) {
+    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, next, stroke, fill) {
+    const length = Math.hypot(next.x - at.x, next.y - at.y);
     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 + '" />';
+    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. */
+/**
+ * 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, x, y, colours) {
     // 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>';
+    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, colours, label) {
     let dropped = 0;

package/lib/render/symbol.js

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+/** 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, t) {
+    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) {
+    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) {
+    return shape === 'diamond' || shape === 'circle';
+}
+/** How much of each end of a hexagon the corner cuts away. */
+export function hexagonCut(width) {
+    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) {
+    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) {
+    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) {
+    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, side) {
+    const caps = cylinderCaps(box);
+    return cubicPoint(side === 'top' ? caps.top : caps.bottom, 0.5);
+}

package/lib/render/text.js

@@ -0,0 +1,74 @@
+/**
+ * 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) {
+    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, limit = MAX_LINE_CHARS) {
+    if (line === '')
+        return [''];
+    const out = [];
+    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;
+}
+/** The text block a label produces: its lines, and the box it needs. */
+export function measure(label) {
+    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) {
+    return text.length * CHAR_WIDTH;
+}