dsh-model-everything 0.5.0 → 0.5.2

package/lib/render/trunk.js

@@ -0,0 +1,213 @@
+/**
+ * Fan-in trunks: a batch of arrows into one box from one side, drawn as one bundle.
+ *
+ * A node that four relations point at is drawn as four ports along its side and four lines converging on it. Each
+ * line is right on its own, and the picture is wrong: the bundle reads as a comb, and a reader counts ports to count
+ * arrows. The mature layered implementations solve this by merging the edges - ELK's *Merge Edges* with junction
+ * points, Graphviz's `concentrate` - and the shape they produce is one straight run outside the node, with a branch
+ * joining it wherever a separate edge arrives, and one shared stub into the node.
+ *
+ * This module decides only which ends may merge, where the shared run sits and which of the branches becomes the
+ * shared entry. It is pure geometry over boxes and ports, so the rules can be asserted without a canvas; the painter
+ * draws the answer.
+ *
+ * The rules, and why each one exists:
+ *
+ * - **One target, one entry side.** Edges that arrive from different sides are travelling in different directions,
+ *   and a trunk that changed axis would be two trunks.
+ * - **The exit faces the trunk.** A branch arrives at the trunk along the direction its own port leaves by, so the
+ *   trunk is outside the source as well as outside the target. An end that does not face the trunk is not merged: it
+ *   would have to turn before it got there, which is the bend the merge was supposed to save.
+ * - **Distinct sources, three or more.** Two merged edges read as one thick line. A pair of relations about one pair
+ *   has its own, older rule - they stay visibly apart - and that rule is the distinct-source rule here: two
+ *   statements about one pair share their source, so they can never both be a branch of one trunk.
+ * - **One arrow semantics.** A composition and an association are different statements about the relation; drawn on
+ *   one trunk they would be read as one statement. Ends that disagree on their arrow are not merged with each other.
+ * - **Clear of every box.** A trunk that crosses a box is the same defect as a route that does, and it is worse here
+ *   because it is drawn once for the whole bundle.
+ * - **One trunk per line.** Two groups whose trunks would be drawn on one line would read as one bundle between two
+ *   unrelated targets, so the later group is refused.
+ *
+ * The shared entry is the middle of the target's side. A bundle enters the target through one port, and a side that
+ * carries one port is centred on it, so the trunk runs to the middle and every branch joins it there: the branches
+ * that are not in the middle bend, which is the price of one entry that reads as centred rather than one that leans
+ * towards whichever branch happened to arrive straightest.
+ *
+ * Merging forces every branch but one to bend twice, so an unmerged drawing of `k` straight branches costs
+ * `2 * (n - k)` bends and a merged one costs `2 * (n - 1)`; the branch nearest the middle is the lead because it is
+ * the only one that can still reach the shared port without a horizontal leg, and on a target whose middle happens
+ * to fall on a branch's own line that branch is free, as before.
+ *
+ * What this module does not decide: the colour of a branch, the text of its label, and how a branch's own route
+ * reaches the trunk. Those belong to the painter.
+ */
+import { crossesBox, normalOf, ROUTE_STUB } from './route.js';
+/** The least a trunk is worth drawing for: two merged edges read as one thick line. */
+const TRUNK_MIN_EDGES = 3;
+/** Does this side move along the page's vertical axis? A run on it is horizontal. */
+function isVerticalSide(side) {
+    return side === 'top' || side === 'bottom';
+}
+/**
+ * Where the trunk outside a box sits.
+ *
+ * The same stub the router leaves before it turns, so the bundle starts exactly where a single route would have
+ * turned: about `ROUTE_STUB` outside the target, square to the side it enters.
+ */
+function trunkAt(box, side) {
+    if (side === 'top')
+        return box.y - ROUTE_STUB;
+    if (side === 'bottom')
+        return box.y + box.height + ROUTE_STUB;
+    if (side === 'left')
+        return box.x - ROUTE_STUB;
+    return box.x + box.width + ROUTE_STUB;
+}
+/** The coordinate a point takes along the side it sits on: where along that side the port is. */
+function alongSide(point, side) {
+    return isVerticalSide(side) ? point.x : point.y;
+}
+/** The coordinate a point takes on its side's outward normal: the axis a trunk outside that side moves on. */
+function alongNormal(point, side) {
+    return isVerticalSide(side) ? point.y : point.x;
+}
+/** Does the port on `side` travel toward the trunk at `at`? A branch only merges into a trunk it moves toward. */
+function facesTrunk(point, side, at) {
+    const normal = normalOf(side);
+    const outward = isVerticalSide(side) ? normal.y : normal.x;
+    return (at - alongNormal(point, side)) * outward > 0.5;
+}
+/** The group an edge end belongs to: its target, the side it enters by, and the arrow it means. */
+function keyOf(end) {
+    return end.to + '\u0000' + end.entry + '\u0000' + (end.arrow ?? '');
+}
+/** Is this axis-aligned segment clear of every box it does not attach to? */
+function clearSegment(boxes, skip, x1, y1, x2, y2) {
+    for (const box of boxes) {
+        if (skip.includes(box))
+            continue;
+        if (crossesBox(x1, y1, x2, y2, box))
+            return false;
+    }
+    return true;
+}
+/** Would this run lie on the line of an accepted trunk and share a stretch of it? */
+function onOneLine(group, side, at, low, high) {
+    if (isVerticalSide(group.side) !== isVerticalSide(side))
+        return false;
+    if (group.at !== at)
+        return false;
+    return Math.min(group.to, high) - Math.max(group.from, low) > 0.5;
+}
+/**
+ * Decide which ends merge, and where each accepted trunk runs.
+ *
+ * Ends that cannot merge are simply absent from the plan; the painter draws them as it always has. Groups are
+ * ordered by the first member the source wrote, so the answer does not depend on map iteration order.
+ */
+export function planTrunks(input) {
+    const groups = [];
+    const groupOf = new Map();
+    // Per edge first: the cheap rules. An end that fails one of them cannot join any group, so it never reaches the
+    // count that decides whether a group is worth drawing.
+    const buckets = new Map();
+    for (const end of input.ends) {
+        if (end.runY === undefined)
+            continue;
+        // The branch approaches the trunk along its own exit normal, so the two ends must move on one axis: a mixed pair
+        // would have to turn before it reached the trunk, which is the bend the merge exists to save.
+        if (isVerticalSide(end.exit) !== isVerticalSide(end.entry))
+            continue;
+        const source = input.boxOf(end.from);
+        const target = input.boxOf(end.to);
+        if (source === undefined || target === undefined)
+            continue;
+        if (source === target)
+            continue;
+        const exit = input.exitPortOf(end.index);
+        if (exit === undefined)
+            continue;
+        const at = trunkAt(target, end.entry);
+        if (!facesTrunk(exit, end.exit, at))
+            continue;
+        const candidate = { end, source, target, at, exit, branch: alongSide(exit, end.exit) };
+        const key = keyOf(end);
+        const list = buckets.get(key);
+        if (list === undefined)
+            buckets.set(key, [candidate]);
+        else
+            list.push(candidate);
+    }
+    for (const list of buckets.values()) {
+        // A pair of relations about one node is not two branches: the pair's own rule keeps them visibly apart, and both
+        // of them name the same source, so dropping the duplicated source drops the whole pair. Neither joins, and the
+        // group keeps the singles.
+        const bySource = new Map();
+        for (const candidate of list) {
+            const seen = bySource.get(candidate.end.from);
+            if (seen === undefined)
+                bySource.set(candidate.end.from, [candidate]);
+            else
+                seen.push(candidate);
+        }
+        const members = list.filter((candidate) => bySource.get(candidate.end.from).length === 1);
+        if (members.length < TRUNK_MIN_EDGES)
+            continue;
+        const target = members[0].target;
+        const side = members[0].end.entry;
+        const at = members[0].at;
+        // The shared entry is the middle of the target's side. A side that carries one port is centred on it, and a bundle
+        // enters through one port, so the run reaches the middle rather than whichever branch asked for the middle first.
+        const entryAlong = isVerticalSide(side) ? target.x + target.width / 2 : target.y + target.height / 2;
+        // The lead is the branch nearest that middle: the only member that can reach the shared port without a lateral
+        // leg. The source's order breaks a tie, so the answer does not depend on map iteration.
+        let lead = members[0];
+        for (const candidate of members) {
+            if (Math.abs(candidate.branch - entryAlong) < Math.abs(lead.branch - entryAlong) - 1e-9)
+                lead = candidate;
+        }
+        // The run: the whole stretch the branches and the one port span, so every branch joins a line that reaches it.
+        let low = entryAlong;
+        let high = entryAlong;
+        for (const candidate of members) {
+            low = Math.min(low, candidate.branch);
+            high = Math.max(high, candidate.branch);
+        }
+        // Clearance. The run is checked against every box but the target; each branch's own drop is checked against every
+        // box but its source and the target. The drop leaves a port square to its side, so those are the only two boxes it
+        // can legitimately touch.
+        const vertical = isVerticalSide(side);
+        const run = vertical ? [low, at, high, at] : [at, low, at, high];
+        if (!clearSegment(input.boxes, [target], run[0], run[1], run[2], run[3]))
+            continue;
+        let blocked = false;
+        for (const candidate of members) {
+            // The drop: from the branch's own port to the point where it meets the trunk, along its exit normal.
+            const drop = vertical
+                ? [candidate.branch, candidate.exit.y, candidate.branch, at]
+                : [candidate.exit.x, candidate.branch, at, candidate.branch];
+            if (!clearSegment(input.boxes, [candidate.source, target], drop[0], drop[1], drop[2], drop[3]))
+                blocked = true;
+        }
+        if (blocked)
+            continue;
+        // Two trunks on one line would be drawn as one bundle. The first group keeps the line; the later one travels alone.
+        if (groups.some((group) => onOneLine(group, side, at, low, high)))
+            continue;
+        const id = groups.length;
+        groups.push({
+            id,
+            target: members[0].end.to,
+            side,
+            at,
+            entryAlong,
+            from: low,
+            to: high,
+            lead: lead.end.index,
+            members: members.map((candidate) => candidate.end.index),
+        });
+        for (const candidate of members)
+            groupOf.set(candidate.end.index, id);
+    }
+    return { groups, groupOf };
+}

