dsh-model-everything 0.5.0 → 0.5.2

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;

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

@@ -5,21 +5,39 @@
  * sidebar tab - so nothing here knows about pixel size. It emits a content-sized canvas and lets the
  * container scale it: the same numbers serve a 360px card and a 1200px whiteboard.
  *
- * Two placements, chosen by the source:
+ * The drawing is placed by the layered pipeline (`place.ts`), which also says which lane a long edge reserved.
+ * Edges are drawn from where the boxes ended up, in two ways only: a long edge follows its lane as one polyline,
+ * and everything else goes through the orthogonal router. Which side of a box an edge leaves by is read off the
+ * route, not picked by comparing the boxes' centres: a route between two rows arrives vertically, so the endpoint
+ * is snapped onto the top or bottom perimeter in the direction the route approaches. Where along that side it sits
+ * follows the symbol: a rectangle spreads its ports along the side, a cylinder's top port sits on its cap curve, and a
+ * diamond or a circle has four legal points and no side to spread along at all. A side that carries one port is
+ * centred on it, and a side that carries several spreads them symmetrically about the middle; the bend budget comes
+ * first, so a port that is the end of a straight run or of a lane keeps the coordinate its route asked for.
  *
- * - **layered** (no groups): breadth-first rows, forward edges dropping straight down, back edges on a side
- *   channel clear of every box, self loops as small loops. The shape a state machine wants.
- * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block
- *   inside its parent, and the top level stacks. The shape an architecture diagram wants, because a package
- *   whose members float somewhere else on the page is not showing containment at all.
+ * A symbol with discrete points gives each of its edges a point of its own: the point whose outward normal faces the
+ * box at the other end is the one that edge takes, and an edge only shares a point when all four are spoken for. A
+ * node with a run on its side keeps doing what it always did, because there the ports are places on the run and not
+ * points at all. Sharing is the fallback, not the rule: two labelled branches of a decision leave by two vertices.
  *
- * Edges are placed from where the boxes ended up, so neither placement needs to tell the edge code which one
- * ran: "below" is a straight line, "beside" is horizontal, "above" routes around.
+ * An edge's name is drawn on the edge, not beside it: it is anchored at the midpoint of one of the edge's own straight
+ * runs, over a rectangle in the page colour that masks the line behind the text, and it slides along that run when
+ * something is in the way. It tries every run - the longest first - because on a dense drawing the longest one can be
+ * crowded for its whole length while a shorter run of the same edge is clear. A label that can clear nothing still
+ * stays on its edge, takes the place with the fewest collisions, and records what it could not avoid. Labels are
+ * placed after every edge is drawn, because what a label has to avoid is the whole picture.
+ *
+ * Every route is checked before it is drawn, and the assembled drawing is checked once more: a segment may touch no
+ * box except the two the edge terminates at. A route is a proposal - a channel run, a lane, a trunk branch, a wrapped
+ * column's sideways read - and any proposal that would cross a box is handed to the router instead. When even the
+ * router cannot clear a box, the failure is reported on the canvas rather than hidden: a drawing that says which edge
+ * could not be routed is worth more than one that quietly draws it through a box.
  *
  * Pure: a diagram in, shapes out, every decision assertable.
  */
+import { type Box } from './place.js';
 import { type ColourRole, type Palette, type PaletteOptions } from './palette.js';
