@dxos/diagram 0.11.1 → 0.14.0

package/src/mermaid-engine.ts

@@ -14,11 +14,14 @@ import ELK, { type ElkNode } from 'elkjs/lib/elk.bundled.js';
 
 import { invariant } from '@dxos/invariant';
 
+import * as Compact from './compact.ts';
 import * as Diagnostics from './diagnostics.ts';
 import * as Layout from './layout.ts';
 import { type Direction, type MermaidEdge, type MermaidGraph, markers, parse } from './mermaid.ts';
+import * as Nudge from './nudge.ts';
 import * as Objective from './objective.ts';
 import { makeAvoidingRouter } from './ortho-router.ts';
+import * as Ports from './ports.ts';
 import type * as Scene from './scene.ts';
 import { GRID, type Rect, type Router, zRouter } from './uml-grid.ts';
 
@@ -102,12 +105,24 @@ export type CompileOptions = {
    * connect through one horizontal bus and a single triangle-headed trunk instead of parallel arrows.
    */
   bus?: readonly boolean[];
+  /**
+   * Compaction candidates (default both): with `true`, packages and boxes slide toward their partners
+   * after placement, closing empty lanes and long detours; see `compact.ts`.
+   */
+  compact?: readonly boolean[];
   /** Objective that picks among candidates (default `Objective.DEFAULT`). */
   objective?: Objective.Objective;
   /** Maximum cell width, in scene units (default GRID × 6); longer labels wrap. */
   maxWidth?: number;
   /** Connector router (default: obstacle-avoiding A* with the Z-router as fallback). */
   route?: Router;
+  /**
+   * Routes one candidate, nearly all of the layout's time (default: on this thread); a caller with
+   * worker threads can run {@link emitJob} there. Each candidate is handed over as soon as it is
+   * placed, so placing the rest overlaps the routing; the candidates are still collected in
+   * generation order. Not used with a custom `route`, which cannot leave the thread.
+   */
+  emitCandidate?: (job: EmitJob) => Promise<Scene.Command[]>;
 };
 
 /** One generated layout with the objective's verdict on it. */
@@ -117,6 +132,7 @@ export type Candidate = {
   arrangement: Arrangement;
   layering: Layering;
   alignment: Alignment;
+  compact: boolean;
   bus: boolean;
   commands: Scene.Command[];
   layout: Objective.Layout;
@@ -129,7 +145,7 @@ export type Result = {
   ranked: readonly Objective.Ranked<Candidate>[];
 };
 
-type Cell = { w: number; h: number };
+export type Cell = { w: number; h: number };
 type Pitch = { x: number; y: number };
 
 /** One cell size for every node, sized to the longest label wrapped at `maxWidth`. */
@@ -155,7 +171,7 @@ const pitchFor = (graph: MermaidGraph, cell: Cell, lattice: number): Pitch => {
   };
 };
 