package/lib/render/wrap.js

@@ -0,0 +1,87 @@
+/**
+ * Wrapping: turning one endless column into a page.
+ *
+ * A chain of twelve boxes has twelve layers, and layering alone draws it as a single column taller than anything a
+ * reader can take in - a strip, not a drawing. Graphviz and ELK both answer this with a wrapping pass: cut the layer
+ * sequence into bands and stand the bands side by side, so reading order becomes "down the page, then the next
+ * column", the way text wraps.
+ *
+ * The cut is chosen, not guessed: each candidate number of bands is scored by how close the packed page gets to the
+ * aspect ratio a page and a landscape screen share, and the best one wins. A drawing that is already close to that
+ * shape is left alone - wrapping exists for the strip, not for every tall drawing.
+ *
+ * Pure: layer sizes in, band ranges and offsets out. The caller applies them.
+ */
+/** The aspect ratio a page and a landscape screen share. */
+const PAGE_ASPECT = 1.6;
+/** A drawing shorter than this many layers is read better stacked, whatever its proportions. */
+const MIN_LAYERS_TO_WRAP = 4;
+/** A drawing that is not this tall relative to its width is not a strip. */
+const STRIP_RATIO = 2;
+/** The height of a run of layers with the gap between them. */
+function runHeight(layerHeight, first, last, gap) {
+    let total = 0;
+    for (let index = first; index <= last; index += 1) {
+        total += layerHeight[index];
+        if (index < last)
+            total += gap;
+    }
+    return total;
+}
+/** The width of a run of layers: the widest layer sets it. */
+function runWidth(layerWidth, first, last) {
+    let widest = 0;
+    for (let index = first; index <= last; index += 1)
+        widest = Math.max(widest, layerWidth[index]);
+    return widest;
+}
+/** How far the packed page is from the target shape, in log space so half and double count the same. */
+function shapeError(width, height, aspect) {
+    if (width <= 0 || height <= 0)
+        return Infinity;
+    const ratio = Math.max(width, height) / Math.min(width, height);
+    return Math.abs(Math.log(ratio / aspect));
+}
+export function planBands(layerWidth, layerHeight, gap, aspect = PAGE_ASPECT) {
+    const count = layerWidth.length;
+    if (count === 0)
+        return { bands: [], width: 0, height: 0 };
+    const single = {
+        bands: [{ first: 0, last: count - 1, offsetX: 0 }],
+        width: runWidth(layerWidth, 0, count - 1),
+        height: runHeight(layerHeight, 0, count - 1, gap),
+    };
+    if (count < MIN_LAYERS_TO_WRAP || single.height <= single.width * STRIP_RATIO)
+        return single;
+    const columnGap = gap * 2;
+    let best = single;
+    let bestError = shapeError(single.width, single.height, aspect);
+    for (let bands = 2; bands < count; bands += 1) {
+        const base = Math.floor(count / bands);
+        const extra = count % bands;
+        const ranges = [];
+        let cursor = 0;
+        for (let band = 0; band < bands; band += 1) {
+            const size = base + (band < extra ? 1 : 0);
+            ranges.push({ first: cursor, last: cursor + size - 1 });
+            cursor += size;
+        }
+        let width = columnGap * (bands - 1);
+        let height = 0;
+        for (const range of ranges) {
+            width += runWidth(layerWidth, range.first, range.last);
+            height = Math.max(height, runHeight(layerHeight, range.first, range.last, gap));
+        }
+        if (shapeError(width, height, aspect) >= bestError)
+            continue;
+        const planned = [];
+        let offsetX = 0;
+        for (const range of ranges) {
+            planned.push({ first: range.first, last: range.last, offsetX });
+            offsetX += runWidth(layerWidth, range.first, range.last) + columnGap;
+        }
+        best = { bands: planned, width, height };
+        bestError = shapeError(width, height, aspect);
+    }
+    return best;
+}

