dsh-model-everything 0.5.0 → 0.5.1

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;

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

@@ -1,22 +1,54 @@
 /**
- * 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.
  */
-import type { DiagramEdge, DiagramNode } from './model.js';
+/** A box to place: an id, and the space its text needs. */
+export interface LayoutNode {
+    id: string;
+    width: number;
+    height: number;
+}
+/** An edge to draw: which two boxes it joins, and which diagram edge it came from. */
+export interface LayoutEdge {
+    /** The index in the diagram's own edge list, so the drawing can report a lane back for it. */
+    index: number;
+    from: string;
+    to: string;
+}
+/** One level of a nested drawing: what is placed together in a single pass of the pipeline. */
+export interface LayoutGraph {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    /** The box that must stay on layer zero, when the source named one. */
+    init?: string;
+}
 export interface Ranked {
     /** The state ids of each row, top to bottom, already ordered left to right. */
     rows: string[][];
     /** States no edge reaches from the initial one. */
     unreachable: string[];
 }
-export declare function rankStates(nodes: DiagramNode[], edges: DiagramEdge[], init: string | undefined): Ranked;
+export declare function rankStates(nodes: ReadonlyArray<{
+    id: string;
+}>, edges: ReadonlyArray<{
+    from: string;
+    to: string;
+}>, init: string | undefined): Ranked;
+/**
+ * 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 declare function seedOrder(graph: LayoutGraph): Map<string, number>;

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

@@ -9,18 +9,35 @@
  */
 /** What a node is, as far as colour is concerned. */
 export type NodeRole = 'normal' | 'error' | 'warning' | 'muted';
+/** The symbol a node is drawn as. UML and Mermaid both distinguish these; the notation decides which one applies. */
+export type NodeShape = 'rect' | 'diamond' | 'cylinder' | 'stadium' | 'circle' | 'subroutine' | 'hexagon';
 export interface DiagramNode {
     id: string;
     /** The text drawn inside the box. Defaults to the id when a notation labelled it. */
     label?: string;
     role: NodeRole;
+    /** Defaults to a rectangle: a node the source gave no shape has no shape to draw. */
+    shape?: NodeShape;
 }
