reladraw 0.0.1 → 0.2.0

package/dist/resolve.js

@@ -0,0 +1,1130 @@
+import { ALL_ATTR_KEYS, ATTR_KEYS, COLOR_KEYS, COLOR_PARTS, describePlacement, } from './ast.js';
+import { ARROW_LENGTH, CHILD_GAP, DECK_STEP, DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, HEADER_GAP, ICON_GAP, ICON_LINES, LABEL_CLEARANCE, PAD, SEPARATION_GAP, fontSizeFor, labelExtent, labelStyleFor, } from './constants.js';
+import { fix, reachability, tightest } from './constrain.js';
+import { SourceError } from './errors.js';
+import { iconFor, shapeFor } from './icons.js';
+import { monospaceMeasurer, splitLines } from './measure.js';
+/**
+ * Turn a parsed document into solved geometry.
+ *
+ * Three passes: build the containment tree, size every node bottom-up, then
+ * turn each node's placements into minimum distances and solve for the tightest
+ * arrangement that satisfies them. That last pass also adds the separations
+ * that keep boxes off each other, and solves again until none is left to add.
+ *
+ * It is a constraint solve, of the kind that computes rather than searches. It
+ * works out how far apart things are; nothing about which side of what a node
+ * sits on is ever decided here, because the author wrote it down.
+ */
+export function resolve(doc, options = {}) {
+    const measurer = options.measurer ?? monospaceMeasurer();
+    const fontSize = options.fontSize ?? DEFAULT_FONT_SIZE;
+    const margin = options.margin ?? DEFAULT_MARGIN;
+    const styles = collectStyles(doc.statements);
+    checkStyleKeys(doc.statements);
+    const { nodes, byName, roots } = buildTree(doc.statements, styles);
+    applyDecks(doc.statements, byName);
+    // Links are resolved to nodes before anything is sized, because a labeled
+    // link claims room in the gap it crosses and so has to be in hand while the
+    // gaps are being worked out. Nothing here reads geometry.
+    const links = buildLinks(doc.statements, byName, styles);
+    const local = new Map();
+    for (const root of roots)
+        sizeNode(root, links, measurer, fontSize, local);
+    placeRoots(roots, byName, links, measurer, fontSize, local);
+    normalize(nodes, margin);
+    const extent = bounds(nodes);
+    return {
+        nodes,
+        roots,
+        links,
+        diagram: collectDiagram(doc.statements),
+        width: Math.ceil(extent.maxX + margin),
+        height: Math.ceil(extent.maxY + margin),
+        margin,
+    };
+}
+// --- pass one: the containment tree -----------------------------------------
+function collectStyles(statements) {
+    const styles = new Map();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'style')
+            continue;
+        if (styles.has(stmt.name)) {
+            throw new SourceError(`style "${stmt.name}" is declared twice`, stmt.line);
+        }
+        styles.set(stmt.name, stmt.attrs);
+    }
+    return styles;
+}
+/** A file holds one diagram, so a second `diagram` statement is a mistake. */
+function collectDiagram(statements) {
+    let found;
+    for (const stmt of statements) {
+        if (stmt.kind !== 'diagram')
+            continue;
+        if (found)
+            throw new SourceError('the diagram is described twice', stmt.line);
+        found = stmt.attrs;
+    }
+    return found ?? {};
+}
+function buildTree(statements, styles) {
+    const nodes = [];
+    const byName = new Map();
+    const roots = [];
+    for (const stmt of statements) {
+        if (stmt.kind !== 'box' && stmt.kind !== 'note')
+            continue;
+        if (byName.has(stmt.name)) {
+            throw new SourceError(`"${stmt.name}" is declared twice`, stmt.line);
+        }
+        const node = {
+            name: stmt.name,
+            kind: stmt.kind,
+            text: stmt.text,
+            lines: linesFor(stmt.text, stmt.attrs, stmt.line),
+            children: [],
+            x: 0,
+            y: 0,
+            width: 0,
+            height: 0,
+            inset: 0,
+            deckLabels: [],
+            headerHeight: 0,
+            label: stmt.kind === 'box' ? stmt.label : {},
+            attrs: stmt.attrs,
+            appearance: appearanceOf(stmt.attrs, styles, stmt.line),
+            placements: stmt.placements,
+            line: stmt.line,
+        };
+        const kind = kindOf(node);
+        checkAttrs(kind, node.name, stmt.attrs, stmt.line);
+        checkStyleUse(kind, node.name, stmt.attrs, styles, stmt.line);
+        const cut = stmt.name.lastIndexOf('.');
+        if (cut === -1) {
+            roots.push(node);
+        }
+        else {
+            const parentName = stmt.name.slice(0, cut);
+            const parent = byName.get(parentName);
+            if (!parent) {
+                throw new SourceError(`"${stmt.name}" is inside "${parentName}", which is not declared yet`, stmt.line);
+            }
+            node.parent = parent;
+            parent.children.push(node);
+        }
+        nodes.push(node);
+        byName.set(stmt.name, node);
+    }
+    return { nodes, byName, roots };
+}
+/** How each kind reads in an error, and what it is actually made of. */
+const KIND_WORD = { box: 'box', note: 'note', glyph: 'glyph body', link: 'link' };
+const KIND_PARTS = {
+    box: 'a fill, a border and text',
+    note: 'bare text and nothing else',
+    glyph: 'a picture and the text under it',
+    link: 'a line and its label',
+};
+/**
+ * An attribute is refused on a kind that has no use for it — the same rule as
+ * an unknown `diagram` key, and for the same reason: a key that silently does
+ * nothing looks like the tool being broken. A color names a part and so is a
+ * special case of this, which is why the two checks are one.
+ *
+ * What is checked is what the author wrote *on this statement*, not what a
+ * style contributed. A style is a bundle meant to be shared across kinds — the
+ * benchmark's `synced` carries a fill and a border for the green boxes and a
+ * line for the four links joining them — so a key it carries that this kind has
+ * no part for is simply unused, and is not a mistake anybody made here. That is
+ * forced rather than chosen: checking the merged appearance would refuse the
+ * benchmark's own central idiom four times over. `checkStyleUse` is what keeps
+ * the permissiveness honest.
+ */
+function checkAttrs(kind, name, attrs, line) {
+    const allowed = ATTR_KEYS[kind];
+    // In the author's own order, so the error names the first offending word as
+    // it is read rather than the first in some list of ours.
+    for (const [key, value] of Object.entries(attrs)) {
+        if (allowed.includes(key))
+            continue;
+        if (!ALL_ATTR_KEYS.includes(key)) {
+            // Nothing anywhere in the language answers to this word, so the only
+            // remedy is the vocabulary itself.
+            throw new SourceError(`"${name}" has ${key}: ${value}, which is not an attribute. A ${KIND_WORD[kind]} takes ${allowed.join(', ')}`, line);
+        }
+        // A real word in the wrong place, and the two sorts of word want different
+        // explanations. A color names a *part*, so saying what the kind is made of
+        // is the whole reason it has no such color, and the remedy is the narrower
+        // list of parts it does have: `line:` on a box is a different mistake from
+        // `border:` on a note, and one hint cannot serve both.
+        if (COLOR_KEYS.includes(key)) {
+            const parts = COLOR_PARTS[kind].map((part) => `\`${part}:\``).join(', ');
+            throw new SourceError(`"${name}" is a ${KIND_WORD[kind]} and has ${key}: ${value}. A ${KIND_WORD[kind]} is ${KIND_PARTS[kind]}, so it has no ${key} — it takes ${parts}`, line);
+        }
+        // Anything else names no part, so what the kind is made of explains
+        // nothing. What does explain it is where the word *does* belong, which is
+        // also the more useful thing to be told: the author has usually written a
+        // real statement about the wrong half of the diagram.
+        throw new SourceError(`"${name}" is a ${KIND_WORD[kind]} and has ${key}: ${value}. \`${key}:\` belongs to ` +
+            `${listKinds(belongTo(key))} — a ${KIND_WORD[kind]} takes ${allowed.join(', ')}`, line);
+    }
+}
+/**
+ * A style may carry keys this kind has no use for, but it may not carry *only*
+ * those. Partial overlap is the normal case and the reason styles exist; zero
+ * overlap is a style name written on the wrong sort of thing, and nothing else.
+ *
+ * This is the check that lets `checkAttrs` ignore style-contributed keys
+ * without the silence coming back. It cannot catch a style that names every key
+ * in the language, since such a style contributes to everything by
+ * construction — that hole is left open, because nobody writes one by accident.
+ */
+function checkStyleUse(kind, name, attrs, styles, line) {
+    const named = attrs['style'];
+    if (named === undefined)
+        return;
+    const base = styles.get(named);
+    if (base === undefined)
+        return; // `appearanceOf` reports the missing style.
+    // A style naming another style is the one way to carry nothing at all: the
+    // parser already refuses one with no attributes, and `appearanceOf` does not
+    // recurse, so the name would sit there doing nothing.
+    const carried = Object.keys(base).filter((key) => key !== 'style');
+    if (carried.length === 0) {
+        throw new SourceError(`style "${named}" carries nothing but a style name`, line);
+    }
+    if (carried.some((key) => ATTR_KEYS[kind].includes(key)))
+        return;
+    throw new SourceError(`style "${named}" gives "${name}" nothing. It carries ${carried.join(' and ')}; ` +
+        `a ${KIND_WORD[kind]} is ${KIND_PARTS[kind]}`, line);
+}
+/**
+ * A style is a bundle spanning kinds, so its keys cannot be checked against any
+ * one of them — but a word that is an attribute of *nothing* is a misspelling
+ * wherever it sits, and a style was the last place in the language where one
+ * could hide.
+ */
+function checkStyleKeys(statements) {
+    for (const stmt of statements) {
+        if (stmt.kind !== 'style')
+            continue;
+        for (const [key, value] of Object.entries(stmt.attrs)) {
+            if (ALL_ATTR_KEYS.includes(key))
+                continue;
+            throw new SourceError(`style "${stmt.name}" has ${key}: ${value}, which is not an attribute. ` +
+                `The attributes are ${ALL_ATTR_KEYS.join(', ')}`, stmt.line);
+        }
+    }
+}
+/** Which kinds understand an attribute, in the order the table declares them. */
+function belongTo(key) {
+    return Object.keys(ATTR_KEYS).filter((kind) => ATTR_KEYS[kind].includes(key));
+}
+/** "a link", "a box or a glyph body", "a box, a note or a glyph body". */
+function listKinds(kinds) {
+    const words = kinds.map((kind) => `a ${KIND_WORD[kind]}`);
+    if (words.length <= 1)
+        return words[0] ?? 'nothing';
+    return `${words.slice(0, -1).join(', ')} or ${words[words.length - 1]}`;
+}
+/** Which of the four kinds a node is, which its `shape:` may decide. */
+function kindOf(node) {
+    if (node.kind === 'note')
+        return 'note';
+    return shapeFor(node.appearance, node.line).body !== undefined ? 'glyph' : 'box';
+}
+function appearanceOf(attrs, styles, line) {
+    const named = attrs['style'];
+    if (named === undefined)
+        return { ...attrs };
+    const base = styles.get(named);
+    if (!base)
+        throw new SourceError(`no style named "${named}"`, line);
+    return { ...base, ...attrs };
+}
+function applyDecks(statements, byName) {
+    for (const stmt of statements) {
+        if (stmt.kind !== 'deck')
+            continue;
+        const node = byName.get(stmt.name);
+        if (!node)
+            throw new SourceError(`deck names "${stmt.name}", which does not exist`, stmt.line);
+        node.deckLabels = stmt.labels;
+    }
+}
+function buildLinks(statements, byName, styles) {
+    const links = [];
+    for (const stmt of statements) {
+        if (stmt.kind !== 'link')
+            continue;
+        const from = byName.get(stmt.from);
+        const to = byName.get(stmt.to);
+        if (!from)
+            throw new SourceError(`link from "${stmt.from}", which does not exist`, stmt.line);
+        if (!to)
+            throw new SourceError(`link to "${stmt.to}", which does not exist`, stmt.line);
+        const between = stmt.between && {
+            nodes: stmt.between.targets.map((name) => {
+                const node = byName.get(name);
+                if (!node) {
+                    throw new SourceError(`link passes between "${name}", which does not exist`, stmt.line);
+                }
+                return node;
+            }),
+            ...(stmt.between.axis !== undefined ? { axis: stmt.between.axis } : {}),
+        };
+        const appearance = appearanceOf(stmt.attrs, styles, stmt.line);
+        const what = `${stmt.from} -> ${stmt.to}`;
+        checkAttrs('link', what, stmt.attrs, stmt.line);
+        checkStyleUse('link', what, stmt.attrs, styles, stmt.line);
+        links.push({
+            from,
+            to,
+            both: stmt.both,
+            ...(stmt.label !== undefined ? { label: stmt.label } : {}),
+            ...(between ? { between } : {}),
+            attrs: stmt.attrs,
+            appearance,
+            line: stmt.line,
+        });
+    }
+    return links;
+}
+/**
+ * Give a node a width and height, sizing its children first. Also records each
+ * child's offset within this node, which pass three turns into absolute
+ * coordinates once this node itself is placed.
+ */
+function sizeNode(node, links, measurer, fontSize, local) {
+    for (const child of node.children)
+        sizeNode(child, links, measurer, fontSize, local);
+    // Text is measured at the size it will be drawn at — the size lives in
+    // `constants.ts` precisely so the resolver reserving the room and the
+    // renderer filling it cannot disagree about how much room there is.
+    const textSize = fontSizeFor(node.kind, node.appearance, fontSize, node.line);
+    const lineHeight = measurer.lineHeight(textSize);
+    // A node with empty text takes no room for it. This is what makes an
+    // invisible grouping container size to exactly its contents.
+    const hasLabel = node.lines.some((line) => line.length > 0);
+    const labelWidth = hasLabel ? widestLine(node.lines, measurer, textSize) : 0;
+    const labelHeight = hasLabel ? node.lines.length * lineHeight : 0;
+    if (node.kind === 'note') {
+        // A note is bare text, so it gets no padding and takes no children.
+        node.width = labelWidth;
+        node.height = labelHeight;
+        return;
+    }
+    const shape = shapeFor(node.appearance, node.line);
+    const glyphSide = ICON_LINES * lineHeight;
+    if (shape.body !== undefined) {
+        // Drawn as a glyph, so there is no box to pad and the node's size is the
+        // picture's. A label goes under it rather than inside it, which is the
+        // arrangement that makes a row of these read as captioned things.
+        if (node.children.length > 0) {
+            throw new SourceError(`"${node.name}" is drawn as a glyph and has children. A glyph is not a box, so nothing can go inside it`, node.line);
+        }
+        node.width = Math.max(glyphSide, labelWidth);
+        node.height = glyphSide + (hasLabel ? ICON_GAP + labelHeight : 0);
+        return;
+    }
+    // An icon takes a column of its own on the right of whatever the box holds,
+    // so the label never runs underneath it and the box grows to fit both. That
+    // is why an icon is not a renderer-only concern: it is content taking room,
+    // like a label, and not appearance like `fill:`.
+    const icon = iconFor(node.appearance, node.line);
+    const iconSide = icon === undefined ? 0 : glyphSide;
+    const iconRoom = icon === undefined ? 0 : iconSide + (hasLabel ? ICON_GAP : 0);
+    if (node.children.length === 0) {
+        // A band only exists because contents have to sit clear of it, and a leaf
+        // has none, so `at` has no end to name. `align` is a different question and
+        // is allowed: a label of several lines has lines of unequal length in any
+        // box, and ranging them left rather than centering them is a real thing to
+        // want. It was refused here too until 2026-09-09, purely because the two
+        // words arrive in the same brackets.
+        if (node.label['at'] !== undefined) {
+            throw new SourceError(`"${node.name}" holds nothing and its label carries at: ${node.label['at']}. ` +
+                `A label sits at one end of a box so its contents can have the other; with no contents there is no band for it to sit at either end of`, node.line);
+        }
+        node.width = labelWidth + iconRoom + PAD * 2;
+        node.height = Math.max(labelHeight, iconSide) + PAD * 2;
+    }
+    else {
+        applyAlign(node);
+        const content = layoutChildren(node, links, measurer, fontSize, local);
+        const band = Math.max(labelHeight, iconSide);
+        // `headerHeight` is the band the label and icon take, whichever end of the
+        // box that band is at. Only the contents' offset depends on the side.
+        node.headerHeight = hasLabel || icon !== undefined ? band + HEADER_GAP : 0;
+        node.width = Math.max(labelWidth + iconRoom, content.width) + PAD * 2;
+        node.height = node.headerHeight + content.height + PAD * 2;
+        const above = labelStyleFor(node.label, node.line).at === 'top' ? node.headerHeight : 0;
+        for (const child of node.children) {
+            const offset = local.get(child);
+            offset.x += PAD;
+            offset.y += PAD + above;
+        }
+    }
+    if (node.deckLabels.length > 0) {
+        // The copies sit behind and above-left, so the whole node grows by the
+        // depth of the stack and its own face moves down and right by the same.
+        node.inset = node.deckLabels.length * DECK_STEP;
+        node.width += node.inset;
+        node.height += node.inset;
+        for (const child of node.children) {
+            const offset = local.get(child);
+            offset.x += node.inset;
+            offset.y += node.inset;
+        }
+    }
+}
+/**
+ * `align: widths` widens every direct child to the widest one's natural
+ * width, before layoutChildren sizes and positions anything from those
+ * widths. A container's own children are already sized by this point.
+ */
+function applyAlign(node) {
+    const value = node.attrs['align'];
+    if (value === undefined)
+        return;
+    if (value !== 'widths') {
+        throw new SourceError(`"${node.name}" has align: ${value}, which is not one of widths`, node.line);
+    }
+    const maxWidth = Math.max(...node.children.map((child) => child.width));
+    for (const child of node.children)
+        child.width = maxWidth;
+}
+/**
+ * Position a container's children relative to each other. Children that make
+ * no placement stack vertically in written order; the rest are solved against the
+ * siblings they name, by the same constraint pass that positions top-level
+ * nodes. A placement may only name a sibling — containment scopes the group.
+ */
+function layoutChildren(parent, links, measurer, fontSize, local) {
+    const siblings = new Map(parent.children.map((child) => [child.name, child]));
+    // Children that say nothing keep the written order, down the page and flush
+    // left. Written as constraints rather than a cursor so a placed sibling can
+    // push them along like anything else.
+    const stack = [];
+    const alignment = [];
+    const quiet = parent.children.filter((child) => child.placements.length === 0);
+    const indexOf = new Map(parent.children.map((child, index) => [child, index]));
+    quiet.forEach((child, position) => {
+        const previous = quiet[position - 1];
+        if (!previous)
+            return;
+        const before = indexOf.get(previous);
+        const after = indexOf.get(child);
+        stack.push({ from: before, to: after, weight: previous.height + CHILD_GAP });
+        alignment.push(...fix(before, after, 0));
+    });
+    const positions = positionGroup(parent.children, (placement, owner) => placement.targets.map((name) => {
+        const target = siblings.get(name);
+        if (!target) {
+            throw new SourceError(`"${owner.name}" is placed against "${name}", which is not one of its siblings`, placement.line);
+        }
+        return {
+            name,
+            node: target,
+            index: indexOf.get(target),
+            offset: { x: 0, y: 0 },
+            width: target.width,
+            height: target.height,
+        };
+    }), { x: alignment, y: stack }, corridorsIn(links, (node) => liftTo(node, indexOf, local), measurer, fontSize));
+    for (const child of parent.children)
+        local.set(child, positions.get(child));
+    return extentOf(parent.children, local);
+}
+function extentOf(children, local) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const child of children) {
+        const offset = local.get(child);
+        minX = Math.min(minX, offset.x);
+        minY = Math.min(minY, offset.y);
+        maxX = Math.max(maxX, offset.x + child.width);
+        maxY = Math.max(maxY, offset.y + child.height);
+    }
+    for (const child of children) {
+        const offset = local.get(child);
+        offset.x -= minX;
+        offset.y -= minY;
+    }
+    return { width: maxX - minX, height: maxY - minY };
+}
+// --- pass three: solve for positions -----------------------------------------
+function placeRoots(roots, byName, links, measurer, fontSize, local) {
+    const anchors = roots.filter((root) => root.placements.length === 0);
+    if (anchors.length === 0) {
+        throw new SourceError('every node is placed relative to another, so nothing anchors the diagram', 1);
+    }
+    if (anchors.length > 1) {
+        const names = anchors.map((node) => `"${node.name}"`).join(', ');
+        throw new SourceError(`exactly one node may say nothing about where it goes, but ${anchors.length} do: ${names}`, anchors[1].line);
+    }
+    const indexOf = new Map(roots.map((root, index) => [root, index]));
+    // A placement may name something nested — `right of server.docker` places a top-level
+    // node against a box inside another. Sizes and offsets within a container are
+    // already settled, so a nested target is its root's position plus a constant.
+    const positions = positionGroup(roots, (placement, owner) => placement.targets.map((name) => {
+        const target = byName.get(name);
+        if (!target) {
+            throw new SourceError(`"${owner.name}" is placed against "${name}", which does not exist`, placement.line);
+        }
+        let root = target;
+        const offset = { x: 0, y: 0 };
+        while (root.parent) {
+            const step = local.get(root);
+            offset.x += step.x;
+            offset.y += step.y;
+            root = root.parent;
+        }
+        return {
+            name,
+            node: target,
+            index: indexOf.get(root),
+            offset,
+            width: target.width,
+            height: target.height,
+        };
+    }), { x: [], y: [] }, corridorsIn(links, (node) => liftTo(node, indexOf, local), measurer, fontSize));
+    for (const root of roots) {
+        const position = positions.get(root);
+        root.x = position.x;
+        root.y = position.y;
+        spreadToChildren(root, local);
+    }
+}
+/** Once a node has an absolute position, its whole subtree follows from the offsets. */
+function spreadToChildren(node, local) {
+    for (const child of node.children) {
+        const offset = local.get(child);
+        child.x = node.x + offset.x;
+        child.y = node.y + offset.y;
+        spreadToChildren(child, local);
+    }
+}
+const AXES = ['x', 'y'];
+const AXIS_WORD = { x: 'horizontally', y: 'vertically' };
+/**
+ * Where a node sits within the group being solved: which member holds it, and
+ * where inside that member. A link may name anything at any depth, so its ends
+ * are lifted to the members of whichever group is being solved — and a node
+ * outside that group has no answer, which is how a link is sorted into the one
+ * group where its two ends are different members.
+ */
+function liftTo(node, indexOf, local) {
+    let member = node;
+    const offset = { x: 0, y: 0 };
+    while (!indexOf.has(member)) {
+        const step = local.get(member);
+        if (!step || !member.parent)
+            return undefined;
+        offset.x += step.x;
+        offset.y += step.y;
+        member = member.parent;
+    }
+    return {
+        name: node.name,
+        node,
+        index: indexOf.get(member),
+        offset,
+        width: node.width,
+        height: node.height,
+    };
+}
+/** The labeled links whose two ends are different members of this group. */
+function corridorsIn(links, locate, measurer, fontSize) {
+    const corridors = [];
+    for (const link of links) {
+        // An unlabeled link asks for nothing: every gap holds an arrowhead. And a
+        // link told to pass between two named things carries its label in *that*
+        // corridor rather than in the gap between its own ends, so widening this one
+        // would make room where the label never goes.
+        if (link.label === undefined || link.between)
+            continue;
+        const from = locate(link.from);
+        const to = locate(link.to);
+        if (!from || !to || from.index === to.index)
+            continue;
+        // The clearance is doubled because the label is drawn at the *midpoint* of
+        // the line, so the room it needs is symmetric about that point whatever sits
+        // at either end. The arrowhead is charged on both sides for the same reason:
+        // it covers `ARROW_LENGTH` of the line it arrives on, and reserving that at
+        // one end only would move the midpoint rather than lengthen the run.
+        const extent = (axis) => labelExtent(link.label, link.appearance, axis, measurer, fontSize, link.line) +
+            (LABEL_CLEARANCE + ARROW_LENGTH) * 2;
+        corridors.push({ link, from, to, need: { x: extent('x'), y: extent('y') } });
+    }
+    return corridors;
+}
+/**
+ * Position a set of nodes against each other from their placements.
+ *
+ * Every placement becomes a minimum distance, and the answer is the arrangement
+ * where nothing is further apart than its placements require — which is what an
+ * author does by hand when they push two things apart to fit something between
+ * them and then pull the slack back out.
+ *
+ * Because a gap is a floor rather than a fixed distance, a corridor widens to
+ * hold whatever is put in it and closes again when that is removed. No number
+ * anywhere has to be guessed, and nothing is ever tried and rejected.
+ */
+function positionGroup(members, locate, extra, corridors = []) {
+    const constraints = { x: [...extra.x], y: [...extra.y] };
+    const indexOf = new Map(members.map((member, index) => [member, index]));
+    const pending = [];
+    for (const node of members) {
+        // Checked here as well as in `gapFor`, so a misspelt node-wide gap is caught
+        // on a node whose placements all name their own or are alignments — and on
+        // one that carries no placements at all, where it now still has an effect.
+        namedGap(node, node.attrs['gap'], node.line);
+        if (node.placements.length === 0)
+            continue;
+        const me = indexOf.get(node);
+        const size = { x: node.width, y: node.height };
+        const located = node.placements.map((placement) => ({ placement, targets: locate(placement, node) }));
+        const spokenFor = { x: false, y: false };
+        for (const { placement } of located) {
+            if (placement.kind === 'align') {
+                spokenFor[placement.axis] = true;
+            }
+            else {
+                if (/left|right/.test(placement.direction))
+                    spokenFor.x = true;
+                if (/above|below/.test(placement.direction))
+                    spokenFor.y = true;
+            }
+        }
+        // Aligning to several targets means aligning to the box that just bounds
+        // them. That box is a constant only while its members hold still relative
+        // to one another; otherwise the alignment waits for the first solution.
+        const alignOn = (axis, edge, targets, placement) => {
+            const anchor = sharedMember(targets);
+            if (anchor === undefined) {
+                pending.push({ node, me, axis, edge, targets, placement });
+                return;
+            }
+            const span = spanOf(targets, axis, () => 0);
+            constraints[axis].push(...fix(anchor, me, alignedAt(edge, span, size[axis]), placement));
+        };
+        for (const { placement, targets } of located) {
+            if (placement.kind === 'align') {
+                alignOn(placement.axis, placement.edge, targets, placement);
+                continue;
+            }
+            // One constraint per target, so the node clears the furthest of them.
+            // Taking that maximum is what longest paths already does, which is why a
+            // direction against a whole region needs nothing added to the solver.
+            const { direction } = placement;
+            // A gap belongs to the relationship rather than to either box in it, so
+            // each placement may name its own and the node's `gap:` is only the
+            // default. That is what lets a node wedged between two things sit tight
+            // against one of them and wide of the other.
+            for (const target of targets) {
+                const gap = gapFor(node, placement, target.node);
+                if (direction.includes('right')) {
+                    constraints.x.push({
+                        from: target.index,
+                        to: me,
+                        weight: target.offset.x + target.width + gap,
+                        placement,
+                    });
+                }
+                if (direction.includes('left')) {
+                    constraints.x.push({
+                        from: me,
+                        to: target.index,
+                        weight: node.width + gap - target.offset.x,
+                        placement,
+                    });
+                }
+                if (direction.includes('below')) {
+                    constraints.y.push({
+                        from: target.index,
+                        to: me,
+                        weight: target.offset.y + target.height + gap,
+                        placement,
+                    });
+                }
+                if (direction.includes('above')) {
+                    constraints.y.push({
+                        from: me,
+                        to: target.index,
+                        weight: node.height + gap - target.offset.y,
+                        placement,
+                    });
+                }
+            }
+        }
+        // An axis nobody spoke to falls back to the center line of whatever the
+        // node was placed against, which is why "right of docker" alone is a whole
+        // position. Two different targets would decide which row the node shares,
+        // so that is refused rather than guessed — but two targets named by one
+        // placement are a single region, and centering on it is unambiguous.
+        for (const axis of AXES) {
+            if (spokenFor[axis])
+                continue;
+            const offers = located.filter((entry) => entry.placement.kind === 'offset');
+            const first = offers[0];
+            if (!first) {
+                throw new SourceError(`"${node.name}" says nothing about where it sits ${AXIS_WORD[axis]}`, node.placements[0].line);
+            }
+            const named = (entry) => entry.placement.targets.join('\u0000');
+            const other = offers.find((entry) => named(entry) !== named(first));
+            if (other) {
+                throw new SourceError(`"${node.name}" does not say where it sits ${AXIS_WORD[axis]}: ` +
+                    `"${describePlacement(first.placement)}" and "${describePlacement(other.placement)}" ` +
+                    `would put it in different places`, other.placement.line);
+            }
+            alignOn(axis, 'center', first.targets, first.placement);
+        }
+    }
+    const solved = { x: [], y: [] };
+    const solveAll = () => {
+        for (const axis of AXES) {
+            const outcome = tightest(members.length, constraints[axis]);
+            if ('contradiction' in outcome)
+                throw noRoom(outcome.contradiction, axis, members);
+            solved[axis] = outcome.positions;
+        }
+    };
+    solveAll();
+    room(corridors, constraints, solved, solveAll);
+    settle(pending, members, constraints, solved, solveAll);
+    snug(members, constraints, solved, solveAll);
+    separate(members, constraints, solved, solveAll);
+    confirm(pending, solved);
+    return new Map(members.map((member, index) => [
+        member,
+        { x: solved.x[index], y: solved.y[index] },
+    ]));
+}
+/** The member every target belongs to, or nothing if they are spread across several. */
+function sharedMember(targets) {
+    const first = targets[0].index;
+    return targets.every((target) => target.index === first) ? first : undefined;
+}
+/** The stretch of one axis that just covers every target. */
+function spanOf(targets, axis, base) {
+    let start = Infinity;
+    let end = -Infinity;
+    for (const target of targets) {
+        const at = base(target) + target.offset[axis];
+        start = Math.min(start, at);
+        end = Math.max(end, at + (axis === 'x' ? target.width : target.height));
+    }
+    return { start, size: end - start };
+}
+/** Where a node of this size sits so that the named edge of it meets the span's. */
+function alignedAt(edge, span, own) {
+    if (edge === 'center')
+        return span.start + (span.size - own) / 2;
+    if (edge === 'top' || edge === 'left')
+        return span.start;
+    return span.start + span.size - own;
+}
+/**
+ * Widen a corridor to hold the label of the link crossing it.
+ *
+ * This is the one place a link reaches the constraint system, and it is the same
+ * measure-then-constrain move `settle` makes rather than links joining the graph
+ * outright: the first solution says which gap each label actually falls in, and
+ * from there the room it needs is an ordinary minimum distance like any other.
+ * Nothing is nudged and no layout is repaired — a constraint the file already
+ * implied is derived and the whole system is solved again.
+ *
+ * Which gap that is, is derived and never chosen. A pair clear of each other on
+ * exactly one axis has exactly one corridor between them, and the label is in
+ * it. A pair clear on *both* axes sits corner to corner, so the line runs
+ * diagonally through open space and there is no corridor to widen; a pair clear
+ * on neither overlaps, which is the separation pass's business and not this
+ * one's. Both are left alone, which is why this only ever moves boxes that a
+ * label is genuinely wedged between.
+ *
+ * A gap being a minimum does the rest. Where the corridor is already wide enough
+ * — because the author said `gap: wide`, or because something else is in there
+ * — the constraint is slack and nothing moves; delete the label and the corridor
+ * closes back to whatever the file asked for.
+ */
+function room(corridors, constraints, solved, solveAll) {
+    let added = false;
+    for (const { from, to, need } of corridors) {
+        const clear = (axis) => {
+            const at = (end) => solved[axis][end.index] + end.offset[axis];
+            const size = (end) => (axis === 'x' ? end.width : end.height);
+            if (at(to) - (at(from) + size(from)) > 1e-9)
+                return { before: from, after: to };
+            if (at(from) - (at(to) + size(to)) > 1e-9)
+                return { before: to, after: from };
+            return undefined;
+        };
+        const open = AXES.filter((axis) => clear(axis));
+        if (open.length !== 1)
+            continue;
+        const axis = open[0];
+        const { before, after } = clear(axis);
+        constraints[axis].push({
+            from: before.index,
+            to: after.index,
+            weight: before.offset[axis] +
+                (axis === 'x' ? before.width : before.height) +
+                need[axis] -
+                after.offset[axis],
+        });
+        added = true;
+    }
+    if (added)
+        solveAll();
+}
+/**
+ * Fix the alignments that had to wait, by measuring what they align to.
+ *
+ * The first solution says where every target actually landed, so the region
+ * they bound is now a number rather than an expression, and the alignment
+ * becomes an ordinary constraint at a fixed distance. Nothing already solved is
+ * moved by hand; a distance is read off and added, which is the same shape as
+ * the separation pass and not the repair pass this design refuses.
+ *
+ * That is exact so long as the region does not depend on the node being aligned
+ * to it. Where it does, measuring changes the thing measured and there is no
+ * order that settles, so the file is refused rather than iterated at. The test
+ * is the same reachability the separation pass uses.
+ */
+function settle(pending, members, constraints, solved, solveAll) {
+    if (pending.length === 0)
+        return;
+    for (const axis of AXES) {
+        const here = pending.filter((entry) => entry.axis === axis);
+        if (here.length === 0)
+            continue;
+        const reach = reachability(members.length, constraints[axis]);
+        for (const entry of here) {
+            for (const target of entry.targets) {
+                if (target.index !== entry.me && !reach[entry.me][target.index])
+                    continue;
+                throw new SourceError(`"${entry.node.name}" is ${describePlacement(entry.placement)}, but "${target.name}" ` +
+                    `is placed ${AXIS_WORD[axis]} against "${entry.node.name}" in turn, so there is no ` +
+                    `arrangement where each waits for the other`, entry.placement.line);
+            }
+            const span = spanOf(entry.targets, axis, (target) => solved[axis][target.index]);
+            const own = axis === 'x' ? entry.node.width : entry.node.height;
+            const anchor = entry.targets[0].index;
+            constraints[axis].push(...fix(anchor, entry.me, alignedAt(entry.edge, span, own) - solved[axis][anchor], entry.placement));
+        }
+    }
+    solveAll();
+}
+/**
+ * Check the measured alignments still hold.
+ *
+ * Separation runs afterwards and only ever adds, so it can push two targets
+ * apart and leave a region wider than it was when it was measured. Nothing here
+ * repairs that — the picture is reported as unbuildable, because silently
+ * drawing a node that is no longer level with what it names is the failure the
+ * diagnostics work exists to prevent.
+ */
+function confirm(pending, solved) {
+    for (const entry of pending) {
+        const { axis } = entry;
+        const span = spanOf(entry.targets, axis, (target) => solved[axis][target.index]);
+        const own = axis === 'x' ? entry.node.width : entry.node.height;
+        if (Math.abs(alignedAt(entry.edge, span, own) - solved[axis][entry.me]) <= 0.5)
+            continue;
+        throw new SourceError(`"${entry.node.name}" cannot be ${describePlacement(entry.placement)}: keeping boxes off ` +
+            `each other moved them apart after that region was measured`, entry.placement.line);
+    }
+}
+/**
+ * Pull in a node that nothing pushes back the other way.
+ *
+ * Every constraint reads "this one is at least so far along the axis from that
+ * one", and the solve puts each member at the smallest position its constraints
+ * allow. That is the tightest arrangement for anything with something behind
+ * it — but `left of X` and `above X` bound *X*, not the node that wrote them,
+ * so a node carrying only those has nothing behind it at all. It settles at the
+ * far edge of the drawing while the thing it names is carried away by the rest
+ * of the diagram, which is neither what the file says nor what the language
+ * promises: as close together as the placements allow.
+ *
+ * The remedy is to look the other way for exactly those members. A member with
+ * no incoming edge cannot be pushed by anything, so moving it along the axis
+ * disturbs nothing; the furthest it may travel is set by whichever of its own
+ * placements binds first, and pinning that one placement to an exact distance
+ * puts it there. Every other placement it wrote had more room to spare and is
+ * still satisfied.
+ *
+ * The pins are worked out against the first solution and applied together,
+ * which keeps them independent: a member with no incoming edge is never the
+ * target of another member's pin, because being a target is what an incoming
+ * edge is.
+ */
+function snug(members, constraints, solved, solveAll) {
+    const pins = [];
+    for (const axis of AXES) {
+        const pushed = new Array(members.length).fill(false);
+        for (const constraint of constraints[axis])
+            pushed[constraint.to] = true;
+        for (let index = 0; index < members.length; index += 1) {
+            if (pushed[index])
+                continue;
+            let binding;
+            let slack = Infinity;
+            for (const constraint of constraints[axis]) {
+                if (constraint.from !== index)
+                    continue;
+                const room = solved[axis][constraint.to] - solved[axis][index] - constraint.weight;
+                if (room < slack) {
+                    slack = room;
+                    binding = constraint;
+                }
+            }
+            // Nothing to travel toward, or already against it.
+            if (!binding || slack <= 1e-9)
+                continue;
+            pins.push({
+                axis,
+                constraint: {
+                    from: binding.to,
+                    to: index,
+                    weight: -binding.weight,
+                    ...(binding.placement ? { placement: binding.placement } : {}),
+                },
+            });
+        }
+    }
+    if (pins.length === 0)
+        return;
+    for (const pin of pins)
+        constraints[pin.axis].push(pin.constraint);
+    solveAll();
+}
+/**
+ * Push apart any two boxes that landed on top of each other.
+ *
+ * Two boxes not overlapping is a placement the author never has to write, but on
+ * its own it says nothing about *which way* to separate them — left, right,
+ * above and below all satisfy it, and choosing among four is the search this
+ * whole design refuses. So the direction is never chosen. It is read off the
+ * constraints already built from the file: if the file lets one box travel away
+ * from the other along an axis and offers no way back, that is the only
+ * separation consistent with what was written. Where nothing in the file orders
+ * a pair on either axis, this reports the pair instead of guessing.
+ *
+ * One case is genuinely free. When both axes already imply an order, either
+ * would do, and the tie is broken by separating along the axis where the two
+ * overlap least — the smallest movement, and the one a person makes by hand.
+ * That is the single place the tool decides something nobody wrote.
+ *
+ * The loop only ever adds constraints and re-solves the whole system, so no
+ * arrangement is ever tried and rejected and it settles without backtracking.
+ * A solved layout is never nudged in place; that is a different thing and it is
+ * the thing the design rules out.
+ *
+ * Members here are always siblings, or the roots of the diagram, so no member
+ * ever contains another and containment needs no exemption of its own.
+ */
+function separate(members, constraints, solved, solveAll) {
+    const eligible = members.map(allowsOverlap).map((allowed) => !allowed);
+    if (eligible.filter(Boolean).length < 2)
+        return;
+    // Adding only, so the number of separations is bounded; the cap is a
+    // backstop against a bug rather than an expected outcome.
+    for (let round = 0; round < members.length * members.length + 1; round += 1) {
+        let reach;
+        let added = false;
+        for (let i = 0; i < members.length; i += 1) {
+            if (!eligible[i])
+                continue;
+            for (let j = i + 1; j < members.length; j += 1) {
+                if (!eligible[j])
+                    continue;
+                const over = overlapOf(members, solved, i, j);
+                if (!over)
+                    continue;
+                reach ??= { x: reachability(members.length, constraints.x), y: reachability(members.length, constraints.y) };
+                const orders = {};
+                for (const axis of AXES) {
+                    const order = impliedOrder(reach[axis], i, j);
+                    if (order)
+                        orders[axis] = order;
+                }
+                const axis = pickAxis(orders, over);
+                if (!axis)
+                    throw unordered(members[i], members[j]);
+                const { before, after } = orders[axis];
+                const span = axis === 'x' ? members[before].width : members[before].height;
+                constraints[axis].push({ from: before, to: after, weight: span + SEPARATION_GAP });
+                reach = undefined;
+                added = true;
+            }
+        }
+        if (!added)
+            return;
+        solveAll();
+    }
+}
+/** How far two members share space on each axis, or nothing if they are clear of each other. */
+function overlapOf(members, solved, i, j) {
+    const shared = (axis) => {
+        const size = (index) => (axis === 'x' ? members[index].width : members[index].height);
+        const startI = solved[axis][i];
+        const startJ = solved[axis][j];
+        return Math.min(startI + size(i), startJ + size(j)) - Math.max(startI, startJ);
+    };
+    const x = shared('x');
+    const y = shared('y');
+    return x > 1e-9 && y > 1e-9 ? { x, y } : undefined;
+}
+/** Which of two members the file lets the other move past, if either. */
+function impliedOrder(reach, i, j) {
+    const forward = reach[i][j];
+    const backward = reach[j][i];
+    if (forward === backward)
+        return undefined;
+    return forward ? { before: i, after: j } : { before: j, after: i };
+}
+/** Of the axes that can separate a pair, the one where they overlap least. */
+function pickAxis(orders, over) {
+    const available = AXES.filter((axis) => orders[axis]);
+    if (available.length < 2)
+        return available[0];
+    return over.x <= over.y ? 'x' : 'y';
+}
+function allowsOverlap(node) {
+    const value = node.attrs['overlap'];
+    if (value === undefined)
+        return false;
+    if (value !== 'allow') {
+        throw new SourceError(`"${node.name}" has overlap: ${value}, which is not one of allow`, node.line);
+    }
+    return true;
+}
+function unordered(first, second) {
+    const [earlier, later] = first.line <= second.line ? [first, second] : [second, first];
+    return new SourceError(`"${earlier.name}" and "${later.name}" overlap, and nothing says which side of the ` +
+        `other either one sits on — place one against the other, or say overlap: allow`, later.line);
+}
+/** Report a set of placements that cannot all hold, in the words they were written in. */
+function noRoom(contradiction, axis, members) {
+    const { placements } = contradiction;
+    if (placements.length === 0) {
+        return new SourceError(`these placements run in a circle ${AXIS_WORD[axis]} and cannot all hold`, members[0]?.line ?? 1);
+    }
+    const quoted = placements.map((placement) => `"${describePlacement(placement)}"`).join(' and ');
+    return new SourceError(`${quoted} cannot all hold — they leave no room ${AXIS_WORD[axis]}`, placements[placements.length - 1].line);
+}
+/**
+ * How far this placement holds the node off its target.
+ *
+ * A gap is a property of the relationship, not of either box in it, so the
+ * placement's own bracketed gap is the specific statement about this pair and
+ * wins outright. Where it says nothing, `gap:` on a node is a default — and both
+ * ends of the relationship may offer one. The node doing the placing wrote its
+ * gap down; the target had someone else's placement written against it. Neither
+ * is more entitled than the other, so the larger applies, which is the only
+ * answer consistent with a gap being a minimum in the first place.
+ *
+ * That is what makes `gap: wide` on a node that carries no placements of its own
+ * do the obvious thing rather than nothing at all: an author looking at two boxes
+ * pushed too close together has no reason to know which of the two happened to
+ * name the other.
+ */
+function gapFor(node, placement, target) {
+    if (placement.gap !== undefined)
+        return namedGap(node, placement.gap, placement.line);
+    const mine = node.attrs['gap'];
+    const theirs = target.attrs['gap'];
+    // Only a gap somebody actually wrote down counts. Reading an absent one as the
+    // default would make it a floor rather than a fallback, and every `gap: tight`
+    // placed against a silent node would quietly widen back to normal.
+    const stated = [];
+    if (mine !== undefined)
+        stated.push(namedGap(node, mine, node.line));
+    if (theirs !== undefined)
+        stated.push(namedGap(target, theirs, target.line));
+    if (stated.length === 0)
+        return namedGap(node, undefined, node.line);
+    return Math.max(...stated);
+}
+function namedGap(node, named, line) {
+    const gap = GAPS[named ?? 'normal'];
+    if (gap === undefined) {
+        const known = Object.keys(GAPS).join(', ');
+        throw new SourceError(`"${node.name}" asks for gap: ${named}, which is not one of ${known}`, line);
+    }
+    return gap;
+}
+// --- shared helpers ----------------------------------------------------------
+function widestLine(lines, measurer, fontSize) {
+    return lines.reduce((widest, line) => {
+        const { width } = measurer.measure(line, fontSize);
+        return Math.max(widest, width);
+    }, 0);
+}
+/**
+ * Split a label into the lines that get drawn. `/` always breaks a line. A
+ * `width` attribute additionally folds each of those at word boundaries, which
+ * is what stops a long note running across the whole diagram.
+ *
+ * The width is a character count rather than a distance. It says how much text
+ * fits on a line, not where anything sits, so it stays a property of the text
+ * and never becomes a coordinate in disguise.
+ */
+function linesFor(text, attrs, line) {
+    const stated = attrs['wrap'];
+    if (stated === undefined)
+        return splitLines(text);
+    const columns = Number(stated);
+    if (!Number.isInteger(columns) || columns < 1) {
+        throw new SourceError(`wrap must be a whole number of characters, not "${stated}"`, line);
+    }
+    return splitLines(text).flatMap((part) => wrap(part, columns));
+}
+/** Fold one line onto several at word boundaries, never exceeding `columns`. */
+function wrap(text, columns) {
+    const lines = [];
+    let current = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= columns) {
+            current += ` ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    return lines.length > 0 ? lines : [''];
+}
+function bounds(nodes) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const node of nodes) {
+        minX = Math.min(minX, node.x);
+        minY = Math.min(minY, node.y);
+        maxX = Math.max(maxX, node.x + node.width);
+        maxY = Math.max(maxY, node.y + node.height);
+    }
+    return { minX, minY, maxX, maxY };
+}
+/** Shift everything so the diagram starts at the margin rather than wherever the anchor fell. */
+function normalize(nodes, margin) {
+    const { minX, minY } = bounds(nodes);
+    const dx = margin - minX;
+    const dy = margin - minY;
+    for (const node of nodes) {
+        node.x += dx;
+        node.y += dy;
+    }
+}