package/lib/types/render/channels.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Channel assignment: where the vertical lanes and the horizontal runs between two rows go.
+ *
+ * The stages before this one decide where the boxes are, and the painter decides what a box looks like. What is left
+ * is the space between two rows, and an edge that decides that space alone will collide with the next one: every long
+ * edge has to cross a row somewhere, and every edge whose two ends are not vertically aligned needs one horizontal run
+ * inside the gap it crosses. Chosen independently, two runs land on one height and read as a junction, and a run
+ * sweeps across a vertical another edge is already using.
+ *
+ * So this stage assigns both, after the boxes have settled and before anything is drawn:
+ *
+ * - **A lane's x.** A long edge owns one vertical lane through the rows it crosses. The x is a position no box
+ *   occupies in any of those rows, and lanes keep the order their dummies have in the ordering, so two lanes never
+ *   share an x inside one gap. Alignment is worth a detour: a lane that lands inside a box's own port span turns a
+ *   four-bend staircase into a straight drop, so alignment comes before distance from the proposed position.
+ * - **A run's y.** The horizontal runs inside one gap are stacked at distinct heights - Graphviz's virtual nodes - so
+ *   two runs never lie on one line, and a nested run stays near the box it leaves.
+ *
+ * Pure: rows, chains and coordinates in; lane positions and run heights out.
+ */
+import type { Chain } from './dummy.js';
+/** A box, as far as routing is concerned: only a box can move a lane. */
+export interface ChannelBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ChannelInput {
+    /** The ordered rows, dummies included: a lane keeps its dummy's order. */
+    layers: string[][];
+    /** Every edge's chain, from the layout source to the layout target. */
+    chains: Chain[];
+    /** A dummy instance, and the lane it belongs to. */
+    chainOf: ReadonlyMap<string, string>;
+    /** The boxes that block a lane. A dummy has none. */
+    boxes: ReadonlyMap<string, ChannelBox>;
+    /** The top of each row, and how tall it is. */
+    layerY: number[];
+    layerHeight: number[];
+    /** What coordinate assignment proposed for each lane. */
+    laneX: ReadonlyMap<string, number>;
+}
+export interface ChannelOptions {
+    /** How far a lane stays from a box in a row it crosses. */
+    clearance: number;
+    /** The narrowest two lanes sharing a gap may be. */
+    spacing: number;
+}
+/** One long edge's lane: the x of its vertical run, and the height of a run in each gap it crosses. */
+export interface LaneChannel {
+    x: number;
+    y: number[];
+}
+export interface ChannelPlan {
+    /** By diagram edge index: the lane a long edge reserved, with one corridor height per gap it crosses. */
+    lanes: Map<number, LaneChannel>;
+    /** By diagram edge index: the height of the one run an edge between two adjacent rows needs. */
+    runs: Map<number, number>;
+}
+/** How far a port sits from a box's corner. The painter places ports from this same number. */
+export declare const PORT_INSET = 10;
+export declare function assignChannels(input: ChannelInput, options: ChannelOptions): ChannelPlan;