-import { type Diagram, type DiagramNode } from './model.js';
+import { type Diagram, type DiagramNode, type EdgeArrow, type NodeShape } from './model.js';
 export interface Point {
     x: number;
     y: number;
@@ -30,10 +48,30 @@ export interface BoxShape {
     y: number;
     width: number;
     height: number;
+    /** The lines to draw, already wrapped; `label` keeps the whole text for anything that reads the shape. */
     label: string;
+    lines: string[];
+    /** The symbol to draw. Undefined means a rectangle. */
+    shape?: NodeShape;
     colour: ColourRole;
     initial: boolean;
 }
+/**
+ * Why a label sits where it does.
+ *
+ * A clear label records `collisions: 0` and the run it chose. A label that could clear nothing records the collisions
+ * it could not avoid, so a reader of the drawing (or a test) can tell a crowded drawing from a placement bug. The
+ * label never leaves its own edge to earn any of these numbers.
+ */
+export interface LabelPlacement {
+    /** The straight run it sits on, 0 being the edge's longest. */
+    run: number;
+    /** Everything its mask overlaps: the other labels, boxes and edges it would have had to move off its line to clear. */
+    collisions: number;
+    boxes: number;
+    labels: number;
+    edges: number;
+}
 export interface LinkShape {
     kind: 'link';
     x1: number;
@@ -41,17 +79,43 @@ export interface LinkShape {
     x2: number;
     y2: number;
     label: string;
+    /** The centre the label is drawn on, and therefore a point on the edge itself. */
     labelX: number;
     labelY: number;
     colour: ColourRole;
+    /** A dashed line, when the notation distinguished one. */
+    dashed?: boolean;
+    /** The arrow the source edge stated. Undefined means the plain arrow every edge has been drawn with. */
+    arrow?: EdgeArrow;
+    /** Why the label sits where it does. Undefined on an edge with no label. */
+    labelPlacement?: LabelPlacement;
 }
 export interface PathShape {
     kind: 'path';
     points: Point[];
     label: string;
+    /** The centre the label is drawn on, and therefore a point on the edge itself. */
     labelX: number;
     labelY: number;
     colour: ColourRole;
+    dashed?: boolean;
+    arrow?: EdgeArrow;
+    /** Why the label sits where it does. Undefined on an edge with no label. */
+    labelPlacement?: LabelPlacement;
+}
+/**
+ * A junction dot: the place one branch of a merged bundle meets the bundle's trunk.
+ *
+ * The dot is not decoration. Two lines that meet at a right angle read as a crossing unless one of them is marked as
+ * joining the other, and a bundle whose branches are not marked reads as a set of broken lines rather than a merge.
+ */
+export interface JunctionShape {
+    kind: 'junction';
+    x: number;
+    y: number;
+    colour: ColourRole;
+    /** The trunk the dot belongs to: one dot per branch, one trunk id per bundle. */
+    trunk: number;
 }
 /** A boundary around several states: a package, a layer, a subgraph. */
 export interface GroupShape {
@@ -79,16 +143,99 @@ export interface TitleShape {
     text: string;
     colour: ColourRole;
 }
-export type Shape = GroupShape | BoxShape | LinkShape | PathShape | CaptionShape | TitleShape;
+export type Shape = GroupShape | BoxShape | LinkShape | PathShape | JunctionShape | CaptionShape | TitleShape;
+/** One segment of a drawn route that could not be kept out of a box it does not terminate at. */
+export interface RoutingFailure {
+    /** The edge's index in the diagram. */
+    edge: number;
+    from: string;
+    to: string;
+    /** The box the segment passes through. */
+    box: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
 export interface Canvas {
     width: number;
     height: number;
     shapes: Shape[];
+    /**
+     * Every place a drawn segment still passes through a box it does not terminate at, after every route was checked.
+     *
+     * A drawing should carry none. The field exists for the case where no stage and no router could find a way around:
+     * a route that cannot be drawn honestly is reported here rather than silently drawn through a box.
+     */
+    routingFailures: RoutingFailure[];
+    /** How many edge labels could not be placed clear of every box, label and other edge. */
+    labelCollisions: number;
 }
+/**
+ * How far apart two edges that join the same pair are drawn.
+ *
+ * Wider than the least two ports may sit: two statements about one pair have to read as two lines, and a gap the
+ * port packer would allow is a gap a reader sees as one thick line. Exported so a test can name the pattern.
+ */
+export declare const MULTI_EDGE_SPACING = 20;
 /** Which colour a box earns from its role. One mapping, used by every container. */
 export declare function roleOfNode(node: DiagramNode): ColourRole;
+/**
+ * How tall the mask an edge label is drawn over is.
+ *
+ * Exported because two modules must agree on it: the painter reserves the rectangle when it looks for a clear
+ * place, and the writer draws the rectangle that was reserved. A label with two sizes is a label half masked.
+ */
+export declare const LABEL_HEIGHT = 12;
+/** A straight piece of an edge, as the collision test needs it. */
+interface Segment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** Where a label sits: the point it is centred on, and the rectangle its mask covers. */
+interface LabelSpot {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The point an edge's label is drawn at.
+ *
+ * A label is not furniture parked beside the line: it names the transition, so it sits on the line - anchored on one
+ * of its own straight runs - and the writer masks the stretch of line it covers. Text beside a line can be read as
+ * belonging to whatever it happens to sit next to; text that interrupts its own line reads as part of it.
+ *
+ * The anchor then has to be earned. A mask over a box hides a border, over another label it makes both unreadable,
+ * and over a third edge's line it hides that line. So the label walks along a run in small steps, in both directions
+ * and bounded so its rectangle stays on that run, and takes the first place that is clear. It tries the longest run
+ * first and then the shorter ones: on a dense drawing the longest run can be crowded for its whole length while a
+ * shorter run of the same edge is empty, and a label that gives up after one run leaves the drawing with a collision
+ * it did not have to accept.
+ *
+ * When no run offers a clear place, the label takes the place with the fewest collisions - boxes and other labels
+ * first, because text over a border hides the border and text over text is unreadable, then other edges, which a mask
+ * merely interrupts. It never leaves its own edge: a label moved onto a neighbouring edge is a label that names the
+ * wrong thing. The choice is returned with the label, so a crowded drawing can be told from a placement bug.
+ *
+ * Exported because the choice is pure and worth asserting without a layout: a test can hand it one polyline, one box
+ * and one other route, and read which run it took and what it could not clear.
+ */
+export declare function placeLabel(label: string, points: Point[], boxes: Iterable<Box>, placed: LabelSpot[], otherRoutes: Segment[][]): LabelPlacement & LabelSpot;
+/**
+ * The boxes a polyline passes through other than the two it terminates at.
+ *
+ * This is the drawing's one clearance rule, and it is deliberately written once: a channel run, a lane, a trunk
+ * branch, a wrapped column's sideways step and the router's fallback all have to obey the same test. A box is skipped
+ * only when it is one of the edge's own two ends, so a port that sits inside its own symbol (a cylinder's cap apex)
+ * is allowed and a segment that ends inside somebody else's box is not.
+ */
+export declare function boxesCrossedBy(points: Point[], from: Box, to: Box, boxes: Iterable<Box>): Box[];
 export declare function paintWith(diagram: Diagram, overrides?: Partial<Palette>, options?: PaletteOptions): {
     canvas: Canvas;
     colours: Palette;
 };
 export declare function paint(diagram: Diagram, overrides?: Partial<Palette>): Canvas;
+export {};

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

@@ -1,18 +1,21 @@
 /**
  * Where the boxes go.
  *
- * Two placements, chosen by the source:
+ * The drawing is placed by the layered pipeline, in the order the mature implementations run it: cycle breaking turns
+ * the graph into a DAG, layering gives every box a row, dummy nodes give every long edge a lane, ordering reduces the
+ * crossings, and coordinate assignment decides the x of each lane and box. This module composes those stages; it does
+ * not decide any of them itself. Each stage is a pure module next door, so it can be asserted without a canvas.
  *
- * - **layered** (no groups): breadth-first rows, centred, no containment - the shape a state machine wants.
- * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block inside
- *   its parent, and the top level stacks - the shape an architecture diagram wants, because a package whose
- *   members float somewhere else on the page is not showing containment at all.
+ * Two decompositions sit around the pipeline. A level - the top of the drawing, or the inside of a boundary - is
+ * split into weakly connected components, each laid out on its own and then packed onto the page, so a wide
+ * subgraph cannot squeeze an unrelated one. A boundary is a node in its parent's layer whose size is whatever its
+ * contents need, and its inside is laid out by the same pipeline; that is how nesting is drawn.
  *
- * Split out of the painter so the two questions stay separate: this module decides positions, `paint.ts` decides
- * what to draw between them. A change to edge routing cannot move a box, and a change to nesting cannot move a
- * line.
+ * What comes out is geometry only: a box per node, a rectangle per boundary, and - for a long edge - the lane its
+ * dummies reserved, so the painter can draw one polyline through it instead of searching around the boxes.
  */
-import type { Diagram } from './model.js';
+import { type Measured as TextBox } from './text.js';
+import type { Diagram, DiagramNode } from './model.js';
 /** Geometry of one placed box, before anything is drawn. */
 export type Box = {
     x: number;
@@ -20,20 +23,38 @@ export type Box = {
     width: number;
     height: number;
 };
-/** What a placement returns: every box, every drawn boundary, and how wide the content is. */
+/** A point in the drawing's own coordinates. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** The lane a long edge's dummies reserved, in layout order: from the layout source down to the layout target. */
+export interface Lane {
+    /** One point per gap the edge crosses, at the lane's own x: it keeps its own order, and the painter walks it. */
+    points: Point[];
+    /** True when the layout runs opposite to the source's arrow, so the painter walks the lane backwards. */
+    reversed: boolean;
+}
+/** What a placement returns: every box, every drawn boundary, every reserved lane, and how wide the content is. */
 export interface Placement {
     boxes: Map<string, Box>;
     groupRects: Map<string, Box>;
     width: number;
+    lanes: Map<number, Lane>;
+    /**
+     * The height of the one horizontal run an edge between two adjacent rows needs.
+     *
+     * A run is measured between two rows of the level that produced it. When a row is a boundary, that strip is the space
+     * outside the boundary while the painter draws the boxes inside it, so the run is a proposal rather than a fact: the
+     * painter clears it against every box and hands the edge to the router when a leg would cross one.
+     */
+    runs: Map<number, number>; /** Edges whose two ends ended up in different wrapped columns: they are read across, not down. */
+    across: Set<number>;
 }
-/** Geometry constants shared by both placements. */
+/** Geometry constants in one place: a container with different proportions changes these, not the rules. */
 export declare const MARGIN = 20;
-/** A box wide enough for its label, clamped so a long id cannot dominate the page. */
-export declare const nodeWidth: (label: string) => number;
-/**
- * Place every box of a diagram.
- *
- * The choice of placement is a property of the source, not of the caller: a drawing that declares boundaries is
- * read as containers and gets the tree; one that does not is read as a machine and gets the ranks.
- */
+/** The text a node will draw, measured from its label - the id is what the source called it, not what it says. */
+export declare function textOf(node: DiagramNode): TextBox;
 export declare function place(diagram: Diagram, top: number): Placement;
+/** The aspect ratio of a placement, for the tests that check a drawing is a page and not a strip. */
+export declare function placementAspect(placement: Placement): number;

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

@@ -0,0 +1,77 @@
+/**
+ * Orthogonal edge routing around boxes.
+ *
+ * A straight line between two boxes is right until a third box sits between them; then it is a line drawn through a
+ * component, which reads as a connection that is not there. Graphviz solves this by routing along a visibility
+ * graph and then fitting splines; ELK, yFiles and mxGraph build a *sparse* grid from the boxes' own edges and run
+ * A* over it with a bend penalty. Sparse is the whole trick: a pixel grid is O(pixels²), while the candidate lines
+ * are the coordinate of every box edge plus a margin - O(boxes) per axis.
+ *
+ * So this module does exactly that, in the two steps those routers use:
+ *
+ * 1. **Candidate lines.** Every box contributes four: one lane just outside each side. Together with the anchor
+ *    coordinates they form the grid a route may travel on.
+ * 2. **A* with bends.** Moving along a candidate line costs its length; changing direction costs extra, because a
+ *    route that zig-zags to save three points is harder to follow than one that goes around.
+ *
+ * A route is only computed for an edge that needs it: the cheap straight segment is tried first, and routing is the
+ * fallback. That keeps the common case - a box directly above another - at two points and no search.
+ *
+ * The layered painter mostly does not ask: an edge between two rows and an edge with a lane are both built from the
+ * channel stage's answer, because a route searched on its own cannot know which lanes the other edges already hold.
+ * What is left for this router is the drawing the layers do not describe - an edge across two wrapped columns, an
+ * edge one of whose ends is a boundary - and the fallback when a channel route would meet a box.
+ */
+import type { Point } from './paint.js';
+/** A rectangle an edge may not cross. */
+export interface Obstacle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The four sides a route may leave a box from. */
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+/** The length of the straight run an edge takes before it is allowed to turn. */
+export declare const ROUTE_STUB = 16;
+/** The outward normal of a side: the direction an edge leaves along. */
+export declare function normalOf(side: Side): Point;
+/** A segment crossing a box at all, with a little slack so a route does not shave a corner. */
+export declare function crossesBox(x1: number, y1: number, x2: number, y2: number, box: Obstacle): boolean;
+/** The point on a side of a box, in the middle of that side. */
+export declare function anchor(box: Obstacle, side: Side): Point;
+/**
+ * Which side of `from` an edge leaves by, and which side of `to` it arrives at.
+ *
+ * The side is a property of the drawing, not of the distance between two centres. A layered drawing puts its boxes
+ * in horizontal rows, and an edge between two rows approaches vertically: out of the bottom, into the top, and the
+ * other way round for an edge drawn against the flow. Only two boxes in the same row are joined sideways, and then
+ * the direction of travel decides which side.
+ *
+ * This replaces the old rule, which compared the two centres' dx and dy and picked the larger axis - so an edge
+ * between two rows left through a box's side as soon as the target was far enough sideways, which is the hook a
+ * top-down drawing is read as a defect.
+ */
+export declare function approachSides(from: Obstacle, to: Obstacle): {
+    exit: Side;
+    entry: Side;
+};
+/**
+ * Route from one box to another, going around any box in the way.
+ *
+ * Returns the polyline to draw. When nothing blocks the straight segment, or when every candidate is blocked (a
+ * single box that fills the drawing), the straight line is returned and the caller keeps a two-point shape - an
+ * unroutable edge is still an edge, and drawing it straight is more honest than dropping it.
+ */
+export interface Ports {
+    exit: Point;
+    entry: Point;
+    exitSide: Side;
+    entrySide: Side;
+}
+export declare function routeEdge(from: Obstacle, to: Obstacle, obstacles: Obstacle[], anchors?: Ports): {
+    points: Point[];
+    routed: boolean;
+};
+/** Drop the points in the middle of a straight run: three collinear points are one segment. */
+export declare function simplify(points: Point[]): Point[];

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

@@ -11,7 +11,7 @@
  *
  * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
  */
-import type { Canvas } from './paint.js';
+import { type Canvas } from './paint.js';
 import type { Palette } from './palette.js';
 export declare function toSvg(canvas: Canvas, colours: Palette, label?: string): {
     markup: string;