+/**
+ * What an edge's head means, when the notation distinguished it.
+ *
+ * The painter draws the meaning: a plain arrow for an association, a hollow triangle for a generalisation or a
+ * realisation, a filled diamond at the source for a composition, a hollow one for an aggregation, and a dashed
+ * line for the two dependency-flavoured kinds.
+ */
+export type EdgeArrow = 'association' | 'dependency' | 'generalization' | 'realization' | 'composition' | 'aggregation';
 export interface DiagramEdge {
     from: string;
     to: string;
     label: string;
     /** A dashed edge, for notations that distinguish one. */
     dashed?: boolean;
+    /**
+     * The arrow the notation stated. Absent means the plain arrow every edge has been drawn with: a Mermaid edge
+     * states no arrow type, so it carries no field and is drawn exactly as before.
+     */
+    arrow?: EdgeArrow;
 }
 export interface DiagramGroup {
     id: string;

package/lib/types/render/network-simplex.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimum-length ranking: the network simplex of Gansner, Koutsofios, North and Vo (1993).
+ *
+ * The ranking problem: give every node a layer such that each edge spans at least its minimum length, and make the
+ * total of all the slack - the layers every edge spans beyond its minimum - as small as it can be. Slack is what a
+ * reader pays for: an edge that spans three layers has to be drawn through two of them.
+ *
+ * Longest paths are one feasible answer and they are not the best one. They put every node as high as it can
+ * possibly go, which leaves a node whose edges leave it with nothing to do above the boxes it points at. The best
+ * answer is the solution of a linear program, and network simplex is how the mature layering implementations solve
+ * it: hold a *feasible tree* - a spanning tree every edge of which is tight - and a ranking that tightens it, attach
+ * a *cut value* to each tree edge (the weight flowing one way across that cut minus the weight flowing the other),
+ * and while some tree edge has a negative cut value, take it out, let the cheapest edge across its cut in, and move
+ * the ranks so the new edge is tight. The cut value is the rate at which the total length falls as the tree edge is
+ * left out, so every exchange shortens the drawing, and a tree with no negative cut value is the optimum: no single
+ * exchange is left that would shorten it, and for this program that is the definition of optimal.
+ *
+ * Three things are done differently from the paper, each because this graph is not the paper's graph:
+ *
+ * - **Components are solved one at a time.** The ranking is translation invariant, so two components that share no
+ *   edge can be laid out apart from each other; each is solved on its own and its top row is then numbered zero.
+ * - **A node may be pinned to the top.** A state machine has an initial state and a reader expects it first, so the
+ *   stage can name one node that must be on the topmost layer: a zero-length, zero-weight constraint edge runs from
+ *   it to every other node of its component (`rank(v) >= rank(pinned)`), and the ranking is minimised subject to that.
+ *   The constraint costs length when the free optimum would have put the pinned node below another source, and that
+ *   price is what "the initial state is first" means.
+ * - **The iteration is capped.** A degenerate exchange (one that moves nothing) is legal and in theory can go round
+ *   in circles. The cap turns that into a ranking that is feasible and no worse than where it started.
+ *
+ * Pure, and generic in the ranking program: no ids, no sizes, no drawing.
+ */
+/** One edge of the ranking program: two layers, how far apart they may be, and what one layer of slack costs. */
+export interface RankEdge {
+    from: number;
+    to: number;
+    /** The least number of layers this edge may span. One for an edge that is drawn, zero for a constraint. */
+    minLength: number;
+    /** What one extra layer on this edge costs. Zero for a constraint, which must hold but is not worth shortening. */
+    weight: number;
+}
+export interface RankProblem {
+    count: number;
+    edges: RankEdge[];
+    /** A feasible ranking to start from: it already gives every edge at least its minimum length. */
+    start: number[];
+    /**
+     * The node that has to sit on the topmost layer, when the source named one.
+     *
+     * It has to be a node nothing points at, or no ranking can hold it at the top - a predecessor forces it down. The
+     * constraint is dropped when the start ranking cannot satisfy it.
+     */
+    pinned?: number;
+}
+export declare function minimumLength(problem: RankProblem): number[];

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

@@ -0,0 +1,27 @@
+/**
+ * Ordering: the left-to-right order of each layer.
+ *
+ * The layer a box is in is fixed by now; the only freedom left is the order inside each layer, and that order decides
+ * how many edges cross. A crossing is counted on a pair of adjacent layers: two edges between the same two layers
+ * cross when their end points are in opposite order on the top and the bottom.
+ *
+ * The method is the one every layered layout uses. A median sweep takes each layer in turn and sorts it by the median
+ * position of its neighbours in the layer just visited - down the drawing, then up. A down sweep alone settles each
+ * layer against the one above it and can be undone by the next; alternating is what makes the passes converge.
+ *
+ * The median is a good guess, not a search. Greedy switch is the search: try swapping two neighbours in a layer, keep
+ * the swap if the total crossing count falls, and stop when a whole pass finds nothing. That is where a crossing the
+ * median cannot see gets removed.
+ *
+ * Pure: layers of ids in, layers of ids out, plus the crossing count that justified them.
+ */
+import type { Chain } from './dummy.js';
+export interface Ordered {
+    /** The same layers, each in its final order. */
+    layers: string[][];
+    /** The number of crossings between adjacent layers left by the ordering. */
+    crossings: number;
+}
+/** How many pairs of edges between adjacent layers cross. */
+export declare function countCrossings(layers: string[][], chains: Chain[]): number;
+export declare function order(seedLayers: string[][], chains: Chain[], seed?: Map<string, number>): Ordered;