@meltemi/diagrams-layout 1.9.0 → 1.10.0

package/dist/layout.js

@@ -16,7 +16,7 @@ import { brandFrame } from "./frame.js";
 import { markGradient } from "./mark.js";
 import { strokeDash, } from "./scene.js";
 import { MIN_TEXT_MARGIN, TextMetrics, estimateMeasurer } from "./measure.js";
-import { CORNERED_SHAPES, SHAPE_SIZES, agentHeight, framedLines, isOutlined, onOutline, onPolygon, shapeOutline, shapeTextCenter, shapeTextSpan, shapeTextSpanner, turnPoint, turnedOutline, } from "./shapes.js";
+import { CORNERED_SHAPES, FIXED_TEXT_SHAPES, boundaryToward, SHAPE_SIZES, agentHeight, framedLines, isOutlined, onOutline, onPolygon, shapeOutline, shapeTextCenter, shapeTextBand, shapeTextSpan, shapeTextSpanner, turnPoint, turnedOutline, } from "./shapes.js";
 import { StyleResolver } from "./styles.js";
 import { splitLines } from "./text.js";
 import { DEFAULT_THEME_NAME, THEMES, resolveTheme, } from "./theme.js";
@@ -38,6 +38,8 @@ export const DEFAULT_SIZES = {
     text: null,
     icon: { width: 48, height: 48 },
     image: null,
+    // A free line is the bounding box of its points.
+    line: null,
     // Sequence heads are measured by the sequence layout.
     participant: null,
     actor: null,
@@ -292,6 +294,47 @@ function boundsOf(points) {
     // A straight horizontal or vertical line still has an area to meet.
     return { x: x0 - 1, y: y0 - 1, width: x1 - x0 + 2, height: y1 - y0 + 2 };
 }
+/** A free line's points in order: `from`, its bends, `to`. */
+function linePointsOf(line) {
+    return [line.from, ...line.via, line.to];
+}
+/** The box of a free line: the bounding box of its points, at least 1 wide and 1 tall. */
+function lineBox(points) {
+    const xs = points.map((p) => p.x);
+    const ys = points.map((p) => p.y);
+    const x = Math.min(...xs);
+    const y = Math.min(...ys);
+    return {
+        x,
+        y,
+        width: Math.max(1, Math.max(...xs) - x),
+        height: Math.max(1, Math.max(...ys) - y),
+    };
+}
+/** The side whose normal points most nearly from `from` towards `to`. */
+function sideToward(from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    if (Math.abs(dx) >= Math.abs(dy))
+        return dx >= 0 ? "east" : "west";
+    return dy >= 0 ? "south" : "north";
+}
+/**
+ * A free line's points with an elbow between consecutive points that differ on both axes, each
+ * leg leaving along the axis of the longer displacement: every segment horizontal or vertical.
+ */
+function orthogonalThrough(points) {
+    const out = [points[0]];
+    for (let i = 1; i < points.length; i++) {
+        const a = points[i - 1];
+        const b = points[i];
+        if (a.x !== b.x && a.y !== b.y) {
+            out.push(Math.abs(b.x - a.x) >= Math.abs(b.y - a.y) ? { x: b.x, y: a.y } : { x: a.x, y: b.y });
+        }
+        out.push(b);
+    }
+    return out;
+}
 const SIDES = ["north", "east", "south", "west"];
 const overlaps = (a, b) => Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x) > 0.5 &&
     Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y) > 0.5;
@@ -528,6 +571,7 @@ function iconDiagnostics(diagram, styles, sizing, lines, words, themeRange) {
             }
         }
     }
+    out.push(...verticalAlignDiagnostics(diagram, styles, sizing, lines, words, themeRange));
     for (const { range, element, used, placed, inherited } of labels.values()) {
         if (used)
             continue;
@@ -550,6 +594,68 @@ function iconDiagnostics(diagram, styles, sizing, lines, words, themeRange) {
     }
     return out;
 }
