dsh-model-everything 0.5.0 → 0.5.2

package/lib/render/from-plantuml.js

@@ -9,53 +9,180 @@
  * Supported:
  *
  * - `@startuml` / `@enduml` (optional) and `title ...`;
- * - `component X`, `component "text" as X`, `[text] as X`, `[text]`;
- * - `package "text" { ... }`, `node`, `folder`, `cloud`, `database` - a group, closed by `}`;
- * - `X --> Y`, `X ---> Y`, `X ..> Y`, `X --> Y : label`, arrow either direction;
- * - `state X`, `state "text" as X`, and `[*] --> X` for a start marker;
+ * - elements: `component`, `node`, `rectangle`, `artifact` and `state` (a rectangle), `database` and
+ *   `entity` (a cylinder), `usecase` (an ellipse), `[text]`, each with a `"text"` label and `as` alias;
+ * - boundaries: `package`, `folder`, `node`, `component`, `rectangle` and `artifact` blocks, closed by `}`;
+ * - arrows, either direction: association `-->`/`<--`, dependency `..>`/`<..`, generalisation `--|>`/`<|--`,
+ *   realisation `..|>`/`<|..`, composition `*--`/`--*`, aggregation `o--`/`--o`, labelled after `:`;
+ * - an edge end that names a declared block attaches to that block's rectangle, the way an external
+ *   dependency on a package is drawn; a name that is not a declared block is an implicit element;
+ * - `[*] --> X` for a start marker;
  * - `'` comments and `skinparam`/`!theme` directives.
  *
- * Refused, by name: `sequence`, `actor`, `participant`, `usecase`, `class`, `object`, `note`, `legend`,
- * `alt`/`opt`/`loop`/`par` and any other fragment keyword.
+ * Refused, by line and by name: the element keywords this renderer has no symbol for (`actor`, `class`,
+ * `cloud`, ...), the diagram kinds it does not draw (`sequence`), and an edge it cannot draw as written (a
+ * line with no arrow end, a mark at both ends, a dotted diamond, an edge between two boundaries, or an edge
+ * into a boundary that is nested or empty).
  */
 import { emptyDiagram } from './model.js';