package/lib/types/render/components.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The two decompositions a drawing needs before it can be packed.
+ *
+ * **Weakly connected components.** Two subgraphs with no edge between them are two drawings that happen to share a
+ * page. Laying them out together makes them share one set of layers, so the wider one sets every column width and
+ * the narrower one is squeezed beside it; moving one moves the other. Split first, lay each out on its own, then pack
+ * the rectangles.
+ *
+ * **Packing.** A pile of rectangles has to become a page. The target is the aspect ratio a page and a screen share -
+ * 1.6 - and a shelf packer is enough to get there: sort by height, fill a shelf until the next rectangle would make
+ * the drawing wider than the page it is aiming at, then start the next shelf. No overlap, and a deterministic order,
+ * so the same rectangles always pack the same way.
+ *
+ * Pure, and asserted on the rectangles themselves.
+ */
+export interface SizedRectangle {
+    width: number;
+    height: number;
+}
+export interface PackedRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The nodes of each weakly connected component, in the order the nodes were written.
+ *
+ * An isolated node is a component of its own: it is not noise, it is a drawing with nothing joining it, and the
+ * packer is what decides where it goes.
+ */
+export declare function weakComponents(nodes: ReadonlyArray<{
+    id: string;
+}>, edges: ReadonlyArray<{
+    from: string;
+    to: string;
+}>): string[][];
+export interface PackOptions {
+    /** The empty strip kept between two rectangles, on both axes. */
+    gap?: number;
+    /** The page the packer aims at; the drawing comes out as close to it as the rectangles allow. */
+    aspect?: number;
+}
+/**
+ * Pack rectangles into a page of roughly `aspect`, using shelves.
+ *
+ * The shelf width is derived from the total area and the target aspect: that is the width at which a perfect grid
+ * would have the wanted shape, so a shelf that fills it lands near the target. Rectangles are taken tallest first,
+ * which is what keeps a shelf from being mostly empty air above a short rectangle.
+ */
+export declare function packRectangles(rectangles: ReadonlyArray<SizedRectangle>, options?: PackOptions): {
+    placements: PackedRectangle[];
+    width: number;
+    height: number;
+};
+/** The aspect ratio of a box, as a number a reader can compare against the page's. */
+export declare function aspectOf(width: number, height: number): number;