+/**
+ * `layout.vertical-align-ignored` for a `verticalAlign` that no element it styles uses: a box whose
+ * shape draws its text at a fixed spot, a box whose icon is the centre piece (its label band is at
+ * `labelPosition`), or an element that is no box. Once per statement that writes the property, or
+ * once for a theme rule or class, on the diagram's `theme` (`themeRange`).
+ */
+function verticalAlignDiagnostics(diagram, styles, sizing, lines, words, themeRange) {
+    const sources = new Map();
+    for (const element of diagram.elements) {
+        if (styles.element(element).verticalAlign === undefined)
+            continue;
+        const source = styleSource(diagram, element, "verticalAlign", lines, styles);
+        const box = element.kind === "box";
+        const fixed = box && FIXED_TEXT_SHAPES.has(sizing.shapeOf(element));
+        const centred = box && !fixed && sizing.centred(element);
+        const used = box && !fixed && !centred;
+        const why = used
+            ? undefined
+            : fixed
+                ? "fixed"
+                : centred
+                    ? "centred"
+                    : "notBox";
+        const known = sources.get(source.key);
+        if (known) {
+            known.used ||= used;
+            if (why)
+                known.why.add(why);
+        }
+        else {
+            sources.set(source.key, {
+                range: source.inherited ? themeRange : source.range,
+                element: element.id,
+                used,
+                why: new Set(why ? [why] : []),
+                inherited: source.inherited,
+            });
+        }
+    }
+    const out = [];
+    for (const { range, element, used, why, inherited } of sources.values()) {
+        if (used)
+            continue;
+        out.push({
+            code: "layout.vertical-align-ignored",
+            severity: "warning",
+            message: inherited
+                ? words.diagnostics.verticalAlignIgnoredByTheme(element)
+                : words.diagnostics.verticalAlignIgnored(element),
+            range,
+            hints: [
+                why.has("fixed")
+                    ? words.hints.verticalAlignFixedShape
+                    : why.has("centred")
+                        ? words.hints.verticalAlignCentredIcon
+                        : words.hints.verticalAlignNeverUsed,
+            ],
+            data: { ids: [element] },
+        });
+    }
+    return out;
+}
 /** Lays out one compiled diagram into a scene. */
 function layoutDrawing(compilation, diagram, options = {}) {
     const diagnostics = [];
@@ -605,6 +711,15 @@ function layoutDrawing(compilation, diagram, options = {}) {
                 break;
         }
     }
+    // Free lines: the bounding box of the points written in their statement is their place and
+    // size, in their parent's interior coordinates, so a group derives its size from them as from
+    // its boxes; the drawn points are found once the groups are placed.
+    const freeLines = diagram.elements.filter((e) => e.kind === "line" && e.line !== null);
+    for (const line of freeLines) {
+        const box = lineBox(linePointsOf(line.line));
+        places.set(line.id, boxCenter(box));
+        sizes.set(line.id, { width: box.width, height: box.height });
+    }
     const mode = options.layout ?? diagram.properties.layout;
     const free = diagram.type === "free";
     const unplaced = diagram.elements.filter((e) => e.kind !== "group" && !places.has(e.id));
@@ -706,8 +821,9 @@ function layoutDrawing(compilation, diagram, options = {}) {
             continue;
         const explicit = sizes.get(element.id);
         const size = explicit ?? sizing.defaultSize(element);
-        if (explicit)
-            sizing.checkOverflow(element, explicit, sizeEntries.get(element.id), diagnostics);
+        const entry = sizeEntries.get(element.id);
+        if (explicit && entry)
+            sizing.checkOverflow(element, explicit, entry, diagnostics);
         elementSizes.set(element.id, size);
     }
     // Turned elements: their angle, clockwise; 0 and 360 draw upright.
@@ -972,6 +1088,24 @@ function layoutDrawing(compilation, diagram, options = {}) {
             }
         }
     }
+    // Free lines: their written points moved by their parent's interior origin, in diagram
+    // coordinates; their box is the bounding box of those points.
+    const lineAnchors = new Map();
+    for (const line of freeLines) {
+        const origin = origins.get(line.id) ?? { x: 0, y: 0 };
+        const points = linePointsOf(line.line).map((p) => ({ x: p.x + origin.x, y: p.y + origin.y }));
+        lineAnchors.set(line.id, points);
+        boxes.set(line.id, lineBox(points));
+        if (points.every((p) => p.x === points[0].x && p.y === points[0].y)) {
+            diagnostics.push({
+                code: "layout.degenerate-line",
+                severity: "warning",
+                message: words.diagnostics.degenerateLine(line.id),
+                range: line.range,
+                hints: [words.hints.lineEnds],
+            });
+        }
+    }
     // The drawn shape of every element box, and the outline of those that are not their box; a
     // turned element's outline is turned, and its drawn box is the bounding box of that outline.
     const shapes = new Map();