-type Placement = {
+export type Placement = {
   nodes: Map<string, Rect>;
   frames: Map<string, Rect>;
 };
@@ -211,7 +227,10 @@ const compactGroups = (
   const groups = graph.groups
     .filter((group) => group.children.some((id) => positions.has(id)))
     .map((group) => {
-      const coords = group.children.flatMap((id) => (positions.has(id) ? [positions.get(id)![axis]] : []));
+      const coords = group.children.flatMap((id) => {
+        const point = positions.get(id);
+        return point ? [point[axis]] : [];
+      });
       return { ids: group.children, start: Math.min(...coords), end: Math.max(...coords) };
     })
     .sort((left, right) => left.start - right.start);
@@ -257,7 +276,7 @@ const compactGroups = (
 type ElkEdge = { id: string; sources: string[]; targets: string[] };
 
 /**
- * Edges for ELK's layering. Inheritance points at the abstraction, which ranks ABOVE its
+ * Edges for ELK's layering. Inheritance and implementation point at the abstraction, which ranks ABOVE its
  * subtypes — so those edges are reversed, as `relationRanks` does for class diagrams; has-many
  * and containment already flow owner-above-owned. In `columns`, the root lays out groups without
  * seeing inside them (`SEPARATE_CHILDREN`), so every edge is lifted to its endpoints' root-level
@@ -270,7 +289,7 @@ const layeringEdges = (graph: MermaidGraph, arrangement: Arrangement, layering:
   const betweenGroups = (edge: MermaidEdge) =>
     groupOf.has(edge.from) && groupOf.has(edge.to) && groupOf.get(edge.from) !== groupOf.get(edge.to);
   const oriented = graph.edges.flatMap((edge) => {
-    if (edge.kind === 'inheritance') {
+    if (edge.kind === 'inheritance' || edge.kind === 'implements') {
       return [{ from: edge.to, to: edge.from }];
     }
     if (edge.kind !== 'reference' || layering === 'down' || betweenGroups(edge)) {
@@ -451,6 +470,21 @@ const alignGroups = (
   return result;
 };
 
+/** Slides packages and boxes toward their partners on the lattice; see `compact.ts`. */
+const compactPlacement = (
+  graph: MermaidGraph,
+  positions: Map<string, Scene.Point>,
+  cell: Cell,
+  pitch: Pitch,
+): Map<string, Scene.Point> =>
+  Compact.compact({ nodes: graph.nodes.map((node) => node.id), groups: graph.groups, edges: graph.edges }, positions, {
+    cell,
+    pitch,
+    framePad: FRAME_PAD,
+    frameLabel: FRAME_LABEL_H,
+    frameGap: FRAME_GAP,
+  });
+
 /** Node rects at the origin plus the frame around each group's members. */
 const frame = (graph: MermaidGraph, positions: Map<string, Scene.Point>, cell: Cell): Placement => {
   const minX = Math.min(0, ...[...positions.values()].map((point) => point.x));
@@ -475,7 +509,20 @@ const frame = (graph: MermaidGraph, positions: Map<string, Scene.Point>, cell: C
   return { nodes, frames };
 };
 
-type Ports = { start?: number; end?: number };
+type PortPair = { start?: number; end?: number };
+
+/** Rounds of port reordering per emit; each re-routes every edge, so it is capped. */
+const PORT_ROUNDS = 3;
+
+/** Local-search passes on the chosen layout, and the most re-routes they may spend. */
+const SEARCH_PASSES = 4;
+const SEARCH_TRIES = 48;
+
+/** Whether a re-routed scene has fewer crossings without any new error or connector overlap. */
+const improves = (next: Diagnostics.Report, current: Diagnostics.Report): boolean =>
+  next.metrics.crossings < current.metrics.crossings &&
+  Diagnostics.errors(next).length <= Diagnostics.errors(current).length &&
+  next.metrics.edgeOverlaps <= current.metrics.edgeOverlaps;
 
 /**
  * Straightened ports: when an edge's nodes overlap on the cross axis, both terminals take one
@@ -487,8 +534,8 @@ const straighten = (
   edges: readonly MermaidEdge[],
   nodes: Map<string, Rect>,
   isHorizontal: (edge: MermaidEdge) => boolean,
-): Map<MermaidEdge, Ports> => {
-  const ports = new Map<MermaidEdge, Ports>();
+): Map<MermaidEdge, PortPair> => {
+  const ports = new Map<MermaidEdge, PortPair>();
   const taken = new Map<string, number[]>();
   for (const edge of edges) {
     const from = nodes.get(edge.from);
@@ -589,7 +636,7 @@ const inheritanceBuses = (
       id: `${baseId}-inherit`,
       start: { x: trunkX, y: busY },
       end: { x: trunkX, y: base.y + base.h },
-      head: 'triangle',
+      relation: 'inheritance',
     });
   }
   return { elements, consumed };
@@ -601,8 +648,83 @@ type EmitOptions = {
   bus: boolean;
   arrangement: Arrangement;
   route?: Router;
+  /** Run the port local search; costly, so only for the layout already chosen. */
+  search?: boolean;
+};
+
+/** One candidate's routing, as structured-cloneable data so it can cross to a worker thread. */
+export type EmitJob = Omit<EmitOptions, 'route'> & {
+  source: string;
+  cell: Cell;
+  placement: Placement;
 };
 
+const rectsOverlap = (a: Rect, b: Rect) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+
+/** Whether an axis-aligned (or short diagonal) segment passes through a rect, by its bounding box. */
+const segmentHits = ([a, b]: [Scene.Point, Scene.Point], rect: Rect) =>
+  rectsOverlap(
+    { x: Math.min(a.x, b.x), y: Math.min(a.y, b.y), w: Math.abs(b.x - a.x) || 1, h: Math.abs(b.y - a.y) || 1 },
+    rect,
+  );
+
+/**
+ * Edge labels, each at the first spot along its own path that is clear of every node, every label
+ * already placed and every other edge's line: beside a vertical run or above/below a horizontal one,
+ * trying the middle segment first and working outward. Falls back to the middle when nothing is clear.
+ */
+const placeLabels = (
+  labelled: readonly { id: string; text: string; points: Scene.Point[] }[],
+  paths: readonly Scene.Point[][],
+  nodes: readonly Rect[],
+): Scene.Text[] => {
+  const segments = paths.map((points) =>
+    points.slice(0, -1).map((point, index): [Scene.Point, Scene.Point] => [point, points[index + 1]]),
+  );
+  const placed: Rect[] = [];
+  return labelled.map(({ id, text, points }) => {
+    const size = { w: text.length * LABEL_FONT.charW, h: LABEL_FONT.lineH };
+    const own = points.slice(0, -1).map((point, index): [Scene.Point, Scene.Point] => [point, points[index + 1]]);
+    const middle = Math.floor((own.length - 1) / 2);
+    const order = own.map((_, index) => index).sort((a, b) => Math.abs(a - middle) - Math.abs(b - middle));
+    const candidates = order.flatMap((index) => {
+      const [a, b] = own[index];
+      const vertical = Math.abs(a.x - b.x) < Math.abs(a.y - b.y);
+      return [0.5, 0.3, 0.7].flatMap((t) => {
+        const at = { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t };
+        return vertical
+          ? [
+              { x: at.x + GRID / 4, y: at.y - size.h / 2 },
+              { x: at.x - GRID / 4 - size.w, y: at.y - size.h / 2 },
+            ]
+          : [
+              { x: at.x - size.w / 2, y: at.y - size.h - GRID / 8 },
+              { x: at.x - size.w / 2, y: at.y + GRID / 8 },
+            ];
+      });
+    });
+    const clear = (rect: Rect) =>
+      !nodes.some((node) => rectsOverlap(rect, node)) &&
+      !placed.some((other) => rectsOverlap(rect, other)) &&
+      !segments.some((path) => path.some((segment) => segmentHits(segment, rect)));
+    const [head, tail] = own[middle] ?? [points[0], points[points.length - 1]];
+    const fallback = { x: (head.x + tail.x) / 2 + GRID / 4, y: (head.y + tail.y) / 2 - LABEL_FONT.lineH };
+    const origin = candidates.find((candidate) => clear({ ...candidate, ...size })) ?? fallback;
+    placed.push({ ...origin, ...size });
+    return { kind: 'text', id: `${id}-label`, x: origin.x, y: origin.y, text, weight: 's' };
+  });
+};
+
+/** Group tints in declaration order; a renderer fills a frame with a light wash of its color. */
+const GROUP_COLORS: readonly Scene.Color[] = [
+  'light-blue',
+  'light-green',
+  'yellow',
+  'light-violet',
+  'orange',
+  'light-red',
+];
+
 /**
  * Scene commands for a placement: one world object per subgraph frame (painted first) and per
  * node, plus an `edges` object of connectors.
@@ -611,13 +733,13 @@ const emit = (
   graph: MermaidGraph,
   cell: Cell,
   { nodes, frames }: Placement,
-  { origin, scale, bus, arrangement, route }: EmitOptions,
+  { origin, scale, bus, arrangement, route, search = false }: EmitOptions,
 ): Scene.Command[] => {
   const horizontal = graph.direction === 'LR' || graph.direction === 'RL';
   const at = (rect: Rect): Scene.Point => ({ x: origin.x + rect.x * scale, y: origin.y + rect.y * scale });
   const commands: Scene.Command[] = [];
 
-  for (const group of graph.groups) {
+  for (const [index, group] of graph.groups.entries()) {
     const frame = frames.get(group.id);
     if (!frame) {
       continue;
@@ -629,7 +751,17 @@ const emit = (
         origin: at(frame),
         scale,
         elements: [
-          { kind: 'rect', id: 'frame', x: 0, y: 0, w: frame.w, h: frame.h, stroke: 'dashed', color: 'grey' },
+          {
+            kind: 'rect',
+            id: 'frame',
+            x: 0,
+            y: 0,
+            w: frame.w,
+            h: frame.h,
+            stroke: 'dashed',
+            fill: 'tint',
+            color: GROUP_COLORS[index % GROUP_COLORS.length],
+          },
           // The label sits in the frame's top band rather than centered, where members would cover it.
           ...(group.label.trim()
             ? [
@@ -668,7 +800,13 @@ const emit = (
 
   if (graph.edges.length > 0) {
     // Frames are containers, not obstacles: only node rects block routes.
-    const router = route ?? makeAvoidingRouter([...nodes.values()], zRouter, { step: GRID / 4 });
+    const makeRouter = (): { router: Router; reserve?: (points: readonly Scene.Point[]) => void } => {
+      if (route) {
+        return { router: route };
+      }
+      const avoiding = makeAvoidingRouter([...nodes.values()], zRouter, { step: GRID / 4 });
+      return { router: avoiding, reserve: avoiding.reserve };
+    };
     const buses = bus && !horizontal ? inheritanceBuses(graph.edges, nodes) : { elements: [], consumed: new Set() };
     const routed = graph.edges.filter((edge) => !buses.consumed.has(edge));
     // In columns the root level runs across the flow, so an edge between two of its members — groups
@@ -677,23 +815,7 @@ const emit = (
     const rootOf = (id: string) => groupOf.get(id) ?? id;
     const isHorizontal = (edge: MermaidEdge) =>
       arrangement === 'columns' && rootOf(edge.from) !== rootOf(edge.to) ? !horizontal : horizontal;
-    const ports = straighten(routed, nodes, isHorizontal);
-    const elements: Scene.Element[] = [...buses.elements];
-    // Terminals already placed, per node, with their role. Edges are routed independently (and an
-    // internal edge and a cross-group edge may even route in different modes), so a later edge can
-    // land its terminal on an earlier one. Only an exit on an entry is a defect — it reads as a
-    // crossing — so a slot is taken by the opposite role alone: two exits (a fork) or two entries (a
-    // merge) share a trunk, as a bus does. Such an edge is re-routed with the port nudged to a free
-    // slot on that side, preferring the nudge that keeps the route straightest.
-    type Role = 'exit' | 'entry';
-    const terminals = new Map<string, { point: Scene.Point; role: Role }[]>();
-    const taken = (nodeId: string, point: Scene.Point, role: Role) =>
-      (terminals.get(nodeId) ?? []).some(
-        (other) =>
-          other.role !== role &&
-          Math.abs(other.point.x - point.x) < GRID_FINE &&
-          Math.abs(other.point.y - point.y) < GRID_FINE,
-      );
+    const straightened = straighten(routed, nodes, isHorizontal);
     // Paired nudges first: both ends move together, so a straight edge stays straight; single-ended
     // ones for when only one end is crowded.
     const NUDGES: [number, number][] = [
@@ -707,82 +829,320 @@ const emit = (
       [0, 1],
       [0, -1],
     ];
-    const routeEdge = (edge: MermaidEdge, from: Rect, to: Rect): Scene.Point[] => {
-      const horizontal = isHorizontal(edge);
-      const sameLane = horizontal ? from.x === to.x : from.y === to.y;
-      const alongY = horizontal ? sameLane : !sameLane;
-      const base = ports.get(edge) ?? {};
-      const center = (rect: Rect) => (alongY ? rect.x + rect.w / 2 : rect.y + rect.h / 2);
-      const within = (rect: Rect, value: number) =>
-        alongY
-          ? Math.min(rect.x + rect.w - GRID_FINE, Math.max(rect.x + GRID_FINE, value))
-          : Math.min(rect.y + rect.h - GRID_FINE, Math.max(rect.y + GRID_FINE, value));
-      const route = ([startNudge, endNudge]: [number, number]) =>
-        router({
-          relation: edge,
-          from,
-          to,
-          horizontal,
-          offset: 0,
-          ports: {
-            start: within(from, (base.start ?? center(from)) + startNudge * GRID_FINE),
-            end: within(to, (base.end ?? center(to)) + endNudge * GRID_FINE),
-          },
+    type Routed = {
+      edge: MermaidEdge;
+      index: number;
+      points: Scene.Point[];
+      source: Rect;
+      target: Rect;
+      /** Every path the router returned for this edge, each of which steered the edges after it. */
+      attempts: Scene.Point[][];
+    };
+    /**
+     * Routes every edge with a fresh router, since the avoiding router steers each route off earlier
+     * ones. Edges before the first whose ports changed would route exactly as in `previous`, so their
+     * routes are replayed into the router instead of searched again.
+     */
+    const routeAll = (
+      ports: Map<MermaidEdge, PortPair>,
+      previous?: { ports: Map<MermaidEdge, PortPair>; routes: readonly Routed[] },
+    ): Routed[] => {
+      const { router: search, reserve } = makeRouter();
+      let attempts: Scene.Point[][] = [];
+      const router: Router = (relation) => {
+        const points = search(relation);
+        attempts.push(points);
+        return points;
+      };
+      // Terminals already placed, per node, with their role. Edges are routed independently (and an
+      // internal edge and a cross-group edge may even route in different modes), so a later edge can
+      // land its terminal on an earlier one. Only an exit on an entry is a defect — it reads as a
+      // crossing — so a slot is taken by the opposite role alone: two exits (a fork) or two entries (a
+      // merge) share a trunk, as a bus does. Such an edge is re-routed with the port nudged to a free
+      // slot on that side, preferring the nudge that keeps the route straightest.
+      type Role = 'exit' | 'entry';
+      const terminals = new Map<string, { point: Scene.Point; role: Role }[]>();
+      const taken = (nodeId: string, point: Scene.Point, role: Role) =>
+        (terminals.get(nodeId) ?? []).some(
+          (other) =>
+            other.role !== role &&
+            Math.abs(other.point.x - point.x) < GRID_FINE &&
+            Math.abs(other.point.y - point.y) < GRID_FINE,
+        );
+      const routeEdge = (edge: MermaidEdge, from: Rect, to: Rect): Scene.Point[] => {
+        const horizontal = isHorizontal(edge);
+        const sameLane = horizontal ? from.x === to.x : from.y === to.y;
+        const alongY = horizontal ? sameLane : !sameLane;
+        const base = ports.get(edge) ?? {};
+        const center = (rect: Rect) => (alongY ? rect.x + rect.w / 2 : rect.y + rect.h / 2);
+        const within = (rect: Rect, value: number) =>
+          alongY
+            ? Math.min(rect.x + rect.w - GRID_FINE, Math.max(rect.x + GRID_FINE, value))
+            : Math.min(rect.y + rect.h - GRID_FINE, Math.max(rect.y + GRID_FINE, value));
+        const route = ([startNudge, endNudge]: [number, number]) =>
+          router({
+            relation: edge,
+            from,
+            to,
+            horizontal,
+            offset: 0,
+            ports: {
+              start: within(from, (base.start ?? center(from)) + startNudge * GRID_FINE),
+              end: within(to, (base.end ?? center(to)) + endNudge * GRID_FINE),
+            },
+          });
+        const free = (points: Scene.Point[]) =>
+          !taken(edge.from, points[0], 'exit') && !taken(edge.to, points[points.length - 1], 'entry');
+        const direct = route(NUDGES[0]);
+        if (free(direct)) {
+          return direct;
+        }
+        let best: Scene.Point[] | undefined;
+        for (const nudge of NUDGES.slice(1)) {
+          const attempt = route(nudge);
+          if (free(attempt) && (!best || attempt.length < best.length)) {
+            best = attempt;
+          }
+        }
+        return best ?? direct;
+      };
+      const replayed = new Map(previous?.routes.map((entry) => [entry.edge, entry]));
+      const samePorts = (edge: MermaidEdge) =>
+        previous?.ports.get(edge)?.start === ports.get(edge)?.start &&
+        previous?.ports.get(edge)?.end === ports.get(edge)?.end;
+      let replaying = reserve !== undefined && previous !== undefined;
+      return routed.flatMap((edge, index): Routed[] => {
+        const from = nodes.get(edge.from);
+        const to = nodes.get(edge.to);
+        if (!from || !to) {
+          return [];
+        }
+        const earlier = replayed.get(edge);
+        replaying = replaying && earlier !== undefined && samePorts(edge);
+        let points: Scene.Point[];
+        if (replaying && earlier && reserve) {
+          earlier.attempts.forEach(reserve);
+          attempts = earlier.attempts;
+          points = earlier.points;
+        } else {
+          attempts = [];
+          points = routeEdge(edge, from, to);
+        }
+        terminals.set(edge.from, [...(terminals.get(edge.from) ?? []), { point: points[0], role: 'exit' }]);
+        terminals.set(edge.to, [
+          ...(terminals.get(edge.to) ?? []),
+          { point: points[points.length - 1], role: 'entry' },
+        ]);
+        return [{ edge, index, points, source: from, target: to, attempts }];
+      });
+    };
+    // Edges are routed one at a time, so parallel runs land on the same line; the bus is a deliberate merge and stays put.
+    const draw = (routes: readonly Routed[]) => {
+      const nudged = Nudge.nudge(routes, {
+        spacing: GRID / 4,
+        obstacles: [...nodes.values()],
+        fixed: buses.elements.flatMap((element) =>
+          element.kind === 'line'
+            ? [element.points]
+            : element.kind === 'arrow' && element.start && element.end
+              ? [[element.start, element.end]]
+              : [],
+        ),
+      });
+      const elements: Scene.Element[] = [...buses.elements];
+      const labelled: { id: string; text: string; points: Scene.Point[] }[] = [];
+      const paths: Scene.Point[][] = [];
+      routes.forEach(({ edge, index }, position) => {
+        const points = nudged[position];
+        const id = `${edge.from}-${edge.to}-${index}`;
+        const style = markers(edge.kind);
+        if (points.length > 2) {
+          elements.push({
+            kind: 'line',
+            id: `${id}-path`,
+            points: points.slice(0, -1),
+            ...(style.stroke ? { stroke: style.stroke } : {}),
+          });
+        }
+        elements.push({
+          kind: 'arrow',
+          id,
+          start: points[points.length - 2],
+          end: points[points.length - 1],
+          ...style,
         });
-      const free = (points: Scene.Point[]) =>
-        !taken(edge.from, points[0], 'exit') && !taken(edge.to, points[points.length - 1], 'entry');
-      const direct = route(NUDGES[0]);
-      if (free(direct)) {
-        return direct;
-      }
-      let best: Scene.Point[] | undefined;
-      for (const nudge of NUDGES.slice(1)) {
-        const attempt = route(nudge);
-        if (free(attempt) && (!best || attempt.length < best.length)) {
-          best = attempt;
+        if (edge.label) {
+          labelled.push({ id, text: edge.label, points });
         }
+        paths.push(points);
+      });
+      elements.push(...placeLabels(labelled, paths, [...nodes.values()]));
+      const object: Scene.WorldObject = { id: 'edges', origin, scale, elements };
+      return { object, nudged };
+    };
+    // The faces whose port the router honours: a terminal it moved to a cross face is not ours to order.
+    const flowSides = (edge: MermaidEdge, from: Rect, to: Rect): [Ports.Side, Ports.Side] => {
+      const horizontal = isHorizontal(edge);
+      const alongY = horizontal ? from.x === to.x : from.y !== to.y;
+      return alongY
+        ? to.y >= from.y
+          ? ['bottom', 'top']
+          : ['top', 'bottom']
+        : to.x >= from.x
+          ? ['right', 'left']
+          : ['left', 'right'];
+    };
+    const others = objectsOf(commands);
+    let ports = straightened;
+    let routes = routeAll(ports);
+    let drawn = draw(routes);
+    let report = Diagnostics.analyze([...others, drawn.object]);
+    const refOf = ({ edge, index }: Routed) => `edges/${edge.from}-${edge.to}-${index}`;
+    const crossingRefs = () =>
+      new Set(report.diagnostics.flatMap(({ code, refs }) => (code === 'edge-crossing' ? refs : [])));
+    /** Re-routes with `candidate` ports and keeps the result only if it {@link improves} the scene. */
+    const attempt = (candidate: Map<MermaidEdge, PortPair>): boolean => {
+      const candidateRoutes = routeAll(candidate, { ports, routes });
+      const candidateDrawn = draw(candidateRoutes);
+      const candidateReport = Diagnostics.analyze([...others, candidateDrawn.object]);
+      if (!improves(candidateReport, report)) {
+        return false;
       }
-      return best ?? direct;
+      [ports, routes, drawn, report] = [candidate, candidateRoutes, candidateDrawn, candidateReport];
+      return true;
     };
-    routed.forEach((edge, index) => {
-      const from = nodes.get(edge.from);
-      const to = nodes.get(edge.to);
-      if (!from || !to) {
-        return;
+    const withPort = (
+      base: Map<MermaidEdge, PortPair>,
+      edge: MermaidEdge,
+      end: 'start' | 'end',
+      coord: number,
+    ): Map<MermaidEdge, PortPair> => new Map(base).set(edge, { ...base.get(edge), [end]: coord });
+
+    for (let round = 0; round < PORT_ROUNDS && report.metrics.crossings > 0; round++) {
+      const assigned = Ports.assign(
+        routes.map(({ edge, source, target }, position) => {
+          const points = drawn.nudged[position];
+          const [startSide, endSide] = flowSides(edge, source, target);
+          // A straightened edge pins its ports only while its route really is one straight run.
+          const straight = straightened.has(edge) && points.length === 2;
+          return {
+            points,
+            source,
+            target,
+            fixed: {
+              start: straight || Ports.sideOf(points[0], source) !== startSide,
+              end: straight || Ports.sideOf(points[points.length - 1], target) !== endSide,
+            },
+          };
+        }),
+        { step: GRID_FINE },
+      );
+      // Re-routing is the expensive part, and moving ports of edges that cross nothing cannot uncross anything.
+      const crossing = crossingRefs();
+      const moved = routes.filter(
+        (_, position) => assigned[position].start !== undefined || assigned[position].end !== undefined,
+      );
+      if (!moved.some((entry) => crossing.has(refOf(entry)))) {
+        break;
+      }
+      let candidate = ports;
+      routes.forEach(({ edge }, position) => {
+        for (const end of ['start', 'end'] as const) {
+          const coord = assigned[position][end];
+          if (coord !== undefined) {
+            candidate = withPort(candidate, edge, end, coord);
+          }
+        }
+      });
+      if (!attempt(candidate)) {
+        break;
       }
-      const points = routeEdge(edge, from, to);
-      terminals.set(edge.from, [...(terminals.get(edge.from) ?? []), { point: points[0], role: 'exit' }]);
-      terminals.set(edge.to, [...(terminals.get(edge.to) ?? []), { point: points[points.length - 1], role: 'entry' }]);
-      const id = `${edge.from}-${edge.to}-${index}`;
-      if (points.length > 2) {
-        elements.push({ kind: 'line', id: `${id}-path`, points: points.slice(0, -1) });
+    }
+
+    // Local search, for the chosen layout only: swap two ports of one side, or slide one to a free
+    // slot beside it, where an edge on that side still crosses another.
+    let tries = 0;
+    for (let pass = 0; search && pass < SEARCH_PASSES && report.metrics.crossings > 0; pass++) {
+      type Slot = { edge: MermaidEdge; end: 'start' | 'end'; coord: number; crossing: boolean; rect: Rect };
+      const crossing = crossingRefs();
+      const sides = new Map<string, Slot[]>();
+      for (const entry of routes) {
+        const { edge, source, target, points } = entry;
+        const flow = flowSides(edge, source, target);
+        const ends = [
+          { end: 'start' as const, rect: source, point: points[0], side: flow[0], node: edge.from },
+          { end: 'end' as const, rect: target, point: points[points.length - 1], side: flow[1], node: edge.to },
+        ];
+        for (const { end, rect, point, side, node } of ends) {
+          if (Ports.sideOf(point, rect) === side) {
+            const coord = side === 'top' || side === 'bottom' ? point.x : point.y;
+            const key = `${node}:${side}`;
+            sides.set(key, [
+              ...(sides.get(key) ?? []),
+              { edge, end, coord, crossing: crossing.has(refOf(entry)), rect },
+            ]);
+          }
+        }
       }
-      elements.push({
-        kind: 'arrow',
-        id,
-        start: points[points.length - 2],
-        end: points[points.length - 1],
-        ...markers(edge.kind),
+      const moves = [...sides.entries()].flatMap(([key, slots]): Map<MermaidEdge, PortPair>[] => {
+        if (slots.length < 2 || !slots.some((slot) => slot.crossing)) {
+          return [];
+        }
+        const horizontalSide = key.endsWith(':top') || key.endsWith(':bottom');
+        const swaps = slots.flatMap((first, index) =>
+          slots
+            .slice(index + 1)
+            .filter(
+              (second) => (first.crossing || second.crossing) && Math.abs(first.coord - second.coord) >= GRID_FINE,
+            )
+            .map((second) =>
+              withPort(withPort(ports, first.edge, first.end, second.coord), second.edge, second.end, first.coord),
+            ),
+        );
+        const slides = slots
+          .filter((slot) => slot.crossing)
+          .flatMap((slot) =>
+            [-GRID_FINE, GRID_FINE]
+              .map((delta) => slot.coord + delta)
+              .filter((coord) => {
+                const [low, high] = horizontalSide
+                  ? [slot.rect.x, slot.rect.x + slot.rect.w]
+                  : [slot.rect.y, slot.rect.y + slot.rect.h];
+                return (
+                  coord >= low + GRID_FINE &&
+                  coord <= high - GRID_FINE &&
+                  slots.every((other) => other === slot || Math.abs(other.coord - coord) >= GRID_FINE)
+                );
+              })
+              .map((coord) => withPort(ports, slot.edge, slot.end, coord)),
+          );
+        return [...swaps, ...slides];
       });
-      if (edge.label) {
-        const head = points[Math.floor(points.length / 2) - 1];
-        const tail = points[Math.floor(points.length / 2)];
-        elements.push({
-          kind: 'text',
-          id: `${id}-label`,
-          x: (head.x + tail.x) / 2 + GRID / 4,
-          y: (head.y + tail.y) / 2 - LABEL_FONT.lineH,
-          text: edge.label,
-          weight: 's',
-        });
+      let improved = false;
+      for (const move of moves) {
+        if (tries++ >= SEARCH_TRIES) {
+          break;
+        }
+        if (attempt(move)) {
+          improved = true;
+          // Routes changed, so the remaining moves were built on stale coordinates.
+          break;
+        }
       }
-    });
-    commands.push({ op: 'upsert-object', object: { id: 'edges', origin, scale, elements } });
+      if (!improved) {
+        break;
+      }
+    }
+    commands.push({ op: 'upsert-object', object: drawn.object });
   }
 
   return commands;
 };
 
+/** Routes one candidate with the default router; what a worker runs for `CompileOptions.emitCandidate`. */
+export const emitJob = ({ source, cell, placement, ...options }: EmitJob): Scene.Command[] =>
+  emit(parse(source), cell, placement, options);
+
 const objectsOf = (commands: readonly Scene.Command[]): Scene.WorldObject[] =>
   commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));
 
@@ -793,8 +1153,16 @@ const objectsOf = (commands: readonly Scene.Command[]): Scene.WorldObject[] =>
  */
 export const layout = async (source: string, options: CompileOptions = {}): Promise<Result> => {
   const graph = parse(source);
-  const { origin = { x: 0, y: 0 }, scale = 1, maxWidth = MAX_W, objective = Objective.DEFAULT, route } = options;
+  const {
+    origin = { x: 0, y: 0 },
+    scale = 1,
+    maxWidth = MAX_W,
+    objective = Objective.DEFAULT,
+    route,
+    compact: compactions = [true, false],
+  } = options;
   const cell = measureCell(graph, maxWidth);
+  const horizontal = graph.direction === 'LR' || graph.direction === 'RL';
   const lattices = typeof options.lattice === 'number' ? [options.lattice] : (options.lattice ?? LATTICES);
   const orders = options.order ?? ORDERS;
   const buses = options.bus ?? [true, false];
@@ -809,14 +1177,33 @@ export const layout = async (source: string, options: CompileOptions = {}): Prom
       buses.length > 0 &&
       arrangements.length > 0 &&
       layerings.length > 0 &&
-      alignments.length > 0,
+      alignments.length > 0 &&
+      compactions.length > 0,
     'every candidate axis needs a value',
   );
 
-  const candidates: Candidate[] = [];
+  const emitCandidate = route ? undefined : options.emitCandidate;
+  // A candidate can fail while later ones are still being placed, before `Promise.all` below
+  // observes it; marking it handled here keeps that from crashing the process as an unhandled
+  // rejection, and `Promise.all` still rethrows the failure.
+  const settleLater = (commands: Promise<Scene.Command[]>) => {
+    commands.catch(() => {});
+    return commands;
+  };
+
+  const pending: {
+    candidate: Omit<Candidate, 'commands' | 'layout'>;
+    placement: Placement;
+    commands: Promise<Scene.Command[]>;
+  }[] = [];
   // Knobs often reach the same placement (a graph with no in-package references layers the same
   // either way; equal-height packages align the same every way); each is routed and graded once.
   const seen = new Set<string>();
+  const keyOf = (placement: Placement) =>
+    [...placement.nodes]
+      .map(([id, rect]) => `${id}:${rect.x}:${rect.y}`)
+      .sort()
+      .join(' ');
   for (const lattice of lattices) {
     for (const order of orders) {
       for (const arrangement of arrangements) {
@@ -825,28 +1212,29 @@ export const layout = async (source: string, options: CompileOptions = {}): Prom
           const positions = await place(graph, cell, pitch, order, arrangement, layering);
           // Alignment moves packages relative to each other, which only columns set side by side.
           for (const alignment of arrangement === 'columns' ? alignments : (['none'] as const)) {
-            const placement = frame(graph, alignGroups(graph, positions, graph.direction, alignment), cell);
-            const key = [...placement.nodes]
-              .map(([id, rect]) => `${id}:${rect.x}:${rect.y}`)
-              .sort()
-              .join(' ');
-            for (const bus of buses) {
-              if (seen.has(`${arrangement}|${bus}|${key}`)) {
-                continue;
+            const aligned = alignGroups(graph, positions, graph.direction, alignment);
+            for (const compact of [false, true].filter((value) => compactions.includes(value))) {
+              const placement = frame(graph, compact ? compactPlacement(graph, aligned, cell, pitch) : aligned, cell);
+              const key = keyOf(placement);
+              // Without a row of subtypes to gather, the bus draws exactly what its absence does; the
+              // `false` twin is routed anyway, so routing both would be the same work twice.
+              const formsBus = !horizontal && inheritanceBuses(graph.edges, placement.nodes).consumed.size > 0;
+              for (const bus of buses) {
+                if (seen.has(`${arrangement}|${bus}|${key}`) || (bus && !formsBus && buses.includes(false))) {
+                  continue;
+                }
+                seen.add(`${arrangement}|${bus}|${key}`);
+                const job: EmitJob = { source, cell, placement, origin, scale, bus, arrangement };
+                pending.push({
+                  candidate: { lattice, order, arrangement, layering, alignment, compact, bus },
+                  placement,
+                  commands: settleLater(
+                    emitCandidate
+                      ? emitCandidate(job)
+                      : Promise.resolve(emit(graph, cell, placement, { origin, scale, bus, arrangement, route })),
+                  ),
+                });
               }
-              seen.add(`${arrangement}|${bus}|${key}`);
-              const commands = emit(graph, cell, placement, { origin, scale, bus, arrangement, route });
-              const objects = objectsOf(commands);
-              candidates.push({
-                lattice,
-                order,
-                arrangement,
-                layering,
-                alignment,
-                bus,
-                commands,
-                layout: { objects, report: Diagnostics.analyze(objects) },
-              });
             }
           }
         }
@@ -854,8 +1242,70 @@ export const layout = async (source: string, options: CompileOptions = {}): Prom
     }
   }
 
-  const { chosen, ranked } = Objective.select(objective, candidates);
-  return { commands: chosen.candidate.commands, chosen, ranked };
+  const emitted = await Promise.all(pending.map(({ commands }) => commands));
+  const placements = new Map<Candidate, Placement>();
+  const candidates = pending.map(({ candidate, placement }, index): Candidate => {
+    const commands = emitted[index];
+    const objects = objectsOf(commands);
+    const result: Candidate = { ...candidate, commands, layout: { objects, report: Diagnostics.analyze(objects) } };
+    placements.set(result, placement);
+    return result;
+  });
+
+  // Compaction trades connector length for proximity, but never for a crossing the uncompacted pick avoids.
+  const plain = candidates.filter((candidate) => !candidate.compact);
+  const ceiling = plain.length
+    ? Objective.select(objective, plain).chosen.candidate.layout.report.metrics.crossings
+    : Infinity;
+  const { ranked } = Objective.select(
+    objective,
+    candidates.filter((candidate) => !candidate.compact || candidate.layout.report.metrics.crossings <= ceiling),
+  );
+  return refine(graph, cell, placements, objective, { origin, scale, route }, ranked);
+};
+
+/** How many of the best-ranked layouts get the port local search; refining more found nothing better on the corpus. */
+const REFINE_TOP = 1;
+
+/**
+ * Re-emits the best-ranked layouts with the port local search, which is too costly to run on every
+ * candidate, keeps each result the objective rates no worse, and picks again among them.
+ */
+const refine = (
+  graph: MermaidGraph,
+  cell: Cell,
+  placements: Map<Candidate, Placement>,
+  objective: Objective.Objective,
+  { origin, scale, route }: Pick<EmitOptions, 'origin' | 'scale' | 'route'>,
+  ranked: readonly Objective.Ranked<Candidate>[],
+): Result => {
+  const refineOne = (entry: Objective.Ranked<Candidate>): Objective.Ranked<Candidate> => {
+    const placement = placements.get(entry.candidate);
+    if (!placement || entry.candidate.layout.report.metrics.crossings === 0) {
+      return entry;
+    }
+    const { bus, arrangement } = entry.candidate;
+    const commands = emit(graph, cell, placement, { origin, scale, bus, arrangement, route, search: true });
+    const objects = objectsOf(commands);
+    const candidate: Candidate = {
+      ...entry.candidate,
+      commands,
+      layout: { objects, report: Diagnostics.analyze(objects) },
+    };
+    const evaluation = Objective.evaluate(objective, candidate.layout);
+    return evaluation.violations.length > entry.evaluation.violations.length || evaluation.cost > entry.evaluation.cost
+      ? entry
+      : { candidate, evaluation };
+  };
+  // Same order as `Objective.select`, and stable, so untouched ties keep the generator's order.
+  const reranked = ranked
+    .map((entry, index) => (index < REFINE_TOP ? refineOne(entry) : entry))
+    .sort(
+      (left, right) =>
+        left.evaluation.violations.length - right.evaluation.violations.length ||
+        left.evaluation.cost - right.evaluation.cost,
+    );
+  return { commands: reranked[0].candidate.commands, chosen: reranked[0], ranked: reranked };
 };
 
 /** The chosen layout's scene commands; see {@link layout} for the candidates and verdicts. */