package/lib/types/render/coords.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Coordinate assignment: how far right each box sits. Brandes-Kopf.
+ *
+ * The layers are rows and the order inside them is settled; the only freedom left is the x of each box. Three
+ * properties make a drawing readable:
+ *
+ * - A box sits over what it is connected to, and a chain of boxes sits on one vertical line. Brandes and Kopf get
+ *   this by *aligning*: every box is offered the median of its neighbours in the layer just above (or just below) and
+ *   is joined to that neighbour's block when the join crosses no other edge. A block is then one node of a smaller
+ *   graph, and a box that aligned downwards through five rows comes out as one straight segment.
+ * - Nothing overlaps, and the empty strip between two boxes in a row is the same everywhere. The blocks are compacted
+ *   against each other by the least distance their rows allow, which is a longest path over the block graph: a block
+ *   sits as far left as the block to its left permits, and no further.
+ * - The drawing is balanced rather than packed to one side. Aligning downwards alone would lean everything left, so
+ *   the same two passes are run from the bottom up, and each pair is run once more mirrored left to right. The four
+ *   layouts are then averaged. Averaging is a convex combination, and the separation constraints are linear, so the
+ *   average of four layouts that keep the boxes apart also keeps them apart - the balance is free of overlaps by
+ *   construction. A pass that starts at the top and one that starts at the bottom compact their blocks from opposite
+ *   ends, so each side is first slid onto the origin of the first pass of that side, and only then averaged.
+ *
+ * Three things this module owes the rest of the pipeline rather than the paper:
+ *
+ * - A long edge's dummies share one x. They are one lane, not one point per row, so each lane is collapsed to the mean
+ *   of the x its two ends want - the straight drop a reader follows. Collapsing can put a lane where a box already is,
+ *   so the last pass spends the lane's space: boxes are pushed right past it and never the other way, and a row keeps
+ *   the width its placeholders were given, which is the width a corridor needs when the lane has to go around a box.
+ *   The lane is a proposal either way - the channel stage moves a lane into a free corridor when routing needs it, and
+ *   a box never moves for a lane.
+ * - A lane is not a neighbour to be aligned with. A box that aligned itself to a lane passing through its row would be
+ *   pulled off the boxes it does connect to, which is how a decision with one long edge comes out as a staircase. Lanes
+ *   are placed by the compaction and then by the channel stage, which is where a lane belongs.
+ * - The empty strip between two rows is the caller's, not this module's: the y of a row is a running sum with one gap.
+ *
+ * Pure: layers and chains in, coordinates out.
+ */
+import type { Chain } from './dummy.js';
+export interface Sized {
+    width: number;
+    height: number;
+}
+export interface CoordInput {
+    layers: string[][];
+    chains: Chain[];
+    sizeOf: (id: string) => Sized;
+    /** A dummy instance, and the shared lane it belongs to. */
+    chainOf: ReadonlyMap<string, string>;
+}
+export interface CoordOptions {
+    /** The empty space between two side-by-side boxes. */
+    gap: number;
+    /** The empty strip between two layers. */
+    layerGap: number;
+}
+export interface Coordinates {
+    /** Centre x, keyed by node id and by lane id. A long edge's dummies share one entry. */
+    x: Map<string, number>;
+    /** The top y of each layer. */
+    layerY: number[];
+    layerHeight: number[];
+    layerWidth: number[];
+    width: number;
+    height: number;
+}
+export declare function assignCoordinates(input: CoordInput, options: CoordOptions): Coordinates;