@@ -979,7 +1113,7 @@ function layoutDrawing(compilation, diagram, options = {}) {
     const turnedBoxes = new Map();
     for (const element of diagram.elements) {
         const box = boxes.get(element.id);
-        if (element.kind === "group" || !box)
+        if (element.kind === "group" || element.kind === "line" || !box)
             continue;
         const shape = element.kind === "tag" ? "pill" : sizing.shapeOf(element);
         shapes.set(element.id, shape);
@@ -1014,7 +1148,7 @@ function layoutDrawing(compilation, diagram, options = {}) {
      * The boxes a connector should not cross: the other shapes of its layer, but not its ends, the
      * groups that hold them, nor a shape that contains an end box (a box it is stacked inside).
      */
-    const shapeIds = diagram.elements.filter((e) => e.kind !== "group" && e.kind !== "tag");
+    const shapeIds = diagram.elements.filter((e) => e.kind !== "group" && e.kind !== "tag" && e.kind !== "line");
     const obstaclesFor = (relation) => {
         const ends = [relation.from, relation.to];
         const holders = new Set(ends.flatMap((id) => [id, ...(diagram.elementsById.get(id)?.groupPath ?? [])]));
@@ -1155,10 +1289,10 @@ function layoutDrawing(compilation, diagram, options = {}) {
         else {
             points = shapeRoute(kind, anchors.points, { first: anchors.points[0], last: anchors.points[anchors.points.length - 1], via }, anchors.fromSide, anchors.toSide);
         }
-        // The target's head is the style's or the theme's; the source's is the style's, else the
-        // target's for a two-way arrow, else none.
-        const endKind = style.arrowhead ?? theme.arrowhead;
-        const startKind = style.arrowtail ?? (relation.twoWay ? endKind : "none");
+        // The target's head is the style's, else none for a line (`--`, `---`), else the theme's; the
+        // source's is the style's, else the target's for a two-way arrow, else none.
+        const endKind = style.arrowhead ?? (relation.heads === "none" ? "none" : theme.arrowhead);
+        const startKind = style.arrowtail ?? (relation.heads === "both" ? endKind : "none");
         const headWidth = (theme.arrowSize * 7) / 8;
         // The labels icon shapes draw beside their ends: a connector passes under its own end's label
         // only straight from the icon and on beyond it, far enough for its head; elsewhere the label
@@ -1291,9 +1425,79 @@ function layoutDrawing(compilation, diagram, options = {}) {
         };
         return { relation, line, start: startHead, end: endHead, label, curve, connector };
     });
+    // Free lines: connectors without ends, routed through their own points (`polyline` unless a
+    // route kind is written; `auto` is `polyline`, there being no box to anchor to), with no lanes,
+    // detours or gaps, their heads `none` unless written, and a pill as a relation's.
+    const lineGeometry = new Map();
+    for (const element of freeLines) {
+        const anchors = lineAnchors.get(element.id);
+        const style = styles.element(element);
+        const written = style.routing ?? "polyline";
+        const kind = written === "auto" ? "polyline" : written;
+        const points = kind === "orthogonal" ? orthogonalThrough(anchors) : [...anchors];
+        const last = points.length - 1;
+        const fromSide = sideToward(points[0], points[Math.min(1, last)]);
+        const toSide = sideToward(points[last], points[Math.max(0, last - 1)]);
+        const endKind = style.arrowhead ?? "none";
+        const startKind = style.arrowtail ?? "none";
+        const headWidth = (theme.arrowSize * 7) / 8;
+        let line;
+        let start;
+        let end;
+        let curve;
+        if (kind === "bezier" && points.length > 1) {
+            const approach = (tip, side) => {
+                const normal = sideNormal(side);
+                return [{ x: tip.x + normal.x * 10, y: tip.y + normal.y * 10 }, tip];
+            };
+            const atEnd = endMarker(approach(points[last], toSide), endKind, theme.arrowSize, headWidth);
+            const atStart = endMarker(approach(points[0], fromSide), startKind, theme.arrowSize, headWidth);
+            const bezier = bezierThrough(points, fromSide, toSide, atEnd.line[atEnd.line.length - 1], atStart.line[atStart.line.length - 1]);
+            line = bezier.samples;
+            start = atStart.parts;
+            end = atEnd.parts;
+            curve = bezier.d;
+        }
+        else {
+            const ends = relationEnds(points, startKind, endKind, theme.arrowSize, headWidth);
+            line =
+                (style.corners ?? theme.corners) === "rounded"
+                    ? roundCorners(ends.line, CORNER_RADIUS)
+                    : ends.line;
+            start = ends.start;
+            end = ends.end;
+        }
+        let label;
+        const icon = sizing.lineIcon(element);
+        if (element.label !== "" || icon) {
+            const entry = labels.get(element.id);
+            const at = entry ? entry.at / 100 : 0.5;
+            const offset = entry ? entry.offset : { x: 0, y: 0 };
+            const center = pointAlong(curve ? line : points, at);
+            const text = element.label;
+            const textWidth = text === "" ? 0 : metrics.width(text, "body", 500, scale.relationLabel);
+            const iconWidth = icon ? icon.size + (text === "" ? 0 : icon.gap) : 0;
+            const width = textWidth + iconWidth + scale.relationLabelPadding;
+            label = {
+                box: boxFromCenter({ x: center.x + offset.x, y: center.y + offset.y }, Math.max(width, scale.relationLabelHeight), scale.relationLabelHeight),
+                text,
+            };
+        }
+        lineGeometry.set(element.id, {
+            element,
+            line,
+            start,
+            end,
+            label,
+            curve,
+            connector: { points, line, fromSide, toSide, via: anchors.slice(1, -1) },
+        });
+    }
     // Every element's box with the label it draws outside it, in diagram coordinates.
     const extents = new Map([...boxes].map(([id, box]) => [id, extentAt(id, box)]));
-    placeLabels(relationGeometry, movable, labelObstacles(diagram, extents, sizing));
+    // A line's box is no obstacle: labels may sit beside it as beside any connector.
+    const shapeExtents = new Map([...extents].filter(([id]) => !lineGeometry.has(id)));
+    placeLabels(relationGeometry, movable, labelObstacles(diagram, shapeExtents, sizing));
     const elementLabels = new Map();
     for (const [id, box] of boxes) {
         const label = labelAt(id, box);
@@ -1306,6 +1510,9 @@ function layoutDrawing(compilation, diagram, options = {}) {
     for (const [id, box] of boxes)
         if (!rotations.has(id))
             checked.set(id, box);
+    // Lines cross boxes by design: they take no part in the composition checks.
+    for (const id of lineGeometry.keys())
+        checked.delete(id);
     diagnostics.push(...checkComposition(diagram, checked, relationGeometry.map((g) => ({
         relation: g.relation,
         points: g.line,
@@ -1323,6 +1530,12 @@ function layoutDrawing(compilation, diagram, options = {}) {
         if (geometry.label)
             everything.push(geometry.label.box);
     }
+    for (const geometry of lineGeometry.values()) {
+        for (const p of [...markerPoints(geometry.start), ...markerPoints(geometry.end)])
+            everything.push({ x: p.x, y: p.y, width: 0, height: 0 });
+        if (geometry.label)
+            everything.push(geometry.label.box);
+    }
     const bounds = unionBoxes(everything) ?? { x: 0, y: 0, width: 0, height: 0 };
     const margin = theme.margin;
     const contentWidth = Math.ceil(bounds.width + 2 * margin);
@@ -1367,6 +1580,49 @@ function layoutDrawing(compilation, diagram, options = {}) {
         const c = boxCenter(box);
         return { ...group, transform: `rotate(${round(degrees)} ${round(c.x)} ${round(c.y)})` };
     };
+    /**
+     * An attached note's leader: a dotted polyline from where the segment between the two boxes'
+     * centres leaves the note to where it enters its element's outline (turned with the element),
+     * the last item of the note's group. None when the target is not drawn or the boxes overlap. A
+     * turned note's group turns its items, so the leader is written in the note's own frame.
+     */
+    const withLeader = (group, element, box) => {
+        const targetId = element.attachedTo;
+        const target = targetId === null ? undefined : diagram.elementsById.get(targetId);
+        const placed = target && target.id !== element.id ? boxes.get(target.id) : undefined;
+        if (!target || !placed)
+            return group;
+        const targetBox = shift(placed);
+        const overlaps = box.x < targetBox.x + targetBox.width &&
+            targetBox.x < box.x + box.width &&
+            box.y < targetBox.y + targetBox.height &&
+            targetBox.y < box.y + box.height;
+        if (overlaps)
+            return group;
+        const own = rotations.get(element.id) ?? 0;
+        const turnedTarget = rotations.get(target.id) ?? 0;
+        const shapeOf = (e) => e.kind === "tag" ? "pill" : e.kind === "group" ? "rectangle" : sizing.shapeOf(e);
+        const centres = { note: boxCenter(box), target: boxCenter(targetBox) };
+        const from = boundaryToward("rectangle", box, own, centres.target);
+        const to = boundaryToward(shapeOf(target), targetBox, turnedTarget, centres.note, sizing.shapeOptions(target));
+        const local = (p) => (own === 0 ? p : turnPoint(p, centres.note, -own));
+        const leader = {
+            kind: "polyline",
+            points: [from, to].map(local).map((p) => ({ x: round(p.x), y: round(p.y) })),
+            stroke: theme.muted,
+            strokeWidth: theme.strokeWidth,
+            dashed: "dotted",
+            className: "leader",
+        };
+        return { ...group, items: [...group.items, leader] };
+    };
+    /** An element's drawing, turned when it is, with the leader of a note attached to something. */
+    const elementGroup = (element, box) => {
+        const drawn = turn(emitter.element(element, box), box);
+        return element.kind === "note" && element.attachedTo !== null
+            ? withLeader(drawn, element, box)
+            : drawn;
+    };
     if (free) {
         const byKey = new Map(relationGeometry.map((g) => [g.relation.key, g]));
         for (const paintable of paintOrder(diagram)) {
@@ -1377,9 +1633,14 @@ function layoutDrawing(compilation, diagram, options = {}) {
                 continue;
             }
             const box = shift(boxes.get(paintable.element.id));
+            const line = lineGeometry.get(paintable.element.id);
+            if (line) {
+                items.push(onLayer(emitter.line(line.element, box, line.line.map(shiftPoint), shiftMarker(line.start, shiftPoint), shiftMarker(line.end, shiftPoint), line.label ? { box: shift(line.label.box), text: line.label.text } : undefined, line.curve ? translatePath(line.curve, dx, dy) : undefined), paintable.element.layer));
+                continue;
+            }
             items.push(onLayer(paintable.kind === "group"
                 ? emitter.group(paintable.element, box)
-                : turn(emitter.element(paintable.element, box), box), paintable.element.layer));
+                : elementGroup(paintable.element, box), paintable.element.layer));
         }
     }
     else {
@@ -1402,7 +1663,7 @@ function layoutDrawing(compilation, diagram, options = {}) {
                 if (element.kind === "group" || element.kind === "tag" || indexOf(element.layer) !== layer)
                     continue;
                 const box = shift(boxes.get(element.id));
-                items.push(onLayer(turn(emitter.element(element, box), box), element.layer));
+                items.push(onLayer(elementGroup(element, box), element.layer));
             }
             for (const geometry of relationGeometry) {
                 if (indexOf(geometry.relation.layer) !== layer)
@@ -1442,6 +1703,7 @@ function layoutDrawing(compilation, diagram, options = {}) {
         gradients: [...gradients, ...emitter.painter.gradients],
         patterns: emitter.patterns,
         items,
+        ...(theme.sketch !== "none" ? { sketch: theme.sketch } : {}),
     };
     const labelBoxes = new Map();
     const connectors = new Map();
@@ -1450,6 +1712,12 @@ function layoutDrawing(compilation, diagram, options = {}) {
             labelBoxes.set(geometry.relation.key, geometry.label.box);
         connectors.set(geometry.relation.key, geometry.connector);
     }
+    // Free lines by their id, beside the relations: their pill and their route.
+    for (const [id, geometry] of lineGeometry) {
+        if (geometry.label)
+            labelBoxes.set(id, geometry.label.box);
+        connectors.set(id, geometry.connector);
+    }
     return {
         scene,
         diagnostics,
@@ -1541,6 +1809,14 @@ function ownLabelCrossings(points, labels, rooms, straight) {
     const route = beyondOwnLabels(points, labels, rooms, straight);
     return labels.filter((label) => label && crossedBoxes(route, [label.box]).length > 0).length;
 }
+/** Points rounded as the scene writes them. */
+function roundedPoints(list) {
+    return list.map((p) => ({ x: round(p.x), y: round(p.y) }));
+}
+/** A circle of radius `r` about (`cx`, `cy`), as path data. */
+function circlePath(cx, cy, r) {
+    return `M${cx - r} ${cy}a${r} ${r} 0 1 0 ${2 * r} 0a${r} ${r} 0 1 0 ${-2 * r} 0Z`;
+}
 function round(value) {
     return Math.round(value * 100) / 100;
 }
@@ -1691,8 +1967,36 @@ function arrangeRequest(diagram, sizes, fixedPlaces, routes, theme, headerOf, la
             },
         ];
     });
+    // An attached note is arranged beside its element as a dashed relation from the element would
+    // be (the element first, so the note follows it in the flow's direction): in `auto`, and for a
+    // note that has no place in `assisted`. The leader is no relation, so the route the engine
+    // answers for this edge is never read.
+    const attached = diagram.elements.flatMap((note) => {
+        const target = note.attachedTo;
+        if (note.kind !== "note" || target === null || target === note.id)
+            return [];
+        if (fixedPlaces.has(note.id) || leftOut.has(note.id) || leftOut.has(target))
+            return [];
+        const element = diagram.elementsById.get(target);
+        if (!element || element.kind === "line" || !sizes.has(target) || !sizes.has(note.id)) {
+            return [];
+        }
+        return [
+            {
+                id: `attach${note.id}`,
+                source: target,
+                target: note.id,
+                sourcePort: null,
+                targetPort: null,
+                primary: false,
+                label: null,
+            },
+        ];
+    });
+    edges.push(...attached);
+    // Free lines are drawn where their points are written: the engine never moves them.
     const nodes = diagram.elements
-        .filter((e) => e.kind !== "group")
+        .filter((e) => e.kind !== "group" && e.kind !== "line")
         .map((element) => {
         const ports = element.ports.map((p) => ({
             id: p.name,
@@ -2061,6 +2365,8 @@ class Sizing {
     centredSizes = new Map();
     centredLayouts = new Map();
     centredLays = new Map();
+    /** The centre of each aligned text block, by element and box. */
+    textCenters = new Map();
     constructor(theme, scale, metrics, styles, icons, images, 
     /** The written `size` of each element that has one. */
     written = new Map()) {
@@ -2122,6 +2428,62 @@ class Sizing {
         }
         return written === undefined ? {} : { radius: written };
     }
+    /**
+     * Where `verticalAlign` moves the text block of an element: `top` or `bottom` on a free box whose
+     * shape has a text band and whose icon is not centred (its band sits at `labelPosition`), else
+     * undefined, and the block stays at the shape's text centre.
+     */
+    verticalAlignOf(element) {
+        if (element.kind !== "box")
+            return undefined;
+        const written = this.styles.element(element).verticalAlign;
+        if (written !== "top" && written !== "bottom")
+            return undefined;
+        if (FIXED_TEXT_SHAPES.has(this.shapeOf(element)) || this.centred(element))
+            return undefined;
+        return written;
+    }
+    /**
+     * The centre of an element's text block drawn in `box`: the shape's text centre, or with
+     * `verticalAlign top` the first row band of the shape's text band, `padding` below its top edge,
+     * whose span about the centre holds the block with the padding on each side (or as much as the
+     * middle does), searched pixel by pixel towards the middle; `bottom` the same from the bottom
+     * edge. A block that no band holds before the middle stays at the middle.
+     */
+    textCenter(element, box) {
+        const shape = this.shapeOf(element);
+        const options = this.shapeOptions(element);
+        const center = shapeTextCenter(shape, box, options);
+        const align = this.verticalAlignOf(element);
+        if (!align)
+            return center;
+        const key = `${element.id}\u0000${box.x}\u0000${box.y}\u0000${box.width}\u0000${box.height}`;
+        const known = this.textCenters.get(key);
+        if (known)
+            return known;
+        const column = this.textColumn(element);
+        const spanOf = shapeTextSpanner(shape, box, options);
+        const band = shapeTextBand(shape, box, options);
+        const padding = this.theme.padding;
+        const widthAt = (y) => {
+            const span = spanOf(y + column.slots.top, y + column.slots.bottom, center.x);
+            return span ? 2 * Math.max(0, Math.min(center.x - span[0], span[1] - center.x)) : -1;
+        };
+        const need = Math.min(column.width + 2 * padding, Math.max(0, widthAt(center.y)));
+        const direction = align === "top" ? 1 : -1;
+        const start = align === "top"
+            ? band.top + padding - column.slots.top
+            : band.bottom - padding - column.slots.bottom;
+        let found = center;
+        for (let y = start; (center.y - y) * direction > 1e-9; y += direction) {
+            if (widthAt(y) >= need - 1e-9) {
+                found = { x: center.x, y };
+                break;
+            }
+        }
+        this.textCenters.set(key, found);
+        return found;
+    }
     /**
      * The rows the text column of a box-like element covers, from its text centre: the slots of its
      * lines and icon, and the same rows with room for the glyphs' descenders. `width` is the widest
@@ -2171,12 +2533,13 @@ class Sizing {
      * aligned text may lie. The glyph rows count as clipped only where the shape reaches more than
      * `ROW_TOLERANCE` into them.
      */
-    textArea(element, box, rows, column = this.textColumn(element), centred = true) {
+    textArea(element, box, rows, column = this.textColumn(element), centred = true, aligned = true) {
         const shape = this.shapeOf(element);
         if (FULL_WIDTH_TEXT.has(shape))
             return box;
         const options = this.shapeOptions(element);
-        const center = shapeTextCenter(shape, box, options);
+        // Where the block is drawn; the sizes of boxes are found about the middle.
+        const center = aligned ? this.textCenter(element, box) : shapeTextCenter(shape, box, options);
         const top = center.y + column[rows].top;
         const bottom = center.y + column[rows].bottom;
         const inset = rows === "glyphs" ? Math.min(ROW_TOLERANCE, (bottom - top) / 2) : 0;
@@ -2214,7 +2577,8 @@ class Sizing {
     widthAt(element, height, margin, rows) {
         const column = this.textColumn(element);
         const need = column.width + 2 * margin;
-        const fits = (width) => this.textArea(element, { x: 0, y: 0, width, height }, rows, column).width >= need - 1e-9;
+        const fits = (width) => this.textArea(element, { x: 0, y: 0, width, height }, rows, column, true, false).width >=
+            need - 1e-9;
         let low = Math.max(1, need);
         if (fits(low))
             return Math.ceil(low - ROUNDING);
@@ -2242,9 +2606,23 @@ class Sizing {
         return groupHeaderOf(group, this.styles.element(group), this.theme);
     }
     /** Horizontal alignment of a box or text label. */
+    /**
+     * A note's font: the theme's note size at weight 400, or a free note's `fontSize` and
+     * `fontWeight`; its lines are as far apart as the note scale's ratio of line to size.
+     */
+    noteFont(element) {
+        const style = this.styles.element(element);
+        const size = style.fontSize ?? this.scale.note;
+        return {
+            size,
+            weight: style.fontWeight ?? 400,
+            line: Math.round((size * this.scale.noteLine) / this.scale.note),
+        };
+    }
     alignOf(element) {
-        if (element.kind === "text")
+        if (element.kind === "text" || element.kind === "note") {
             return this.styles.element(element).textAlign ?? "left";
+        }
         if (element.kind === "box")
             return this.styles.element(element).textAlign ?? "center";
         return "center";
@@ -2297,7 +2675,7 @@ class Sizing {
             case "tag":
                 return this.place(style.icon, Math.round(scale.tag * 1.3), "left");
             case "note":
-                return this.place(style.icon, Math.round(scale.note * 1.3), "left");
+                return this.place(style.icon, Math.round(this.noteFont(element).size * 1.3), "left");
         }
         const icon = this.elementIcon(element);
         if (!icon)
@@ -2375,7 +2753,7 @@ class Sizing {
         const box = { x: 0, y: 0, ...size };
         if (!this.rowsFit(element, box, slots))
             return false;
-        const area = this.textArea(element, box, "slots", { ...column, slots });
+        const area = this.textArea(element, box, "slots", { ...column, slots }, true, false);
         return area.width >= column.width + 2 * margin - 1e-9;
     }
     /** Whether rows about an element's text centre lie inside the text area of its shape in `box`. */
@@ -2691,6 +3069,10 @@ class Sizing {
     relationIcon(relation) {
         return this.place(this.styles.relation(relation).icon, Math.round(this.scale.relationLabel * 1.3), "left");
     }
+    /** The icon of a free line's pill, as a relation's pill takes it. */
+    lineIcon(line) {
+        return this.place(this.styles.element(line).icon, Math.round(this.scale.relationLabel * 1.3), "left");
+    }
     /**
      * Label and description positions of a box, with the icon above or below them when it sits
      * there. The label is broken at `\n` into lines `line` apart; a one-line label sits where it
@@ -2784,9 +3166,10 @@ class Sizing {
                 };
             }
             case "note": {
+                const font = this.noteFont(element);
                 const best = widest(splitLines(element.label).map((line) => ({
                     text: line,
-                    width: metrics.width(line, "body", 400, scale.note),
+                    width: metrics.width(line, "body", font.weight, font.size),
                 })));
                 const width = Math.ceil(Math.max(best.width + beside, 1));
                 return { text: best.text, width, minimum: width };
@@ -2856,7 +3239,7 @@ class Sizing {
             case "note":
                 return {
                     width: needs.width,
-                    height: splitLines(element.label).length * scale.noteLine + 4,
+                    height: splitLines(element.label).length * this.noteFont(element).line + 4,
                 };
             case "text":
                 return {
@@ -3340,7 +3723,8 @@ class Emitter {
             this.lines(items, element, x, band.y - column.slots.top, this.sizing.plainBlock(element), align);
             return { kind: "group", id: element.id, role: "element", items };
         }
-        const textCenter = shapeTextCenter(shape, box, this.sizing.shapeOptions(element));
+        // At the shape's text centre, or where `verticalAlign` moves the block.
+        const textCenter = this.sizing.textCenter(element, box);
         const block = this.sizing.textBlock(element);
         // Aligned text keeps the padding inside the shape's text area.
         const area = this.sizing.textArea(element, box, "slots");
@@ -3422,7 +3806,7 @@ class Emitter {
         return { kind: "group", id: element.id, role: "element", items };
     }
     note(element, box) {
-        const { theme, scale } = this;
+        const { theme } = this;
         const style = this.styles.element(element);
         const items = [];
         if (style.fill || style.stroke || style.pattern) {
@@ -3430,13 +3814,22 @@ class Emitter {
             items.push(outline, ...this.overlay(style, outline));
         }
         const color = style.color ?? theme.muted;
+        const font = this.sizing.noteFont(element);
         const icon = this.sizing.iconOf(element);
         const indent = icon ? icon.size + icon.gap : 0;
         if (icon) {
-            items.push(this.icon(icon, box.x + icon.size / 2, box.y + scale.noteLine / 2, style.iconColor ?? color));
+            items.push(this.icon(icon, box.x + icon.size / 2, box.y + font.line / 2, style.iconColor ?? color));
         }
+        // The lines are aligned in the room right of the icon: at its edge, its middle or the box's.
+        const align = this.sizing.alignOf(element);
+        const x = align === "left"
+            ? box.x + indent
+            : align === "right"
+                ? box.x + box.width
+                : box.x + indent + (box.width - indent) / 2;
+        const anchor = align === "left" ? "start" : align === "right" ? "end" : "middle";
         splitLines(element.label).forEach((line, i) => {
-            items.push(this.text(box.x + indent, box.y + scale.noteLine / 2 + i * scale.noteLine, line, scale.note, 400, color, "start"));
+            items.push(this.text(x, box.y + font.line / 2 + i * font.line, line, font.size, font.weight, color, anchor));
         });
         return { kind: "group", id: element.id, role: "element", items };
     }
@@ -3462,25 +3855,55 @@ class Emitter {
         return { kind: "group", id: element.id, role: "element", items };
     }
     relation(relation, line, start, end, label, curve) {
-        const { theme, scale } = this;
         const style = this.styles.relation(relation);
         // An assumption is drawn dashed in the muted colour until a style says otherwise.
         const assumed = relation.assumption !== null;
-        const stroke = style.stroke ?? (assumed ? theme.muted : theme.connector);
-        const strokeWidth = style.width ?? theme.connectorWidth;
-        const dashed = strokeDash(style.line ?? (assumed ? "dashed" : relation.line));
-        const points = (list) => list.map((p) => ({ x: round(p.x), y: round(p.y) }));
         // A straight connector passes under the titles of groups it crosses (not its own ends'). It
         // is drawn from beyond the labels its own ends draw outside their boxes (see `underLabel`).
         const holes = this.titles
             .filter((t) => t.id !== relation.from && t.id !== relation.to)
             .map((t) => t.box);
+        const items = this.connectorItems(relation.key, style, style.stroke ?? (assumed ? this.theme.muted : this.theme.connector), strokeDash(style.line ?? (assumed ? "dashed" : relation.line)), holes, line, start, end, label, this.sizing.relationIcon(relation), curve);
+        return { kind: "group", id: relation.key, role: "relation", items, track: roundedPoints(line) };
+    }
+    /**
+     * A free line: a connector without ends, drawn as a relation is (its line, its heads, its pill),
+     * as an element group whose `track` is its drawn line and whose `bounds` is its box. A line whose
+     * points coincide is a dot of its width.
+     */
+    line(element, box, line, start, end, label, curve) {
+        const style = this.styles.element(element);
+        const stroke = style.stroke ?? this.theme.connector;
+        const strokeWidth = style.width ?? this.theme.connectorWidth;
+        const first = line[0];
+        const dot = first !== undefined && line.every((p) => p.x === first.x && p.y === first.y);
+        const items = dot
+            ? [
+                {
+                    kind: "path",
+                    d: circlePath(round(first.x), round(first.y), Math.max(1, strokeWidth)),
+                    fill: stroke,
+                    stroke: "none",
+                    strokeWidth: 0,
+                    dashed: false,
+                },
+            ]
+            : this.connectorItems(element.id, style, stroke, strokeDash(style.line ?? "solid"), [], line, start, end, label && { ...label, technology: null }, this.sizing.lineIcon(element), curve);
+        return withBounds({ kind: "group", id: element.id, role: "element", items, track: roundedPoints(line) }, box);
+    }
+    /**
+     * The items of a connector, in the order motion and hit tests expect: its line (pieces around
+     * `holes`, or one curve), its heads, then its label pill with its icon and text.
+     */
+    connectorItems(id, style, stroke, dashed, holes, line, start, end, label, icon, curve) {
+        const { theme, scale } = this;
+        const strokeWidth = style.width ?? theme.connectorWidth;
         const pieces = curve ? [] : splitAround(line, holes);
         const items = curve
             ? [{ kind: "path", d: curve, fill: "none", stroke, strokeWidth, dashed }]
             : pieces.map((piece) => ({
                 kind: "polyline",
-                points: points(piece),
+                points: roundedPoints(piece),
                 stroke,
                 strokeWidth,
                 dashed,
@@ -3498,7 +3921,6 @@ class Emitter {
             const pill = [
                 this.rect(label.box, Math.min(label.box.height, scale.relationLabelHeight) / 2, fill, style.stroke ?? (style.fill ? style.fill : theme.line), theme.strokeWidth, false),
             ];
-            const icon = this.sizing.relationIcon(relation);
             if (icon && label.text === "") {
                 pill.push(this.icon(icon, center.x, center.y, style.iconColor ?? color));
             }
@@ -3515,9 +3937,9 @@ class Emitter {
                 const y = label.text === "" && !icon ? box.y + box.height / 2 : center.y + techLine;
                 pill.push(this.text(center.x, y, label.technology, techSize, 400, style.color ?? theme.muted));
             }
-            items.push({ kind: "group", id: relation.key, role: "label", items: pill });
+            items.push({ kind: "group", id, role: "label", items: pill });
         }
-        return { kind: "group", id: relation.key, role: "relation", items, track: points(line) };
+        return items;
     }
     /** The brand strip: hairline, mark, wordmark and diagram title, spanning the canvas. */
     frame(width, stripTop, title) {