-const ARROW = /^(.+?)\s*(<?)(-{2,}|\.{2,})(>?)\s*(.+?)(?:\s*:\s*(.+))?$/;
-const DECLARED = /^(component|package|node|folder|cloud|database|state|artifact|frame|rectangle)\s+(.+)$/;
+/** The element keywords this renderer draws, and the symbol each one becomes. */
+const SHAPES = {
+    component: 'rect',
+    node: 'rect',
+    rectangle: 'rect',
+    artifact: 'rect',
+    state: 'rect',
+    database: 'cylinder',
+    // PlantUML draws an entity as a cylinder in a component diagram; `entity` in an ER diagram is a different
+    // symbol, and that diagram family is not one this renderer accepts.
+    entity: 'cylinder',
+    // A use case is an ellipse. The `circle` symbol is written as an ellipse whose radii follow the box, so it
+    // reads as the familiar use-case oval; `stadium` is the pill a terminal state is drawn as.
+    usecase: 'circle',
+};
+/** The keywords that open a boundary around what is written inside them. */
+const BOUNDARY = new Set(['package', 'folder', 'node', 'component', 'rectangle', 'artifact']);
+/** Element keywords this renderer deliberately does not draw, with the reason it gives for each. */
+const NOT_DRAWN = {
+    actor: 'an actor is a stick figure, not one of the shapes this renderer draws',
+    participant: 'a participant is a lifeline, not one of the shapes this renderer draws',
+    class: 'a class box has compartments this renderer does not draw',
+    object: 'an object box has compartments this renderer does not draw',
+    interface: 'an interface is a circle or a boxed stereotype, neither of which this renderer draws',
+    enum: 'an enum box has compartments this renderer does not draw',
+    annotation: 'an annotation is not one of the shapes this renderer draws',
+    cloud: 'a cloud outline is not one of the shapes this renderer draws',
+    frame: 'a frame tab is not one of the shapes this renderer draws',
+    card: 'a card is not one of the shapes this renderer draws',
+    file: 'a file outline is not one of the shapes this renderer draws',
+    agent: 'an agent is not one of the shapes this renderer draws',
+    boundary: 'the boundary symbol is not one of the shapes this renderer draws',
+    control: 'the control symbol is not one of the shapes this renderer draws',
+    collections: 'a collections symbol is not one of the shapes this renderer draws',
+    queue: 'a queue is not one of the shapes this renderer draws',
+    stack: 'a stack is not one of the shapes this renderer draws',
+    storage: 'a storage symbol is not one of the shapes this renderer draws',
+    note: 'a note is not one of the shapes this renderer draws',
+    legend: 'a legend is not one of the shapes this renderer draws',
+};
+/** A sequence fragment or lifeline event: lines that only make sense in a diagram this renderer refuses. */
+const FRAGMENT = new Set(['sequence', 'alt', 'opt', 'loop', 'par', 'group', 'ref', 'break', 'critical', 'activate', 'deactivate', 'destroy', 'create', 'newpage', 'autonumber']);
+const ARROW = /^(.+?)\s*(<\|?|[*o])?(-{2,}|\.{2,})(\|?>|[*o])?\s*(.+?)(?:\s*:\s*(.+))?$/;
+const SHAPE_KEYWORDS = Object.keys(SHAPES);
+const DECLARED = new RegExp('^(' + SHAPE_KEYWORDS.join('|') + ')\\s+(.+)$');
 const QUOTED_ALIAS = /^["'](.+?)["']\s+as\s+([A-Za-z_][\w-]*)$/;
 const BRACKET_ALIAS = /^\[(.+?)\]\s+as\s+([A-Za-z_][\w-]*)$/;
+const PLAIN_ALIAS = /^([A-Za-z_][\w.-]*)\s+as\s+([A-Za-z_][\w-]*)$/;
 const BRACKET = /^\[(.+?)\]$/;
-const UNSUPPORTED = /^(actor|participant|usecase|class|object|note|legend|alt|opt|loop|par|group\s|ref\s|activate|deactivate|destroy|create|newpage)\b/;
-const IGNORED = /^(skinparam|!theme|!define|!include|hide|show|scale|left to right direction|top to bottom direction|together)\b/;
-function ensure(builder, id, label) {
+const IGNORED = /^(skinparam|!theme|!define|!include|!pragma|hide|show|scale|left to right direction|top to bottom direction|together|allowmixing)\b/;
+function ensure(builder, id, label, shape, implicit = false) {
     const existing = builder.nodes.get(id);
     if (existing === undefined) {
-        builder.nodes.set(id, { id, role: 'normal', ...(label === undefined ? {} : { label }) });
+        builder.nodes.set(id, {
+            id,
+            role: 'normal',
+            ...(label === undefined ? {} : { label }),
+            ...(shape === undefined ? {} : { shape }),
+        });
+        if (implicit)
+            builder.implicit.add(id);
         // Membership is decided where the node is first written: the innermost open boundary.
         const innermost = builder.open[builder.open.length - 1];
         if (innermost !== undefined && !innermost.members.includes(id))
             innermost.members.push(id);
         return;
     }
+    // An explicit declaration settles what a name is: it stays a box even when a block has the same name.
+    if (!implicit)
+        builder.implicit.delete(id);
     if (label !== undefined && (existing.label === undefined || existing.label === ''))
         existing.label = label;
+    // A bare reference may have been written first: the later declaration is what states the symbol.
+    if (shape !== undefined && existing.shape === undefined)
+        existing.shape = shape;
 }
-/** A component reference: `[text]`, `X`, or a quoted name. Returns the id and the label it carried. */
+/** A component reference: `[text]`, `X`, or a quoted name. Returns the id, the label and any shape it stated. */
 function reference(token) {
     const text = token.trim();
     const bracket = BRACKET.exec(text);
     if (bracket !== null) {
         const label = bracket[1].trim();
-        return { id: label, label };
+        return { id: label, label, shape: 'rect' };
     }
     const quoted = /^["'](.+?)["']$/.exec(text);
     if (quoted !== null)
         return { id: quoted[1], label: quoted[1] };
     return { id: text };
 }
+function keywordOf(line) {
+    return line.split(/[\s{]/)[0].toLowerCase();
+}
+/** The id and label an opening boundary line states. An alias is the id, because edges will name it. */
+function boundaryOf(declaration, keyword, ordinal) {
+    const rest = declaration.slice(keyword.length).trim();
+    const alias = QUOTED_ALIAS.exec(rest) ?? BRACKET_ALIAS.exec(rest) ?? PLAIN_ALIAS.exec(rest);
+    if (alias !== null)
+        return { id: alias[2], label: alias[1] };
+    const label = rest.replace(/^["']|["']$/g, '');
+    return { id: 'group-' + String(ordinal), label: label === '' ? keyword : label };
+}
+/**
+ * Read one arrow line.
+ *
+ * Returns the edge it states, `undefined` when the line is not an arrow at all, or the reason it is refused.
+ * The arrow the source writes decides which end carries the mark: `A <|-- B` is B generalising to A, so the
+ * edge runs from B to A with the triangle at A, and `A *-- B` puts its diamond at A, so A is the source.
+ */
+function readArrow(line) {
+    const match = ARROW.exec(line);
+    if (match === null)
+        return undefined;
+    const left = reference(match[1]);
+    const right = reference(match[5]);
+    const leftMark = match[2];
+    const rightMark = match[4];
+    const dotted = match[3].startsWith('.');
+    const label = (match[6] ?? '').trim();
+    if (leftMark !== undefined && rightMark !== undefined) {
+        return 'an edge marked at both ends is not one this renderer draws';
+    }
+    if (leftMark === '*' || leftMark === 'o' || rightMark === '*' || rightMark === 'o') {
+        if (dotted)
+            return 'a dotted composition or aggregation is not one this renderer draws';
+        const atRight = rightMark === '*' || rightMark === 'o';
+        const mark = atRight ? rightMark : leftMark;
+        return {
+            from: atRight ? right : left,
+            to: atRight ? left : right,
+            label,
+            dashed: false,
+            arrow: mark === '*' ? 'composition' : 'aggregation',
+        };
+    }
+    if (leftMark !== undefined) {
+        return {
+            from: right,
+            to: left,
+            label,
+            dashed: dotted,
+            arrow: leftMark === '<|' ? (dotted ? 'realization' : 'generalization') : dotted ? 'dependency' : 'association',
+        };
+    }
+    if (rightMark !== undefined) {
+        return {
+            from: left,
+            to: right,
+            label,
+            dashed: dotted,
+            arrow: rightMark === '|>' ? (dotted ? 'realization' : 'generalization') : dotted ? 'dependency' : 'association',
+        };
+    }
+    return 'a line with no arrow end is not one this renderer draws; name the end it points at';
+}
 export function fromPlantUml(source, title = 'plantuml') {
     const lines = source.split(/\r?\n/);
     const refused = [];
-    const builder = { nodes: new Map(), edges: [], groups: [], open: [] };
+    const builder = { nodes: new Map(), edges: [], edgeLines: [], edgeScopes: [], groups: [], open: [], implicit: new Set() };
     let startId;
     let seenAny = false;
     let groupCount = 0;
@@ -71,8 +198,14 @@ export function fromPlantUml(source, title = 'plantuml') {
             return;
         if (IGNORED.test(line))
             return;
-        if (UNSUPPORTED.test(line)) {
-            refused.push(where + '`' + (line.split(/\s/)[0] ?? '') + '` is not a diagram this renderer draws');
+        const keyword = keywordOf(line);
+        const notDrawn = NOT_DRAWN[keyword];
+        if (notDrawn !== undefined) {
+            refused.push(where + '`' + keyword + '`: ' + notDrawn);
+            return;
+        }
+        if (FRAGMENT.has(keyword)) {
+            refused.push(where + '`' + keyword + '`: a sequence statement is not part of a drawing this renderer makes');
             return;
         }
         if (line === '}') {
@@ -87,59 +220,198 @@ export function fromPlantUml(source, title = 'plantuml') {
         }
         if (line.endsWith('{')) {
             const declaration = line.slice(0, -1).trim();
-            const declared = DECLARED.exec(declaration);
-            const label = declared === null ? declaration.replace(/^["']|["']$/g, '') : declared[2].replace(/^["']|["']$/g, '');
+            const opener = keywordOf(declaration);
+            if (!BOUNDARY.has(opener)) {
+                const reason = SHAPES[opener] === undefined
+                    ? '`' + declaration + '` is not a boundary this renderer draws'
+                    : 'a `' + opener + '` block is not a boundary this renderer draws';
+                refused.push(where + reason);
+                return;
+            }
             groupCount += 1;
-            builder.open.push({ id: 'group-' + String(groupCount), label, members: [] });
+            const boundary = boundaryOf(declaration, opener, groupCount);
+            builder.open.push({ id: boundary.id, label: boundary.label, members: [] });
+            return;
+        }
+        if (line === '[*] --> [*]')
+            return;
+        const startMarker = /^\[\*\]\s*-->\s*(.+)$/.exec(line);
+        if (startMarker !== null) {
+            const target = reference(startMarker[1]);
+            ensure(builder, target.id, target.label, target.shape);
+            if (startId === undefined)
+                startId = target.id;
             return;
         }
         const declared = DECLARED.exec(line);
         if (declared !== null) {
+            const shape = SHAPES[declared[1]];
             const rest = declared[2].trim();
             const quoted = QUOTED_ALIAS.exec(rest);
             if (quoted !== null) {
-                ensure(builder, quoted[2], quoted[1]);
+                ensure(builder, quoted[2], quoted[1], shape);
                 return;
             }
             const bracketed = BRACKET_ALIAS.exec(rest);
             if (bracketed !== null) {
-                ensure(builder, bracketed[2], bracketed[1]);
+                ensure(builder, bracketed[2], bracketed[1], shape);
                 return;
             }
-            if (/^["'](.+?)["']$/.test(rest))
-                return; // a group heading with no alias: nothing to draw
-            const reference_ = reference(rest);
-            ensure(builder, reference_.id, reference_.label);
-            return;
-        }
-        if (line === '[*] --> [*]')
-            return;
-        const startMarker = /^\[\*\]\s*-->\s*(.+)$/.exec(line);
-        if (startMarker !== null) {
-            const target = reference(startMarker[1]);
-            ensure(builder, target.id, target.label);
-            if (startId === undefined)
-                startId = target.id;
+            const plain = PLAIN_ALIAS.exec(rest);
+            if (plain !== null) {
+                ensure(builder, plain[2], plain[1], shape);
+                return;
+            }
+            const written = reference(rest);
+            ensure(builder, written.id, written.label, shape);
             return;
         }
-        const arrow = ARROW.exec(line);
-        if (arrow !== null) {
-            const left = arrow[2] === '<' ? arrow[5] : arrow[1];
-            const right = arrow[2] === '<' ? arrow[1] : arrow[5];
-            const from = reference(left);
-            const to = reference(right);
-            ensure(builder, from.id, from.label);
-            ensure(builder, to.id, to.label);
-            builder.edges.push({ from: from.id, to: to.id, label: (arrow[6] ?? '').trim(), ...(arrow[3].startsWith('.') ? { dashed: true } : {}) });
+        const arrow = readArrow(line);
+        if (arrow !== undefined) {
+            if (typeof arrow === 'string') {
+                refused.push(where + arrow);
+                return;
+            }
+            ensure(builder, arrow.from.id, arrow.from.label, arrow.from.shape, true);
+            ensure(builder, arrow.to.id, arrow.to.label, arrow.to.shape, true);
+            builder.edges.push({
+                from: arrow.from.id,
+                to: arrow.to.id,
+                label: arrow.label,
+                ...(arrow.dashed ? { dashed: true } : {}),
+                arrow: arrow.arrow,
+            });
+            builder.edgeLines.push(index + 1);
+            builder.edgeScopes.push(builder.open[builder.open.length - 1]?.id);
             return;
         }
         const single = BRACKET.exec(line);
         if (single !== null) {
-            ensure(builder, single[1].trim(), single[1].trim());
+            ensure(builder, single[1].trim(), single[1].trim(), 'rect');
             return;
         }
         refused.push(where + '`' + line + '` is not something this renderer draws');
     });
+    // A block's name can be written as an edge endpoint: `Web <|-- Mobile` points at the `package Web`
+    // block. PlantUML allows it and so does UML; what it must not do is become a second box called `Web`.
+    // An endpoint an arrow created is re-read as the boundary it names, and the edge attaches to that
+    // boundary's rectangle. A name that is not a declared block stays an implicit element, which PlantUML
+    // also allows.
+    const boundaryNames = new Map();
+    const disputedNames = new Set();
+    for (const group of builder.groups) {
+        for (const name of [group.id, group.label]) {
+            const existing = boundaryNames.get(name);
+            if (existing !== undefined && existing !== group.id)
+                disputedNames.add(name);
+            else
+                boundaryNames.set(name, group.id);
+        }
+    }
+    for (const name of disputedNames)
+        boundaryNames.delete(name);
+    // Only a node an arrow wrote can turn out to be a boundary. An explicitly declared element of the same
+    // name stays a box: the source said what it is.
+    const boundaryAt = new Map();
+    const ambiguousAt = new Set();
+    for (const id of builder.implicit) {
+        if (disputedNames.has(id)) {
+            ambiguousAt.add(id);
+            builder.nodes.delete(id);
+        }
+        else {
+            const groupId = boundaryNames.get(id);
+            if (groupId === undefined)
+                continue;
+            boundaryAt.set(id, groupId);
+            builder.nodes.delete(id);
+        }
+        for (const group of builder.groups) {
+            const at = group.members.indexOf(id);
+            if (at >= 0)
+                group.members.splice(at, 1);
+        }
+    }
+    const groupById = new Map(builder.groups.map((group) => [group.id, group]));
+    const childrenOf = new Map();
+    for (const group of builder.groups) {
+        if (group.parent === undefined)
+            continue;
+        childrenOf.set(group.parent, [...(childrenOf.get(group.parent) ?? []), group.id]);
+    }
+    // An empty boundary is not drawn, so an edge cannot attach to it. Look through nested boundaries, which
+    // are drawn only when something inside them is.
+    const drawable = new Map();
+    const hasContents = (id) => {
+        const known = drawable.get(id);
+        if (known !== undefined)
+            return known;
+        const group = groupById.get(id);
+        let found = false;
+        for (const member of group.members) {
+            if (builder.nodes.has(member)) {
+                found = true;
+                break;
+            }
+        }
+        if (!found) {
+            for (const child of childrenOf.get(id) ?? []) {
+                if (hasContents(child)) {
+                    found = true;
+                    break;
+                }
+            }
+        }
+        drawable.set(id, found);
+        return found;
+    };
+    const boundaryLabel = (id) => groupById.get(id).label;
+    const within = (scope, boundary) => {
+        let cursor = scope;
+        while (cursor !== undefined) {
+            if (cursor === boundary)
+                return true;
+            cursor = groupById.get(cursor).parent;
+        }
+        return false;
+    };
+    const keptEdges = [];
+    builder.edges.forEach((edge, index) => {
+        const where = 'line ' + String(builder.edgeLines[index]) + ': ';
+        const fromBoundary = boundaryAt.get(edge.from);
+        const toBoundary = boundaryAt.get(edge.to);
+        if (ambiguousAt.has(edge.from) || ambiguousAt.has(edge.to)) {
+            const name = ambiguousAt.has(edge.from) ? edge.from : edge.to;
+            refused.push(where + '`' + name + '` is the name of more than one block; an edge cannot say which boundary it means');
+            return;
+        }
+        if (fromBoundary !== undefined && toBoundary !== undefined) {
+            refused.push(where + '`' + boundaryLabel(fromBoundary) + '` and `' + boundaryLabel(toBoundary) + '` are boundaries, not elements; an edge between two boundaries is not one this renderer draws');
+            return;
+        }
+        const boundary = fromBoundary ?? toBoundary;
+        if (boundary !== undefined) {
+            const group = groupById.get(boundary);
+            if (group.parent !== undefined) {
+                refused.push(where + '`' + group.label + '` is a block inside `' + boundaryLabel(group.parent) + '`, not an element; an edge to a nested boundary would have to enter another boundary');
+                return;
+            }
+            if (within(builder.edgeScopes[index], boundary)) {
+                refused.push(where + '`' + group.label + '` is the block this edge is written inside, not an element; an edge cannot leave a boundary and arrive at the same boundary');
+                return;
+            }
+            if (!hasContents(boundary)) {
+                refused.push(where + '`' + group.label + '` is a block with nothing drawn inside it, so there is no rectangle to attach the edge to');
+                return;
+            }
+        }
+        keptEdges.push({
+            ...edge,
+            ...(fromBoundary === undefined ? {} : { from: fromBoundary }),
+            ...(toBoundary === undefined ? {} : { to: toBoundary }),
+        });
+    });
+    builder.edges = keptEdges;
     if (!seenAny || builder.nodes.size === 0) {
         return { diagram: emptyDiagram(title, 'no nodes found'), refused };
     }

package/lib/render/layer.js

@@ -0,0 +1,91 @@
+/**
+ * Layering: which row each box is in.
+ *
+ * The graph is acyclic by the time it gets here. A layered drawing needs every edge to span at least one layer, so it
+ * always travels downwards, and it wants the total of the layers every edge spans beyond one to be as small as
+ * possible: those are the edges that have to be drawn through a row of placeholders instead of going straight down a
+ * gap.
+ *
+ * Longest paths are the first guess: every source on the top row, every other node one layer below its latest
+ * predecessor. It is feasible and it is not optimal, because it puts every node as high as it can go - a node whose
+ * edges leave it with slack above the boxes it points at is a node that could have moved down and shortened them.
+ * `network-simplex.ts` solves the program the mature layering implementations solve: the ranking that minimises the
+ * total length, found by exchanging edges in a tight tree until no exchange is left that shortens it.
+ *
+ * The initial state is layer zero. It is a node with no predecessor - cycle breaking has turned around every edge
+ * that ran into it - so a source, and every source is a candidate for the top row. The pin is passed to the solver as
+ * a constraint, so the search never trades it away: an initial state that moved down the page would be a machine
+ * diagram read from the wrong end.
+ *
+ * Pure: the graph in, one layer per node out.
+ */
+import { minimumLength } from './network-simplex.js';
+/**
+ * The longest-path ranking: the highest layer each node can possibly take.
+ *
+ * Every source starts on layer zero and every other node one below its latest predecessor, which is the shortest
+ * ranking that is feasible at all - and, because no node can then move up, the starting point the exchange search
+ * needs. A node the walk never reaches is part of a cycle and is put on layer zero: the stage is defined on a DAG,
+ * and a graph that arrived cyclic is laid out as far as it can be rather than losing the boxes of the cycle.
+ */
+function longestPath(ids, edges, index) {
+    const rank = new Array(ids.length).fill(0);
+    const pending = new Array(ids.length).fill(0);
+    const outgoing = ids.map(() => []);
+    for (const edge of edges) {
+        outgoing[index.get(edge.from)].push(index.get(edge.to));
+        pending[index.get(edge.to)] += 1;
+    }
+    const queue = [];
+    for (let node = 0; node < ids.length; node += 1)
+        if (pending[node] === 0)
+            queue.push(node);
+    for (let head = 0; head < queue.length; head += 1) {
+        const node = queue[head];
+        for (const target of outgoing[node]) {
+            rank[target] = Math.max(rank[target], rank[node] + 1);
+            pending[target] -= 1;
+            if (pending[target] === 0)
+                queue.push(target);
+        }
+    }
+    return rank;
+}
+export function layer(graph, edges) {
+    // A model is data: the same box may be written twice, and an edge may name a box this level does not have.
+    const ids = [];
+    const seen = new Set();
+    for (const node of graph.nodes) {
+        if (seen.has(node.id))
+            continue;
+        seen.add(node.id);
+        ids.push(node.id);
+    }
+    const index = new Map(ids.map((id, offset) => [id, offset]));
+    const forward = edges.filter((edge) => index.has(edge.from) && index.has(edge.to) && edge.from !== edge.to);
+    const rankEdges = forward.map((edge) => ({
+        from: index.get(edge.from),
+        to: index.get(edge.to),
+        minLength: 1,
+        weight: 1,
+    }));
+    // The pin only means something for a node that could be on the top row. A node with a predecessor cannot be: it is
+    // forced below it, and no ranking puts it first while keeping the edge that points at it.
+    let pinned;
+    if (graph.init !== undefined && index.has(graph.init)) {
+        const start = index.get(graph.init);
+        const forced = forward.some((edge) => edge.to === graph.init);
+        if (!forced)
+            pinned = start;
+    }
+    const rank = minimumLength({ count: ids.length, edges: rankEdges, start: longestPath(ids, forward, index), ...(pinned === undefined ? {} : { pinned }) });
+    const layers = [];
+    for (const [offset, id] of ids.entries()) {
+        const depth = rank[offset];
+        while (layers.length <= depth)
+            layers.push([]);
+        layers[depth].push(id);
+    }
+    const layerOf = new Map(ids.map((id, offset) => [id, rank[offset]]));
+    return { layers, layerOf };
+}

package/lib/render/layout.js

@@ -1,28 +1,26 @@
 /**
- * Ranks for a machine, and the order of states within each rank.
+ * The graph the layout stages agree on, and the order they start from.
  *
- * Breadth-first from the initial state decides the row: the layout a reader expects, and the one a layered
- * drawing asks for - edges mostly flow down, and a state's row is how far it is from the start. A state
- * nothing reaches goes in a block of its own rather than being dropped.
+ * A layout stage has no business knowing what a diagram is: it sees boxes with a size and edges
+ * between them. That is what `LayoutGraph` is, and it is the whole vocabulary the pipeline shares -
+ * cycle breaking reads it, layering writes layers, ordering and coordinate assignment read those.
  *
- * Within a row, states keep the order breadth-first found them in: a row is filled by walking the row above
- * left to right, so a state already sits under the parent that discovered it. A barycentre pass was written
- * and removed - with breadth-first insertion it could never move a state, so it was complexity without an
- * observable effect.
+ * `rankStates` stays: it is the breadth-first order a source's own reading suggests, and it seeds
+ * the ordering stage with the discovery order instead of whatever order the parser happened to
+ * collect. It no longer decides which row a state is in - `layer.ts` does that now - so the rows it
+ * returns are only a first guess at the left-to-right order.
  *
- * Pure, and asserted on the rows themselves.
+ * Pure, and asserted on the answer itself.
  */
 export function rankStates(nodes, edges, init) {
     const ids = nodes.map((node) => node.id);
     const known = new Set(ids);
     const start = init !== undefined && known.has(init) ? init : ids[0];
     const outgoing = new Map();
-    const incoming = new Map();
     for (const edge of edges) {
         if (!known.has(edge.from) || !known.has(edge.to))
             continue;
         outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge.to]);
-        incoming.set(edge.to, [...(incoming.get(edge.to) ?? []), edge.from]);
     }
     const depth = new Map();
     if (start !== undefined) {
@@ -50,3 +48,21 @@ export function rankStates(nodes, edges, init) {
     }
     return { rows, unreachable: ids.filter((id) => !depth.has(id)) };
 }
+/**
+ * The left-to-right seed the ordering stage starts from.
+ *
+ * Breadth-first discovery is what a reader expects a drawing to follow, so it is a better first
+ * guess than the order the parser collected. A state nothing reaches has no discovery order and
+ * keeps the order it was written in, after everything that was reached.
+ */
+export function seedOrder(graph) {
+    const ranked = rankStates(graph.nodes, graph.edges, graph.init);
+    const order = new Map();
+    let index = 0;
+    for (const row of ranked.rows)
+        for (const id of row)
+            order.set(id, index++);
+    for (const id of ranked.unreachable)
+        order.set(id, index++);
+    return order;
+}