package/lib/types/render/cycle-break.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cycle breaking, in the order a layered layout does it.
+ *
+ * A layered drawing is a drawing of a DAG: an edge that runs back up the page has no layer to go to. The fix is to
+ * lay such an edge out backwards and draw its arrow the way the source wrote it - but *which* edges to turn around
+ * is a decision, and deciding it edge by edge is what makes two back edges of one cycle end up pointing opposite
+ * ways.
+ *
+ * So the graph is decomposed first. Tarjan's algorithm finds the strongly connected components; contracting each to
+ * a node gives the condensation, which is a DAG, so every edge between components already points one way and nothing
+ * between them needs reversing. Only inside a component - where by definition every edge lies on a cycle - is there
+ * an order to choose: the nodes are ranked once, greedily, and every edge inside the component is oriented along that
+ * single ranking. One ranking per component is what "consistently" means: after the pass, every surviving edge of a
+ * component points from a lower rank to a higher one, so the component cannot contain a cycle any more.
+ *
+ * The initial state is a special case: it is layer zero by definition, so an edge that runs into it is a back edge
+ * before the decomposition even starts. Turning those around leaves the state with no predecessor, so the ranking
+ * of its component puts it first and nothing is ever oriented back into it.
+ *
+ * Pure: the same graph in, the same edge directions out.
+ */
+import type { LayoutEdge, LayoutGraph } from './layout.js';
+/** One strongly connected component: a set of nodes that can all reach each other. */
+export interface Component {
+    /** The component's index in the condensation, numbered in topological order. */
+    id: number;
+    members: string[];
+}
+export interface BrokenGraph {
+    /** The same edges, in the same order, with the ones that close a cycle turned around. */
+    edges: LayoutEdge[];
+    /** The diagram edges whose direction the layout changed. */
+    reversed: Set<number>;
+    /** The strongly connected components, numbered in topological order. */
+    components: Component[];
+    componentOf: Map<string, number>;
+    /** Each node's rank inside its own component: every intra-component edge points from a lower rank to a higher. */
+    rank: Map<string, number>;
+    /** The condensation: an edge per pair of components that has at least one edge between them. Always acyclic. */
+    condensation: Array<{
+        from: number;
+        to: number;
+    }>;
+}
+export declare function breakCycles(graph: LayoutGraph): BrokenGraph;

