dsh-model-everything 0.5.1 → 0.6.0

package/src/render/paint.ts

@@ -11,17 +11,27 @@
  * 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.
+ * 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.
  *
  * 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.
  *
- * An edge's name is drawn on the edge, not beside it: it is anchored at the midpoint of the edge's longest straight
- * run, 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. Labels are placed after every edge is drawn, because what a label has to avoid is the
- * whole picture.
+ * 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.
  */
@@ -29,6 +39,7 @@
 import { MARGIN, place, textOf, type Box } from './place.js'
 import { PORT_INSET } from './channels.js'
 import { anchor, approachSides, crossesBox, normalOf, ROUTE_STUB, routeEdge, simplify, type Ports, type Side } from './route.js'
+import { planTrunks, type TrunkEnd, type TrunkGroup, type TrunkPlan } from './trunk.js'
 import { cylinderApex, cylinderCaps, hasDiscretePorts, hexagonCut, stadiumRadius } from './symbol.js'
 import { textWidth } from './text.js'
 import { palette, roleForVerdict, type ColourRole, type Palette, type PaletteOptions } from './palette.js'
@@ -41,6 +52,8 @@ export interface Point {
 
 export interface BoxShape {
   kind: 'box'
+  /** Which node this box is. It travels into the markup, so a reader can target one node by delegation. */
+  id: string
   x: number
   y: number
   width: number
@@ -54,6 +67,23 @@ export interface BoxShape {
   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
@@ -69,6 +99,8 @@ export interface LinkShape {
   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 {
@@ -81,6 +113,23 @@ export interface PathShape {
   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. */
@@ -112,7 +161,7 @@ export interface TitleShape {
   colour: ColourRole
 }
 
-export type Shape = GroupShape | BoxShape | LinkShape | PathShape | CaptionShape | TitleShape
+export type Shape = GroupShape | BoxShape | LinkShape | PathShape | JunctionShape | CaptionShape | TitleShape
 
 /** Which side of each box an edge leaves by and arrives at, and, for a long edge, the lane x it meets there. */
 interface Facing {
@@ -121,10 +170,33 @@ interface Facing {
   at?: number
 }
 
+/** 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
 }
 
 /** Geometry constants in one place: a container with different proportions changes these, not the rules. */
@@ -179,6 +251,23 @@ function packPorts(wanted: number[], low: number, high: number): number[] {
   return placed
 }
 
+/**
+ * Centre a row of ports on the side it sits on.
+ *
+ * The row keeps its order, its gaps and its separation, and is translated as a whole so its outer two ports sit
+ * symmetrically about the middle of the span: two ports become the middle less and plus half their gap, and a longer
+ * row is the same run of places the routing asked for, moved to where the side has room for it. A row that cannot
+ * travel the whole way stops where its last port reaches the end of the span - the alternative is a port off the box.
+ */
+function centreRun(placed: number[], low: number, high: number): number[] {
+  if (placed.length === 0) return placed
+  const first = placed[0] as number
+  const last = placed[placed.length - 1] as number
+  const middle = (low + high) / 2
+  const shift = Math.min(high - last, Math.max(low - first, middle - (first + last) / 2))
+  return shift === 0 ? placed : placed.map((value) => value + shift)
+}
+
 /** Which colour a box earns from its role. One mapping, used by every container. */
 export function roleOfNode(node: DiagramNode): ColourRole {
   if (node.role === 'error') return 'fail'
@@ -246,26 +335,58 @@ interface LabelSpot {
   height: number
 }
 
-/** The point an edge's label is drawn at.
+/** A straight run of an edge: one of the pieces a label may sit on. */
+interface Run {
+  from: Point
+  to: Point
+  /** The run is axis-aligned, so its Manhattan length is its length. */
+  length: number
+  /** Where the run sits in the route, so two equal runs keep the order they are drawn in. */
+  index: number
+}
+
+/** The runs of one edge, longest first. A label prefers the run with the most room. */
+function runsOf(points: Point[]): Run[] {
+  const runs: Run[] = []
+  for (let index = 0; index + 1 < points.length; index += 1) {
+    const from = points[index]
+    const to = points[index + 1]
+    const length = Math.abs(to.x - from.x) + Math.abs(to.y - from.y)
+    if (length < 1) continue
+    runs.push({ from, to, length, index })
+  }
+  return runs.sort((left, right) => right.length - left.length || left.index - right.index)
+}
+
+/**
+ * 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.
  *
- * A label is not furniture parked beside the line: it names the transition, so it sits on the line - anchored at
- * the middle of the longest straight run of its own edge - 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.
  *
- * 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 its own 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 never leaves the run: a label moved onto a neighbouring edge is a label that names the wrong thing.
+ * 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.
  */
-function placeLabel(
+export function placeLabel(
   label: string,
-  from: Point,
-  to: Point,
+  points: Point[],
   boxes: Iterable<Box>,
   placed: LabelSpot[],
-  segments: Segment[],
-): LabelSpot {
+  otherRoutes: Segment[][],
+): LabelPlacement & LabelSpot {
   const width = textWidth(label)
   const height = LABEL_HEIGHT
   const spotAt = (x: number, y: number): LabelSpot => ({ x, y, width, height })
@@ -286,42 +407,60 @@ function placeLabel(
     spot.x - spot.width / 2 < Math.max(segment.x1, segment.x2) + LABEL_PAD &&
     spot.y + spot.height / 2 > Math.min(segment.y1, segment.y2) - LABEL_PAD &&
     spot.y - spot.height / 2 < Math.max(segment.y1, segment.y2) + LABEL_PAD
-  const clearOfBoxes = (spot: LabelSpot): boolean => {
-    for (const box of boxes) if (hitsBox(spot, box)) return false
-    for (const earlier of placed) if (hitsSpot(spot, earlier)) return false
-    return true
+  /** Everything one candidate place overlaps, counted by the thing it covers rather than by the segment that draws it. */
+  const collisionsAt = (spot: LabelSpot, run: number): LabelPlacement => {
+    let boxHits = 0
+    let labelHits = 0
+    let edgeHits = 0
+    for (const box of boxes) if (hitsBox(spot, box)) boxHits += 1
+    for (const earlier of placed) if (hitsSpot(spot, earlier)) labelHits += 1
+    for (const route of otherRoutes) {
+      for (const segment of route) {
+        if (!hitsSegment(spot, segment)) continue
+        edgeHits += 1
+        break
+      }
+    }
+    return { run, collisions: boxHits + labelHits + edgeHits, boxes: boxHits, labels: labelHits, edges: edgeHits }
   }
-  const clearOfEdges = (spot: LabelSpot): boolean => {
-    for (const segment of segments) if (hitsSegment(spot, segment)) return false
-    return true
+
+  const runs = runsOf(points)
+  if (runs.length === 0) {
+    // A route with no straight piece has no line to sit on: keep the label at the route's own point rather than move
+    // it into the air. Only a degenerate route reaches this, and the writer still draws its mask.
+    const point = points[0] ?? { x: 0, y: 0 }
+    return { ...spotAt(point.x, point.y), run: -1, collisions: 0, boxes: 0, labels: 0, edges: 0 }
+  }
+
+  let best: (LabelPlacement & LabelSpot) | undefined
+  for (const [runIndex, run] of runs.entries()) {
+    const dx = run.to.x - run.from.x
+    const dy = run.to.y - run.from.y
+    const ux = dx / run.length
+    const uy = dy / run.length
+    const middle = { x: (run.from.x + run.to.x) / 2, y: (run.from.y + run.to.y) / 2 }
+    // The walk is bounded so the label's own rectangle stays on the run that names it: a mask that hangs off the
+    // end of its segment would be half over the next thing and would not read as sitting on this edge.
+    const along = (Math.abs(ux) * width) / 2 + (Math.abs(uy) * height) / 2
+    const bound = Math.max(0, run.length / 2 - along)
+    const walk: number[] = [0]
+    for (let step = LABEL_STEP; step <= bound + 0.001; step += LABEL_STEP) walk.push(step, -step)
+    for (const offset of walk) {
+      const spot = spotAt(middle.x + ux * offset, middle.y + uy * offset)
+      const placement = collisionsAt(spot, runIndex)
+      // A clear place is the answer, and the first one is the preferred one: the search order is already the
+      // drawing's preference - longest run, own midpoint, then either side.
+      if (placement.collisions === 0) return { ...spot, ...placement }
+      if (
+        best === undefined ||
+        placement.collisions < best.collisions ||
+        (placement.collisions === best.collisions && placement.boxes + placement.labels < best.boxes + best.labels)
+      ) {
+        best = { ...spot, ...placement }
+      }
+    }
   }
-  const middle = { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 }
-  // The run is axis-aligned, so its Manhattan length is its length.
-  const dx = to.x - from.x
-  const dy = to.y - from.y
-  const length = Math.abs(dx) + Math.abs(dy)
-  const ux = dx / length
-  const uy = dy / length
-  // The walk is bounded so the label's own rectangle stays on the run that names it: a mask that hangs off the
-  // end of its segment would be half over the next thing and would not read as sitting on this edge.
-  const along = (Math.abs(ux) * width) / 2 + (Math.abs(uy) * height) / 2
-  const bound = Math.max(0, length / 2 - along)
-  const walk: number[] = [0]
-  for (let step = LABEL_STEP; step <= bound + 0.001; step += LABEL_STEP) walk.push(step, -step)
-  const at = (offset: number): LabelSpot => spotAt(middle.x + ux * offset, middle.y + uy * offset)
-  for (const offset of walk) {
-    const spot = at(offset)
-    if (clearOfBoxes(spot) && clearOfEdges(spot)) return spot
-  }
-  // Nothing on the run is clear of every other edge - two runs may lie side by side for their whole length, and
-  // then no place on one is clear of the other. Covering a neighbour's line is the least of the three: text over
-  // a line still reads, while text over a box hides the box and text over text is unreadable. The label stays
-  // on its own edge, which is the one thing it may not give up.
-  for (const offset of walk) {
-    const spot = at(offset)
-    if (clearOfBoxes(spot)) return spot
-  }
-  return at(0)
+  return best as LabelPlacement & LabelSpot
 }
 
 
@@ -352,11 +491,35 @@ function drawnExtent(shapes: Shape[]): { width: number; height: number } {
       case 'title':
         consider(textWidth((shape as { lines?: string[]; text?: string }).lines?.[0] ?? '') + shape.x, shape.y + 12)
         break
+      case 'junction':
+        // A dot sits on a line that already reaches further than it does: counting it would never widen the canvas.
+        break
     }
   }
   return { width, height }
 }
 
+/**
+ * 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 function boxesCrossedBy(points: Point[], from: Box, to: Box, boxes: Iterable<Box>): Box[] {
+  const crossed: Box[] = []
+  for (let index = 0; index + 1 < points.length; index += 1) {
+    const a = points[index]
+    const b = points[index + 1]
+    for (const box of boxes) {
+      if (box === from || box === to) continue
+      if (crossesBox(a.x, a.y, b.x, b.y, box)) crossed.push(box)
+    }
+  }
+  return crossed
+}
+
 export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, options: PaletteOptions = {}): { canvas: Canvas; colours: Palette } {
   const colours = palette(overrides, options)
   const shapes: Shape[] = []
@@ -387,8 +550,15 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
   const drawn = new Set<string>()
   // A Map iterator is consumed by the first pass: collision checks need a list.
   const boxList = Array.from(boxes.values())
+  /** One drawn edge: the shape, its index in the diagram, and whether its label was fixed rather than placed. */
+  interface DrawnRoute {
+    shape: LinkShape | PathShape
+    edge: number
+    /** A self loop's label is drawn beside the loop by design; the placement pass leaves it alone. */
+    fixed: boolean
+  }
   /** The edges drawn as lines, in paint order: their labels are placed once every one of them is known. */
-  const routes: Array<LinkShape | PathShape> = []
+  const routes: DrawnRoute[] = []
   for (const node of diagram.nodes) {
     // A state id may repeat in a malformed model: the first placement wins and the repeat is skipped.
     if (drawn.has(node.id)) continue
@@ -397,6 +567,7 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     const text = textOf(node)
     shapes.push({
       kind: 'box',
+      id: node.id,
       x: box.x,
       y: box.y,
       width: box.width,
@@ -450,32 +621,173 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     endsAt.set(edge.to, (endsAt.get(edge.to) ?? 0) + 1)
   }
 
+  /**
+   * Where a port may sit on one side of one node, as the interval its coordinate may take.
+   *
+   * This is the per-symbol rule, and it is why the rule lives here: a port slot is chosen in this module, so this is
+   * where the symbol has to be known. A rectangle spreads a port along the side, and a subroutine does the same. A
+   * diamond's side meets its outline at exactly one point - the vertex - so its interval is that point, and a circle's
+   * is its cardinal point; a point is all that side has to give, so two edges on one side share it rather than take
+   * two points in the air. A hexagon's top and bottom are the flat run between the cut corners, and its left and right
+   * are the vertices. A stadium's flat run stops at the end caps, and a cylinder's flat sides are the two vertical
+   * runs, never the caps.
+   *
+   * A zero-width interval is not a failure: the packer keeps every port on it, so a symbol that offers one point on a
+   * side hands that point to every edge that wants it. Which is why a symbol with four points is given one edge per
+   * side first - the point is only shared when the four are taken.
+   */
+  const spanOf = (boxId: string, side: Side, corner: boolean): { low: number; high: number } => {
+    const box = endBox(boxId) as Box
+    const vertical = side === 'top' || side === 'bottom'
+    const middle = vertical ? box.x + box.width / 2 : box.y + box.height / 2
+    const within = (low: number, high: number): { low: number; high: number } => ({ low, high: Math.max(low, high) })
+    switch (shapeOf(boxId)) {
+      // The four vertices of a diamond, and the four cardinal points of an ellipse, are the middles of its sides.
+      case 'diamond':
+      case 'circle':
+        return within(middle, middle)
+      case 'hexagon':
+        return vertical ? within(box.x + hexagonCut(box.width), box.x + box.width - hexagonCut(box.width)) : within(middle, middle)
+      case 'stadium': {
+        const radius = stadiumRadius(box)
+        return vertical ? within(box.x + radius, box.x + box.width - radius) : within(middle, middle)
+      }
+      case 'cylinder': {
+        if (vertical) return within(middle, middle)
+        const cap = cylinderCaps(box).cap
+        return within(box.y + cap, box.y + box.height - cap)
+      }
+      default: {
+        // A rectangle, and a subroutine's doubled side, keep the margins they have always had; `corner` relaxes them
+        // because a side that is crowded uses its corners.
+        const inset = corner ? 2 : vertical ? PORT_INSET : 8
+        return vertical ? within(box.x + inset, box.x + box.width - inset) : within(box.y + inset, box.y + box.height - inset)
+      }
+    }
+  }
+  const clampTo = (boxId: string, side: Side, value: number, corner: boolean): number => {
+    const span = spanOf(boxId, side, corner)
+    return Math.min(span.high, Math.max(span.low, value))
+  }
+  /**
+   * The boundary point a coordinate along one side takes.
+   *
+   * The box's rectangle is the point for every symbol whose side is the box's side. A cylinder's top and bottom are
+   * arcs, so a port there sits on the cap curve's apex - `cap / 4` inside the box, not on the box's own edge.
+   */
+  const pointOn = (boxId: string, side: Side, along: number): Point => {
+    const box = endBox(boxId) as Box
+    if (side === 'left') return { x: box.x, y: along }
+    if (side === 'right') return { x: box.x + box.width, y: along }
+    if (side === 'top') return { x: along, y: shapeOf(boxId) === 'cylinder' ? cylinderApex(box, 'top').y : box.y }
+    return { x: along, y: shapeOf(boxId) === 'cylinder' ? cylinderApex(box, 'bottom').y : box.y + box.height }
+  }
   /** The side each edge end's port is on, where the port is a point rather than a place along a run. */
   const claimed = new Map<string, Side>()
-  const claimedAt = new Map<string, Side[]>()
+  const claimedAt = new Map<string, Array<{ index: number; side: Side }>>()
   const claim = (id: string, index: number, end: 'exit' | 'entry', side: Side): void => {
     claimed.set(endKey(index, end), side)
-    claimedAt.set(id, [...(claimedAt.get(id) ?? []), side])
+    claimedAt.set(id, [...(claimedAt.get(id) ?? []), { index, side }])
+  }
+  /** The sides of one node another edge already holds. An edge is not crowded by its own other end. */
+  const takenSides = (id: string, except: number): Side[] =>
+    (claimedAt.get(id) ?? []).filter((entry) => entry.index !== except).map((entry) => entry.side)
+
+  /** The middle of one side: the coordinate that side's point sits at when nothing has moved it. */
+  const sideMiddle = (box: Box, side: Side): number => (isVerticalSide(side) ? box.x + box.width / 2 : box.y + box.height / 2)
+
+  /** The point a side offers at its middle: a symbol's own point, or the middle of the run it spreads along. */
+  const sidePoint = (boxId: string, side: Side): Point => pointOn(boxId, side, sideMiddle(endBox(boxId) as Box, side))
+
+  /** Does this side face away from the box at the other end? A route leaving it has to come back round its own box. */
+  const facesAway = (box: Box, other: Box, side: Side): boolean => {
+    const out = normalOf(side)
+    const dx = other.x + other.width / 2 - (box.x + box.width / 2)
+    const dy = other.y + other.height / 2 - (box.y + box.height / 2)
+    return out.x * dx + out.y * dy < 0
+  }
+
+  /** The coordinate a free side takes when the other end is pinned: the pinned port's stub, read on the free axis. */
+  const stubAlong = (pinnedId: string, pinnedSide: Side, freeSide: Side): number => {
+    const point = sidePoint(pinnedId, pinnedSide)
+    const out = normalOf(pinnedSide)
+    return isVerticalSide(freeSide) ? point.x + out.x * ROUTE_STUB : point.y + out.y * ROUTE_STUB
+  }
+
+  /** Can this side put a port at `value`? A point-side offers exactly one coordinate; a run offers an interval. */
+  const offers = (boxId: string, side: Side, value: number): boolean => {
+    const span = spanOf(boxId, side, true)
+    return value >= span.low - 0.01 && value <= span.high + 0.01
+  }
+
+  /**
+   * The bend budget a candidate (exit side, entry side) pair spends on the orthogonal route it implies, before a lane
+   * or a router is consulted. The numbers, and what each one is:
+   *
+   *   0  the two stubs share a line: both on vertical sides whose x can be the same, or both on horizontal sides
+   *      whose y can be the same, with each stub pointing the way the edge travels. One straight run, no corner.
+   *   1  an L: the two sides are perpendicular and the one that can still move can be placed exactly where the pinned
+   *      side's stub ends, so the route turns once. It is the rung between the straight run and the Z: an L never
+   *      beats a run that shares a line, and always beats a Z.
+   *   2  a Z: the stubs are perpendicular but cannot meet at one corner, or they are parallel and offset. Out, across,
+   *      in: two corners.
+   *   4  a U: a side faces away from the box at the other end, so the route has to wrap a box - out, round, back
+   *      in. The canonical U has both sides facing away; one is already enough to force the wrap, and a pair that
+   *      has to come back the way it went is never worth a pair that does not.
+   *
+   * "Can be the same" is the symbol's own answer (`spanOf`): a rectangle offers its whole side, a diamond one point, a
+   * cylinder's top the apex of its cap. Two rectangles facing each other therefore share a line wherever they sit; two
+   * diamonds only when their vertices line up. This is a budget, not the final polyline: the router still adds the
+   * length an obstacle demands, and the channel stage still decides which lanes exist.
+   *
+   * A side another edge already holds is charged for the L it costs: the packer has to move this pair's port at least
+   * a port separation along the side, which turns the one corner the pair counted on into a jog. A Z is not charged -
+   * it was already off the line, and a port that moves along its side does not add a corner to it.
+   */
+  const bendBudget = (fromId: string, toId: string, exit: Side, entry: Side, index: number): number => {
+    const from = endBox(fromId) as Box
+    const to = endBox(toId) as Box
+    if (facesAway(from, to, exit) || facesAway(to, from, entry)) return 4
+    if (isVerticalSide(exit) === isVerticalSide(entry)) {
+      // Parallel: a straight run only when the two stubs travel the same way and the sides can meet on one line.
+      const out = normalOf(exit)
+      const into = normalOf(entry)
+      const sameWay = out.x === -into.x && out.y === -into.y
+      const fromSpan = spanOf(fromId, exit, true)
+      const toSpan = spanOf(toId, entry, true)
+      const meet = fromSpan.low <= toSpan.high + 0.01 && toSpan.low <= fromSpan.high + 0.01
+      return sameWay && meet ? 0 : 2
+    }
+    // Perpendicular: one corner when the vertical side can be placed at the horizontal side's stub end.
+    const horizontalId = isVerticalSide(exit) ? toId : fromId
+    const horizontalSide = isVerticalSide(exit) ? entry : exit
+    const verticalId = isVerticalSide(exit) ? fromId : toId
+    const verticalSide = isVerticalSide(exit) ? exit : entry
+    if (!offers(verticalId, verticalSide, stubAlong(horizontalId, horizontalSide, verticalSide))) return 2
+    const crowded = takenSides(fromId, index).includes(exit) || takenSides(toId, index).includes(entry)
+    return crowded ? 2 : 1
   }
 
   /**
-   * The side a discrete port takes: the one whose outward normal points most nearly at the other box.
+   * The side a discrete port takes: the point whose pair with the edge's other end bends least.
    *
-   * The score is the cosine of the angle between the normal and the direction to the other box, so 1 is dead ahead
-   * and the four sides of a diamond rank by how much of the way to the target each one faces. Equal scores are broken
-   * by the point nearest the other box - the port the route has least ground to cover from - and then by the order the
-   * sides are drawn in. That last tie-break is what "the earlier edge keeps the earlier point" means in practice: the
-   * edges are walked in source order, and each one takes the best side still free.
+   * `partner` is the side the other end holds - the side it was claimed, or, until it is claimed, the side the route
+   * approaches by. The bend budget comes first. Equal budgets fall back to the rule that was here before: the cosine
+   * of the outward normal against the direction to the other box, then the point nearest that box, then the ground
+   * between the two points - the small length term. So a case that already read well does not move, and a point that
+   * costs an extra corner loses even when it faces the target more squarely.
    */
-  const bestSide = (id: string, other: Box): Side | undefined => {
+  const bestSide = (id: string, otherId: string, end: 'exit' | 'entry', partner: Side, index: number): Side | undefined => {
     const box = endBox(id) as Box
+    const other = endBox(otherId) as Box
     const centre = { x: box.x + box.width / 2, y: box.y + box.height / 2 }
     const toward = { x: other.x + other.width / 2 - centre.x, y: other.y + other.height / 2 - centre.y }
     const reach = Math.hypot(toward.x, toward.y)
-    const taken = claimedAt.get(id) ?? []
-    let best: { side: Side; score: number; near: number } | undefined
+    const taken = takenSides(id, index)
+    let best: { side: Side; bends: number; score: number; near: number; ground: number } | undefined
     for (const side of PORT_SIDES) {
       if (taken.includes(side)) continue
+      const bends = end === 'exit' ? bendBudget(id, otherId, side, partner, index) : bendBudget(otherId, id, partner, side, index)
       const normal = normalOf(side)
       const score = reach === 0 ? 0 : (normal.x * toward.x + normal.y * toward.y) / reach
       // How far the point is from the other box's rectangle: the nearest port is the one the edge reaches first.
@@ -484,15 +796,69 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
         Math.max(other.x - point.x, 0, point.x - (other.x + other.width)),
         Math.max(other.y - point.y, 0, point.y - (other.y + other.height)),
       )
+      const partnerPoint = anchor(other, partner)
+      const ground = Math.abs(point.x - partnerPoint.x) + Math.abs(point.y - partnerPoint.y)
       const better =
         best === undefined ||
-        score > best.score + 1e-9 ||
-        (Math.abs(score - best.score) <= 1e-9 && near < best.near - 1e-9)
-      if (better) best = { side, score, near }
+        bends < best.bends ||
+        (bends === best.bends &&
+          (score > best.score + 1e-9 ||
+            (Math.abs(score - best.score) <= 1e-9 &&
+              (near < best.near - 1e-9 || (Math.abs(near - best.near) <= 1e-9 && ground < best.ground - 1e-9)))))
+      if (better) best = { side, bends, score, near, ground }
     }
     return best?.side
   }
 
+  /**
+   * The sides an edge leaves and enters by when no claimed point decides either end: the pair the budget likes best.
+   *
+   * Only the two same-kind pairs are offered. Both ends here spread their ports along a side, so the choice is which
+   * side of the box the edge travels on; a pair that turns the corner one side further is the case `bestEnd` decides,
+   * where a claimed point has already fixed the near end. A pair strictly cheaper than the one the route approaches by
+   * wins; an equal pair keeps the approach, which leaves a drawing that was already right exactly as it was.
+   */
+  const bestPair = (fromId: string, toId: string, index: number): { exit: Side; entry: Side } => {
+    const approach = approachSides(endBox(fromId) as Box, endBox(toId) as Box)
+    const pairs: Array<{ exit: Side; entry: Side }> = [
+      { exit: 'bottom', entry: 'top' },
+      { exit: 'top', entry: 'bottom' },
+      { exit: 'right', entry: 'left' },
+      { exit: 'left', entry: 'right' },
+    ]
+    let best = approach
+    let bestBends = bendBudget(fromId, toId, approach.exit, approach.entry, index)
+    for (const pair of pairs) {
+      const bends = bendBudget(fromId, toId, pair.exit, pair.entry, index)
+      if (bends >= bestBends) continue
+      best = pair
+      bestBends = bends
+    }
+    return best
+  }
+
+  /**
+   * The side one end takes when the other end has already been decided: the cheapest of the four.
+   *
+   * The side the route approaches by wins a tie, for the same reason as `bestPair` - a drawing that already read well
+   * does not move for a pair the budget cannot tell apart.
+   */
+  const bestEnd = (id: string, otherId: string, end: 'exit' | 'entry', partner: Side, index: number): Side => {
+    const approach =
+      end === 'exit'
+        ? approachSides(endBox(id) as Box, endBox(otherId) as Box).exit
+        : approachSides(endBox(otherId) as Box, endBox(id) as Box).entry
+    let best = approach
+    let bestBends = end === 'exit' ? bendBudget(id, otherId, approach, partner, index) : bendBudget(otherId, id, partner, approach, index)
+    for (const side of PORT_SIDES) {
+      const bends = end === 'exit' ? bendBudget(id, otherId, side, partner, index) : bendBudget(otherId, id, partner, side, index)
+      if (bends >= bestBends) continue
+      best = side
+      bestBends = bends
+    }
+    return best
+  }
+
   // A side the drawing has already decided is claimed first, because a point there would point the route away from
   // the corridor it has to run in: a long edge leaves by the side its lane starts from, and an edge read across two
   // wrapped columns leaves and arrives on the sides the reading order turns at.
@@ -527,7 +893,12 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
       const id = end === 'exit' ? edge.from : edge.to
       if ((endsAt.get(id) ?? 0) < 2) continue
       if (!hasDiscretePorts(shapeOf(id))) continue
-      const side = bestSide(id, end === 'exit' ? target : source)
+      // The side the other end holds, or will hold if nothing claims it first.
+      const approached = approachSides(source, target)
+      const partner =
+        claimed.get(endKey(index, end === 'exit' ? 'entry' : 'exit')) ??
+        (end === 'exit' ? approached.entry : approached.exit)
+      const side = bestSide(id, end === 'exit' ? edge.to : edge.from, end, partner, index)
       if (side === undefined) continue
       claim(id, index, end, side)
     }
@@ -539,23 +910,25 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     if (source === undefined || target === undefined || edge.from === edge.to) return undefined
     // A wrapped drawing is read in columns: the edge from one column to the next leaves and arrives at the side,
     // which is the direction that reading order travels. A column is always to the right of the one before it.
-    const sides = placement.across.has(index)
-      ? { exit: 'right' as Side, entry: 'left' as Side }
-      : approachSides(source, target)
+    if (placement.across.has(index)) return { exit: 'right', entry: 'left' }
     const lane = placement.lanes.get(index)
-    if (lane === undefined || lane.points.length === 0) {
-      return {
-        exit: claimed.get(endKey(index, 'exit')) ?? sides.exit,
-        entry: claimed.get(endKey(index, 'entry')) ?? sides.entry,
-      }
-    }
     // A lane runs down the page, so its ends face the rows above and below wherever the box centres are.
     const down = target.y > source.y
-    return {
-      exit: claimed.get(endKey(index, 'exit')) ?? (down ? 'bottom' : 'top'),
-      entry: claimed.get(endKey(index, 'entry')) ?? (down ? 'top' : 'bottom'),
-      at: lane.points[0].x,
+    if (lane !== undefined && lane.points.length > 0) {
+      return {
+        exit: claimed.get(endKey(index, 'exit')) ?? (down ? 'bottom' : 'top'),
+        entry: claimed.get(endKey(index, 'entry')) ?? (down ? 'top' : 'bottom'),
+        at: lane.points[0].x,
+      }
     }
+    // No claimed point and no lane: an end that was claimed keeps its point, the other one takes the side the budget
+    // likes best against it; with neither claimed, the pair is chosen together.
+    const exit = claimed.get(endKey(index, 'exit'))
+    const entry = claimed.get(endKey(index, 'entry'))
+    if (exit !== undefined && entry !== undefined) return { exit, entry }
+    if (exit !== undefined) return { exit, entry: bestEnd(edge.to, edge.from, 'entry', exit, index) }
+    if (entry !== undefined) return { exit: bestEnd(edge.from, edge.to, 'exit', entry, index), entry }
+    return bestPair(edge.from, edge.to, index)
   })
   // A long edge's lane is where the whole edge runs, so a fan moves the lane instead of bending the edge twice at its
   // ends. It tries the place that keeps the set evenly spaced first, then its own place moved by the same offset; a
@@ -599,67 +972,6 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
 
   const wanted = new Map<string, number>()
   const slotKey = (boxId: string, side: Side, index: number): string => boxId + ':' + side + ':' + String(index)
-  /**
-   * Where a port may sit on one side of one node, as the interval its coordinate may take.
-   *
-   * This is the per-symbol rule, and it is why the rule lives here: a port slot is chosen in this module, so this is
-   * where the symbol has to be known. A rectangle spreads a port along the side, and a subroutine does the same. A
-   * diamond's side meets its outline at exactly one point - the vertex - so its interval is that point, and a circle's
-   * is its cardinal point; a point is all that side has to give, so two edges on one side share it rather than take
-   * two points in the air. A hexagon's top and bottom are the flat run between the cut corners, and its left and right
-   * are the vertices. A stadium's flat run stops at the end caps, and a cylinder's flat sides are the two vertical
-   * runs, never the caps.
-   *
-   * A zero-width interval is not a failure: the packer keeps every port on it, so a symbol that offers one point on a
-   * side hands that point to every edge that wants it. Which is why a symbol with four points is given one edge per
-   * side first - the point is only shared when the four are taken.
-   */
-  const spanOf = (boxId: string, side: Side, corner: boolean): { low: number; high: number } => {
-    const box = endBox(boxId) as Box
-    const vertical = side === 'top' || side === 'bottom'
-    const middle = vertical ? box.x + box.width / 2 : box.y + box.height / 2
-    const within = (low: number, high: number): { low: number; high: number } => ({ low, high: Math.max(low, high) })
-    switch (shapeOf(boxId)) {
-      // The four vertices of a diamond, and the four cardinal points of an ellipse, are the middles of its sides.
-      case 'diamond':
-      case 'circle':
-        return within(middle, middle)
-      case 'hexagon':
-        return vertical ? within(box.x + hexagonCut(box.width), box.x + box.width - hexagonCut(box.width)) : within(middle, middle)
-      case 'stadium': {
-        const radius = stadiumRadius(box)
-        return vertical ? within(box.x + radius, box.x + box.width - radius) : within(middle, middle)
-      }
-      case 'cylinder': {
-        if (vertical) return within(middle, middle)
-        const cap = cylinderCaps(box).cap
-        return within(box.y + cap, box.y + box.height - cap)
-      }
-      default: {
-        // A rectangle, and a subroutine's doubled side, keep the margins they have always had; `corner` relaxes them
-        // because a side that is crowded uses its corners.
-        const inset = corner ? 2 : vertical ? PORT_INSET : 8
-        return vertical ? within(box.x + inset, box.x + box.width - inset) : within(box.y + inset, box.y + box.height - inset)
-      }
-    }
-  }
-  const clampTo = (boxId: string, side: Side, value: number, corner: boolean): number => {
-    const span = spanOf(boxId, side, corner)
-    return Math.min(span.high, Math.max(span.low, value))
-  }
-  /**
-   * The boundary point a coordinate along one side takes.
-   *
-   * The box's rectangle is the point for every symbol whose side is the box's side. A cylinder's top and bottom are
-   * arcs, so a port there sits on the cap curve's apex - `cap / 4` inside the box, not on the box's own edge.
-   */
-  const pointOn = (boxId: string, side: Side, along: number): Point => {
-    const box = endBox(boxId) as Box
-    if (side === 'left') return { x: box.x, y: along }
-    if (side === 'right') return { x: box.x + box.width, y: along }
-    if (side === 'top') return { x: along, y: shapeOf(boxId) === 'cylinder' ? cylinderApex(box, 'top').y : box.y }
-    return { x: along, y: shapeOf(boxId) === 'cylinder' ? cylinderApex(box, 'bottom').y : box.y + box.height }
-  }
   for (const [index, entry] of facing.entries()) {
     if (entry === undefined) continue
     const edge = diagram.edges[index]
@@ -691,16 +1003,16 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
       exitWanted = clampTo(edge.from, entry.exit, chosen, corner)
       entryWanted = clampTo(edge.to, entry.entry, chosen, corner)
     } else {
-      // The two ports sit on sides of different kinds, which only a discrete point causes. The end that is fixed on
-      // its symbol's point keeps that point's coordinate; the other one sits where the route actually arrives - one
-      // step out of the fixed port along its own normal - so the two legs of the route meet in a straight drop
-      // instead of jogging sideways to reach a middle that the route never passes.
+      // The two ports sit on sides of different kinds, which a discrete point causes. The end that is fixed on its
+      // symbol's point keeps that point's coordinate; the other one sits where the route actually arrives - one step
+      // out of the fixed port along that port's own normal, read on the free side's axis - so the two legs of the
+      // route meet in one corner instead of jogging sideways to reach a middle the route never passes.
       exitWanted = hasDiscretePorts(shapeOf(edge.from))
         ? fromMiddle
-        : clampTo(edge.from, entry.exit, anchor(to, entry.entry).x + normalOf(entry.entry).x * ROUTE_STUB, false) + offset
+        : clampTo(edge.from, entry.exit, stubAlong(edge.to, entry.entry, entry.exit), false) + offset
       entryWanted = hasDiscretePorts(shapeOf(edge.to))
         ? toMiddle
-        : clampTo(edge.to, entry.entry, anchor(from, entry.exit).x + normalOf(entry.exit).x * ROUTE_STUB, false) + offset
+        : clampTo(edge.to, entry.entry, stubAlong(edge.from, entry.exit, entry.entry), false) + offset
     }
     wanted.set(slotKey(edge.from, entry.exit, index), exitWanted)
     wanted.set(slotKey(edge.to, entry.entry, index), entryWanted)
@@ -752,6 +1064,181 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     }
     if (!moved) break
   }
+
+  /**
+   * A batch of arrows into one box from one side is one bundle, not a comb: which ends may merge is the planner's
+   * answer (`trunk.ts` carries the rules), and this module supplies what only it knows - which edges have a run of
+   * their own, and where each port landed.
+   *
+   * The plan is made twice. The first pass, from the ports the packing gave, says which ends merge; the centring rule
+   * below reads it, because a merged branch is drawn into the bundle's one port and that - not its own entry port -
+   * is the coordinate its exit either shares a line with or does not. The second pass is made from the centred ports
+   * and is the plan the drawing uses: the run it lays out is the run of the ports that are actually drawn.
+   */
+  const trunkEnds: TrunkEnd[] = []
+  diagram.edges.forEach((edge, index) => {
+    const entry = facing[index]
+    if (entry === undefined) return
+    const runY = placement.runs.get(index)
+    trunkEnds.push({
+      index,
+      from: edge.from,
+      to: edge.to,
+      exit: entry.exit,
+      entry: entry.entry,
+      ...(edge.arrow === undefined ? {} : { arrow: edge.arrow }),
+      ...(runY === undefined ? {} : { runY }),
+    })
+  })
+  const planFor = (exitPortOf: (index: number) => Point | undefined): TrunkPlan =>
+    planTrunks({
+      ends: trunkEnds,
+      // Only a node's own box is a trunk target: an arrow into a boundary points past it, not at it.
+      boxOf: (id) => boxes.get(id),
+      boxes: boxList,
+      exitPortOf,
+    })
+  /** Where an edge's exit port sits before the centring rule has had its say. */
+  const packedExit = (index: number): Point | undefined => {
+    const entry = facing[index]
+    if (entry === undefined) return undefined
+    const edge = diagram.edges[index] as DiagramEdge
+    const coordinate = placedPort.get(slotKey(edge.from, entry.exit, index))
+    return coordinate === undefined ? undefined : pointOn(edge.from, entry.exit, coordinate)
+  }
+  const planned = planFor(packedExit)
+
+  /**
+   * Does the channel stage's lane pin this port to its own coordinate? A port off its lane is a jog added to the run.
+   * A merged branch has a lane the painter never follows - the branch is drawn from its exit to the trunk - so it is
+   * not pinned by it.
+   */
+  const onLane = (index: number, coordinate: number): boolean => {
+    if (planned.groupOf.has(index)) return false
+    const lane = placement.lanes.get(index)
+    if (lane === undefined || lane.points.length === 0) return false
+    return Math.abs((lane.points[0] as Point).x - coordinate) <= 0.5
+  }
+
+  /**
+   * A side's ports as the centring rule reads them: where they are now, and how far the whole row would move to be
+   * centred. The row is the side, so its ports move together and not one by one.
+   */
+  interface PortRow {
+    boxId: string
+    side: Side
+    /** The edge indexes in the row, in the row's own order, and the coordinate each one sits at. */
+    indexes: number[]
+    at: number[]
+    /** Where each index sits in `at`, so a partner port can be read without searching. */
+    position: Map<number, number>
+    /** How far the whole row travels to be centred. Zero when it already is. */
+    shift: number
+    /** Whether it may travel at all: the fixpoint below only ever takes this away. */
+    allowed: boolean
+  }
+
+  const rows: PortRow[] = []
+  const rowOf = new Map<string, PortRow>()
+  for (const [key, list] of sides) {
+    const [boxId, side] = key.split(':') as [string, Side]
+    const span = spanOf(boxId, side, true)
+    const slots = [...list]
+      .map((entry) => ({ index: entry.index, at: placedPort.get(slotKey(boxId, side, entry.index)) as number }))
+      .sort((left, right) => left.at - right.at || left.index - right.index)
+    const centred = centreRun(
+      slots.map((slot) => slot.at),
+      span.low,
+      span.high,
+    )
+    const first = slots[0] as { index: number; at: number }
+    const row: PortRow = {
+      boxId,
+      side,
+      indexes: slots.map((slot) => slot.index),
+      at: slots.map((slot) => slot.at),
+      position: new Map(slots.map((slot, at) => [slot.index, at] as const)),
+      shift: (centred[0] as number) - first.at,
+      allowed: true,
+    }
+    rows.push(row)
+    rowOf.set(key, row)
+  }
+
+  /** Where a port of a row will sit once the rows that may move have moved. */
+  const movedAt = (row: PortRow, at: number): number => (row.at[at] as number) + (row.allowed ? row.shift : 0)
+
+  /**
+   * The coordinate the port at the other end of this edge sits at, and the row that port belongs to.
+   *
+   * Three ends are not a drawn port of a row: the entry of a merged branch (the bundle has one port), the shared
+   * entry itself (the planner's `entryAlong`), and a partner on a side of the other kind (a discrete symbol's point,
+   * on a different axis). Each is a fixed coordinate or nothing, which is all the pin test needs.
+   */
+  const partnerOf = (boxId: string, side: Side, index: number): { coordinate: number; row?: PortRow; at?: number } | undefined => {
+    const entry = facing[index]
+    if (entry === undefined) return undefined
+    const edge = diagram.edges[index] as DiagramEdge
+    const isExit = edge.from === boxId && entry.exit === side
+    const groupId = planned.groupOf.get(index)
+    if (groupId !== undefined) {
+      // A merged branch ends at the bundle's one port, so its own entry port is not drawn and pins nothing. Its exit
+      // is drawn, and the line it may share is the one to that shared port.
+      if (!isExit) return undefined
+      const group = planned.groups[groupId] as TrunkGroup
+      if (isVerticalSide(side) !== isVerticalSide(group.side)) return undefined
+      return { coordinate: group.entryAlong }
+    }
+    const partnerId = isExit ? edge.to : edge.from
+    const partnerSide = isExit ? entry.entry : entry.exit
+    if (isVerticalSide(side) !== isVerticalSide(partnerSide)) return undefined
+    const coordinate = placedPort.get(slotKey(partnerId, partnerSide, index))
+    if (coordinate === undefined) return undefined
+    const row = rowOf.get(partnerId + ':' + partnerSide)
+    return { coordinate, ...(row === undefined ? {} : { row, at: row.position.get(index) as number }) }
+  }
+
+  /**
+   * A side that carries one port is centred on it; a side that carries several keeps its spread, translated as a
+   * whole so its outer ports sit symmetrically about the middle.
+   *
+   * A port is put where the route wants it, and a side that carries one relation has no spread to fit: the only
+   * reason its port is not in the middle is that the route asked for a coordinate near one end - the far end of the
+   * span, the point a lane runs at. That request is real, and the bend budget decides whether it may be overruled.
+   * A port that shares a line with the port at the other end of its edge is the middle of a straight run, and a port
+   * on a lane is the end of a channel: moving either adds two corners. Every other port moves to where its side has
+   * room, which costs nothing.
+   *
+   * So the bend budget is a fixpoint over rows, not a test per port: a row may move unless that breaks a line it
+   * shares with a port that is staying. Two ends of one straight line may both move when they move by the same
+   * amount - which is what centring both sides of one pair does - so the rows are resolved together, and a row that
+   * is refused takes the lines it shares with it.
+   */
+  for (let pass = 0; pass < rows.length; pass += 1) {
+    let refused = false
+    for (const row of rows) {
+      if (!row.allowed || row.shift === 0) continue
+      const pinned = row.indexes.some((index, at) => {
+        if (onLane(index, row.at[at] as number)) return true
+        const partner = partnerOf(row.boxId, row.side, index)
+        if (partner === undefined) return false
+        // Only a line that exists now can be broken: two ports that already differ are a Z, and moving one end of a Z
+        // along its own side changes where its corners are, not how many.
+        if (Math.abs((row.at[at] as number) - partner.coordinate) > 0.5) return false
+        const partnerAt = partner.row === undefined ? partner.coordinate : movedAt(partner.row, partner.at as number)
+        return Math.abs(movedAt(row, at) - partnerAt) > 0.5
+      })
+      if (!pinned) continue
+      row.allowed = false
+      refused = true
+    }
+    if (!refused) break
+  }
+  for (const row of rows) {
+    if (!row.allowed || row.shift === 0) continue
+    row.indexes.forEach((index, at) => placedPort.set(slotKey(row.boxId, row.side, index), movedAt(row, at)))
+  }
+
   const portOf = (boxId: string, side: Side, edgeIndex: number): Point => {
     const coordinate = placedPort.get(slotKey(boxId, side, edgeIndex)) as number
     return pointOn(boxId, side, coordinate)
@@ -768,17 +1255,12 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     })
   }
 
-  /** The longest straight run of a polyline: where a label has the most room. */
-  const longestRun = (points: Point[]): { from: Point; to: Point } => {
-    let best = { from: points[0], to: points[points.length - 1], length: -1 }
-    for (let index = 0; index + 1 < points.length; index += 1) {
-      const from = points[index]
-      const to = points[index + 1]
-      const length = Math.abs(to.x - from.x) + Math.abs(to.y - from.y)
-      if (length > best.length) best = { from, to, length }
-    }
-    return best
-  }
+  const trunks = planFor((index) => anchorsFor.get(index)?.exit)
+  // The one port each accepted bundle enters by: the middle of the target's side, which is the port the planner
+  // centred on `entryAlong`. A merged entry is one port, so the rule for a side with one port applies to it, and the
+  // target carries one relation's worth of ports however many arrows point at it.
+  const sharedEntry = new Map<number, Point>()
+  for (const group of trunks.groups) sharedEntry.set(group.id, pointOn(group.target, group.side, group.entryAlong))
 
   /** The points a drawn edge passes through, whichever of the two shapes carries it. */
   const pointsOfRoute = (shape: LinkShape | PathShape): Point[] =>
@@ -797,7 +1279,7 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
   }
 
   /** Paint one edge as a polyline. Its label is placed once every edge is drawn; see the pass after the loop. */
-  const paintPath = (edge: DiagramEdge, points: Point[], colour: ColourRole): void => {
+  const paintPath = (edgeIndex: number, edge: DiagramEdge, points: Point[], colour: ColourRole): void => {
     const shape: PathShape = {
       kind: 'path',
       points,
@@ -809,13 +1291,13 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
       ...(edge.arrow === undefined ? {} : { arrow: edge.arrow }),
     }
     shapes.push(shape)
-    routes.push(shape)
+    routes.push({ shape, edge: edgeIndex, fixed: false })
   }
 
   /** Two points are a line and more of them are a polyline; both are an edge carrying a label. */
-  const paintRoute = (edge: DiagramEdge, points: Point[], colour: ColourRole): void => {
+  const paintRoute = (edgeIndex: number, edge: DiagramEdge, points: Point[], colour: ColourRole): void => {
     if (points.length > 2) {
-      paintPath(edge, points, colour)
+      paintPath(edgeIndex, edge, points, colour)
       return
     }
     const exit = points[0]
@@ -834,9 +1316,18 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
       ...(edge.arrow === undefined ? {} : { arrow: edge.arrow }),
     }
     shapes.push(shape)
-    routes.push(shape)
+    routes.push({ shape, edge: edgeIndex, fixed: false })
   }
 
+  /**
+   * Is this route clear of every box it does not terminate at?
+   *
+   * One test, used by every stage. A run, a lane and a trunk branch are proposals made from the layout; when the
+   * proposal meets a box - which happens when the layout reserved a run between two boundaries while the painter
+   * draws the boxes inside them - the proposal is refused and the router gets the edge.
+   */
+  const clearOfBoxes = (points: Point[], from: Box, to: Box): boolean => boxesCrossedBy(points, from, to, boxList).length === 0
+
   /**
    * The polyline through a run: out of one port, across the strip between two rows, and into the other, square to
    * whatever side each port belongs to.
@@ -849,10 +1340,16 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
   const runRoute = (ports: Ports, runY: number): Point[] => {
     const out = isVerticalSide(ports.exitSide) ? 0 : normalOf(ports.exitSide).x * ROUTE_STUB
     const into = isVerticalSide(ports.entrySide) ? 0 : normalOf(ports.entrySide).x * ROUTE_STUB
+    // A sideways port and a vertical one meet where the other port already is, if that is the way the stub points: the
+    // stub is the straight run out of the port, and it is worth more than a stub to avoid the point-wide jog that
+    // meeting at the nominal length leaves behind - a jog the edge would be charged a bend for and a reader for
+    // nothing. Only when the other port is on the far side does the stub have to overshoot.
+    const exitRun = out !== 0 && into === 0 && Math.sign(ports.entry.x - ports.exit.x) === Math.sign(out) ? ports.entry.x : ports.exit.x + out
+    const entryRun = into !== 0 && out === 0 && Math.sign(ports.exit.x - ports.entry.x) === Math.sign(into) ? ports.exit.x : ports.entry.x + into
     const points: Point[] = [ports.exit]
-    if (out !== 0) points.push({ x: ports.exit.x + out, y: ports.exit.y })
-    points.push({ x: ports.exit.x + out, y: runY }, { x: ports.entry.x + into, y: runY })
-    if (into !== 0) points.push({ x: ports.entry.x + into, y: ports.entry.y })
+    if (out !== 0) points.push({ x: exitRun, y: ports.exit.y })
+    points.push({ x: exitRun, y: runY }, { x: entryRun, y: runY })
+    if (into !== 0) points.push({ x: entryRun, y: ports.entry.y })
     points.push(ports.entry)
     return simplify(points)
   }
@@ -875,19 +1372,8 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     return true
   }
 
-  /** Does the route pass through a box it does not attach to? A run is an empty strip; a step out of a side may not be. */
-  const clearsBoxes = (points: Point[], from: Box, to: Box): boolean => {
-    for (let at = 0; at + 1 < points.length; at += 1) {
-      const a = points[at]
-      const b = points[at + 1]
-      for (const box of boxList) {
-        if (box === from || box === to) continue
-        if (crossesBox(a.x, a.y, b.x, b.y, box)) return false
-      }
-    }
-    return true
-  }
-
+  /** Where a branch meets its trunk, one per merged edge. They are drawn after every line, so no line covers one. */
+  const junctions: JunctionShape[] = []
   for (const [edgeIndex, edge] of diagram.edges.entries()) {
     const source = endBox(edge.from)
     const target = endBox(edge.to)
@@ -897,7 +1383,7 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     if (edge.from === edge.to) {
       const x = source.x + source.width
       const y = source.y + source.height / 2
-      shapes.push({
+      const shape: PathShape = {
         kind: 'path',
         points: [
           { x, y: y - 9 },
@@ -913,12 +1399,38 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
         colour,
         ...(edge.dashed === undefined ? {} : { dashed: edge.dashed }),
         ...(edge.arrow === undefined ? {} : { arrow: edge.arrow }),
-      })
+      }
+      shapes.push(shape)
+      routes.push({ shape, edge: edgeIndex, fixed: true })
       continue
     }
 
     const anchors = anchorsFor.get(edgeIndex)
 
+    // A branch of an accepted bundle: out of its own port, square onto the trunk, along the trunk to the bundle's one
+    // port, and in. The last leg is shared with every other branch of the group, so the target is entered once; the
+    // branch still draws its own head and its own label. The junction is recorded where the branch meets the trunk,
+    // because a reader who is not shown the join reads the two lines as one line that was broken. A branch that would
+    // cross a box is refused here as well: the planner checked it, but the painter is the last stage that knows every
+    // box the drawing actually carries.
+    const groupId = trunks.groupOf.get(edgeIndex)
+    if (groupId !== undefined && anchors !== undefined) {
+      const group = trunks.groups[groupId] as TrunkGroup
+      const entry = sharedEntry.get(groupId) as Point
+      const branch: Point[] = isVerticalSide(group.side)
+        ? [anchors.exit, { x: anchors.exit.x, y: group.at }, { x: entry.x, y: group.at }, entry]
+        : [anchors.exit, { x: group.at, y: anchors.exit.y }, { x: group.at, y: entry.y }, entry]
+      const points = simplify(branch)
+      if (clearOfBoxes(points, source, target)) {
+        paintRoute(edgeIndex, edge, points, colour)
+        // The join itself, read off the two ports rather than off the emitted points: a branch that drops straight
+        // into the shared port is drawn as one segment, and its junction is still where the trunk crosses it.
+        const meet = isVerticalSide(group.side) ? { x: anchors.exit.x, y: group.at } : { x: group.at, y: anchors.exit.y }
+        junctions.push({ kind: 'junction', x: meet.x, y: meet.y, colour, trunk: group.id })
+        continue
+      }
+    }
+
     // A long edge follows the lane the channel stage gave it: down the exit stub, across to the lane's x on the run
     // the gap was assigned, down the lane, and across to the entry stub. The spine carries one point per gap, so the
     // two runs are the places where a port and the lane disagree, and everything between them is one straight drop.
@@ -936,41 +1448,93 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
       }
       if (Math.abs(previous.x - anchors.entry.x) > 0.5 && Math.abs(previous.y - anchors.entry.y) > 0.5) points.push({ x: anchors.entry.x, y: previous.y })
       points.push(anchors.entry)
-      paintPath(edge, simplify(points), colour)
-      continue
+      const simplified = simplify(points)
+      if (clearOfBoxes(simplified, source, target)) {
+        paintPath(edgeIndex, edge, simplified, colour)
+        continue
+      }
     }
 
-    // Two rows with nothing between them: the edge is the two-bend run the channel stage stacked. A run sits in the
-    // empty strip between its own two rows and inside its own component's column, so it cannot meet a box - unless a
-    // port on a side steps out of it, and then the step is checked and a route that would meet a box is the router's.
+    // Two rows with nothing between them: the edge is the two-bend run the channel stage stacked. The run's height is
+    // an empty strip only when the two rows it was measured between are the boxes actually drawn: a run reserved
+    // between two boundaries is a strip outside them, while the painter's ports belong to boxes inside them. So the
+    // proposal is checked, not trusted, and an edge whose legs would cross a box is the router's.
     const runY = placement.runs.get(edgeIndex)
     if (runY !== undefined && anchors !== undefined && runFits(anchors, runY)) {
       const points = runRoute(anchors, runY)
-      const mixed = isVerticalSide(anchors.exitSide) !== isVerticalSide(anchors.entrySide)
-      if (!mixed || clearsBoxes(points, source, target)) {
-        paintRoute(edge, points, colour)
+      if (clearOfBoxes(points, source, target)) {
+        paintRoute(edgeIndex, edge, points, colour)
         continue
       }
     }
 
-    paintRoute(edge, routeEdge(source, target, boxList, anchors).points, colour)
+    // The router is the last stage. Its own straight-line shortcut is already refused when a box is in the way; a
+    // search that cannot finish still returns a line, and the final pass over the assembled drawing reports it.
+    paintRoute(edgeIndex, edge, routeEdge(source, target, boxList, anchors).points, colour)
+  }
+
+  // The dots last of the lines: a dot marks a join, so no line of the drawing may be drawn over it.
+  for (const dot of junctions) shapes.push(dot)
+
+  // The assembled drawing, checked once: every segment of every drawn edge against every box it does not terminate
+  // at. Each candidate route was checked before it was emitted, so this pass is the assertion that no stage slipped a
+  // segment through a box - and the place a router that found no way round is reported rather than hidden.
+  const boxEntries = Array.from(boxes.entries())
+  const routingFailures: RoutingFailure[] = []
+  for (const { shape, edge } of routes) {
+    const diagramEdge = diagram.edges[edge] as DiagramEdge
+    const source = endBox(diagramEdge.from)
+    const target = endBox(diagramEdge.to)
+    if (source === undefined || target === undefined) continue
+    for (const segment of segmentsOfRoute(shape)) {
+      for (const [id, box] of boxEntries) {
+        if (box === source || box === target) continue
+        if (!crossesBox(segment.x1, segment.y1, segment.x2, segment.y2, box)) continue
+        routingFailures.push({
+          edge,
+          from: diagramEdge.from,
+          to: diagramEdge.to,
+          box: id,
+          x1: segment.x1,
+          y1: segment.y1,
+          x2: segment.x2,
+          y2: segment.y2,
+        })
+      }
+    }
   }
 
   // Labels last. A label has to clear every other edge, and until the last edge is drawn the painter does not know
   // where those are: this is why the whole pass exists rather than a decision made edge by edge.
-  const routeSegments = routes.map((shape) => segmentsOfRoute(shape))
+  const routeSegments = routes.map(({ shape }) => segmentsOfRoute(shape))
   const placedLabels: LabelSpot[] = []
-  routes.forEach((shape, index) => {
-    const run = longestRun(pointsOfRoute(shape))
-    // The middle of the longest run is where the label belongs; a label with nothing to avoid stays exactly there.
-    let spot: LabelSpot = { x: (run.from.x + run.to.x) / 2, y: (run.from.y + run.to.y) / 2, width: textWidth(shape.label), height: LABEL_HEIGHT }
-    if (shape.label !== '') {
-      spot = placeLabel(shape.label, run.from, run.to, boxList, placedLabels, routeSegments.flatMap((list, at) => (at === index ? [] : list)))
-      placedLabels.push(spot)
-    }
-    shape.labelX = spot.x
-    shape.labelY = spot.y
+  routes.forEach(({ shape, fixed }, at) => {
+    if (fixed) {
+      if (shape.label !== '') {
+        placedLabels.push({ x: shape.labelX, y: shape.labelY, width: textWidth(shape.label), height: LABEL_HEIGHT })
+      }
+      return
+    }
+    if (shape.label === '') return
+    const placement = placeLabel(
+      shape.label,
+      pointsOfRoute(shape),
+      boxList,
+      placedLabels,
+      routeSegments.filter((_, other) => other !== at),
+    )
+    shape.labelX = placement.x
+    shape.labelY = placement.y
+    shape.labelPlacement = {
+      run: placement.run,
+      collisions: placement.collisions,
+      boxes: placement.boxes,
+      labels: placement.labels,
+      edges: placement.edges,
+    }
+    placedLabels.push({ x: placement.x, y: placement.y, width: placement.width, height: placement.height })
   })
+  const labelCollisions = routes.reduce((total, { shape }) => total + ((shape.labelPlacement?.collisions ?? 0) > 0 ? 1 : 0), 0)
 
   shapes.push({ kind: 'title', x: MARGIN, y: MARGIN + 12, text: diagram.title, colour: 'text' })
 
@@ -989,6 +1553,8 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
     ...Array.from(groupRects.values(), (rect) => rect.y + rect.height),
   )
   const captionTop = contentBottom + CAPTION_GAP
+  // Anchored at the left margin, where the title is. The writer starts the text there: centred on a left-edge x,
+  // half of a long caption fell outside the drawing and was clipped at the bottom edge of the picture.
   shapes.push({ kind: 'caption', x: MARGIN, y: captionTop, lines: captionLines, colour: captionRole(diagram.caption) })
   const height = captionTop + captionLines.length * CAPTION_LINE + MARGIN / 2
 
@@ -998,7 +1564,10 @@ export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, op
   const canvasWidth = Math.max(width, extent.width + MARGIN)
   const canvasHeight = Math.max(height, extent.height + MARGIN)
 
-  return { canvas: { width: Math.round(canvasWidth), height: Math.round(canvasHeight), shapes }, colours }
+  return {
+    canvas: { width: Math.round(canvasWidth), height: Math.round(canvasHeight), shapes, routingFailures, labelCollisions },
+    colours,
+  }
 }
 
 export function paint(diagram: Diagram, overrides: Partial<Palette> = {}): Canvas {