package/lib/types/render/dummy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Dummy nodes: the placeholders a long edge stands on.
+ *
+ * An edge from layer 0 to layer 3 has to cross layers 1 and 2. The router can go around whatever is in the way, but a
+ * drawing reads better if the edge owns a lane through those layers: then ordering can keep other edges off it, and
+ * coordinate assignment can give the whole lane one x. A dummy node is that lane: one per layer the edge crosses.
+ *
+ * A lane is one variable, not one variable per layer. The instances keep their own id (`#d<edge>_<layer>`) so the
+ * ordering stage can sort them inside their layer, and they all point at one lane id (`#e<edge>`) so coordinate
+ * assignment cannot give the same edge three different x values.
+ *
+ * Pure: the layers, the chains, and the map between the two.
+ */
+import type { LayoutEdge } from './layout.js';
+import type { Layering } from './layer.js';
+/** One edge, as the id it passes through in each layer it crosses. */
+export interface Chain {
+    /** The diagram edge's index. */
+    index: number;
+    /** The ids from the layout source to the layout target: the endpoints plus one dummy per crossed layer. */
+    path: string[];
+}
+export interface Augmented {
+    /** The layers with the dummies inserted; each dummy sits in the layer it crosses. */
+    layers: string[][];
+    chains: Chain[];
+    /** A dummy instance's lane id: the variable coordinate assignment shares between a long edge's dummies. */
+    chainOf: Map<string, string>;
+    /** The lane id of every edge that needed dummies. */
+    laneOf: Map<number, string>;
+}
+export declare function addDummies(layering: Layering, edges: LayoutEdge[]): Augmented;

package/lib/types/render/from-plantuml.d.ts

@@ -9,14 +9,20 @@
  * 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 { type Diagram } from './model.js';
 export interface Parsed {

package/lib/types/render/layer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { LayoutEdge, LayoutGraph } from './layout.js';
+export interface Layering {
+    /** The ids of each layer, top to bottom. A layer holds at least one node. */
+    layers: string[][];
+    layerOf: Map<string, number>;
+}
+export declare function layer(graph: LayoutGraph, edges: LayoutEdge[]): Layering;