@dxos/diagram 0.11.1 → 0.13.0

package/src/mermaid.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, test } from 'vitest';
 
-import { compile, parse } from './mermaid.ts';
+import { compile, markers, parse } from './mermaid.ts';
 import type * as Scene from './scene.ts';
 
 /** Exercises node declarations, a labelled-blank subgraph, fan-out, and a `C <-> Y` cycle. */
@@ -55,6 +55,22 @@ describe('mermaid', () => {
     ]);
   });
 
+  test('reads the relation tokens as kinds with their UML markers', ({ expect }) => {
+    const graph = parse(
+      ['flowchart TB', '  B ..|> A', '  C -.-> D', '  E o--> F', '  G --{ H', '  I --|> J', '  K --> L'].join('\n'),
+    );
+    expect(graph.edges.map(({ kind }) => kind)).toEqual([
+      'implements',
+      'creates',
+      'contains',
+      'hasMany',
+      'inheritance',
+      'reference',
+    ]);
+    expect(markers('implements')).toEqual({ relation: 'implementation', stroke: 'dashed' });
+    expect(markers('creates')).toEqual({ relation: 'dependency', stroke: 'dashed' });
+  });
+
   test('compiles to one object per node plus a frame and an edge object', ({ expect }) => {
     const objects = objectsOf(compile(FLOWCHART));
 

package/src/mermaid.ts

@@ -29,7 +29,7 @@ export type MermaidGroup = {
 };
 
 /** Relationship kind, from the edge token; drawn with the UML end markers in `markers`. */
-export type RelationKind = 'reference' | 'inheritance' | 'hasMany' | 'contains';
+export type RelationKind = 'reference' | 'inheritance' | 'implements' | 'hasMany' | 'contains' | 'creates';
 
 export type MermaidEdge = {
   from: string;
@@ -39,23 +39,30 @@ export type MermaidEdge = {
 };
 
 /**
- * Edge tokens: mermaid's own arrows read as references; the classDiagram-style `--|>` (hollow
- * triangle) and ER-style `--{` (crow's foot) and `o-->` (circle at the source) extend the flowchart
- * grammar with the UML kinds, at the cost of mermaid.js rejecting those lines.
+ * Edge tokens: mermaid's own arrows read as references, except the dotted `-.->`, which reads as
+ * creation (UML's dashed «create» dependency). The classDiagram-style `--|>` (hollow triangle) and
+ * `..|>` (dashed hollow triangle) and ER-style `--{` (crow's foot) and `o-->` (circle at the owner)
+ * extend the flowchart grammar with the UML kinds, at the cost of mermaid.js rejecting those lines.
  */
 const EDGE_KINDS: Record<string, RelationKind> = {
   '-->': 'reference',
   '---': 'reference',
-  '-.->': 'reference',
   '==>': 'reference',
+  '-.->': 'creates',
   '--|>': 'inheritance',
+  '..|>': 'implements',
   '--{': 'hasMany',
   'o-->': 'contains',
 };
 
 /** Reference-render labels for the UML kinds, used when the edge carries none of its own. */
-const UML_LABELS: Record<string, string> = { '--|>': 'extends', '--{': 'has many', 'o-->': 'contains' };
-const UML_EDGE = /^(\s*\S+)\s*(o-->|--\|>|--\{)\s*(?:\|(.*?)\|\s*)?(\S+)\s*$/;
+const UML_LABELS: Record<string, string> = {
+  '--|>': 'extends',
+  '..|>': 'implements',
+  '--{': 'has many',
+  'o-->': 'contains',
+};
+const UML_EDGE = /^(\s*\S+)\s*(o-->|--\|>|\.\.\|>|--\{)\s*(?:\|(.*?)\|\s*)?(\S+)\s*$/;
 
 /**
  * Rewrite the UML edge tokens into mermaid-legal labelled arrows, for rendering the source with
@@ -72,15 +79,19 @@ export const toStandard = (source: string): string =>
     })
     .join('\n');
 
-/** Scene arrow markers for a relationship kind. */
-export const markers = (kind: RelationKind): Pick<Scene.Arrow, 'head' | 'tail'> => {
+/** The scene relation a relationship kind draws as, with the dash its line needs; a plain reference stays a plain arrow. */
+export const markers = (kind: RelationKind): Pick<Scene.Arrow, 'relation' | 'stroke'> => {
   switch (kind) {
     case 'inheritance':
-      return { head: 'triangle' };
+      return { relation: 'inheritance' };
+    case 'implements':
+      return { relation: 'implementation', stroke: 'dashed' };
     case 'hasMany':
-      return { head: 'crowsfoot' };
+      return { relation: 'one-to-many' };
     case 'contains':
-      return { tail: 'circle' };
+      return { relation: 'aggregation' };
+    case 'creates':
+      return { relation: 'dependency', stroke: 'dashed' };
     default:
       return {};
   }
@@ -97,8 +108,9 @@ const DIRECTIONS: Direction[] = ['TB', 'BT', 'LR', 'RL'];
 
 // `A[Label]`, `A(Label)`, `A{Label}` or a bare `A`.
 const NODE = /^([A-Za-z0-9_-]+)(?:\[(.*?)\]|\((.*?)\)|\{(.*?)\})?$/;
-// `A --> B`, `A-->|label|B`, `A --- B`, plus the UML kinds `B --|> A`, `X --{ Y`, `A o--> B`.
-const EDGE = /^(.+?)\s*(o-->|--\|>|--\{|-->|---|-\.->|==>)\s*(?:\|(.*?)\|\s*)?(.+)$/;
+// `A --> B`, `A-->|label|B`, `A --- B`, `A -.-> B`, plus the UML kinds `B --|> A`, `B ..|> A`, `X --{ Y`
+// and `A o--> B`.
+const EDGE = /^(.+?)\s*(o-->|--\|>|\.\.\|>|--\{|-->|---|-\.->|==>)\s*(?:\|(.*?)\|\s*)?(.+)$/;
 const SUBGRAPH = /^subgraph\s+([A-Za-z0-9_-]+)(?:\s*\[(.*?)\])?\s*$/;
 
 // `%% ref A packages/core/echo` — a comment to mermaid proper, so sources stay portable.
@@ -114,7 +126,7 @@ export const parse = (source: string): MermaidGraph => {
   let direction: Direction = 'TB';
   const stack: string[] = [];
 
-  const declare = (token: string): string | undefined => {
+  const declareNode = (token: string): string | undefined => {
     const match = NODE.exec(token.trim());
     if (!match) {
       return undefined;
@@ -172,8 +184,8 @@ export const parse = (source: string): MermaidGraph => {
     const edge = EDGE.exec(line);
     if (edge) {
       const [, from, token, label, to] = edge;
-      const fromId = declare(from);
-      const toId = declare(to);
+      const fromId = declareNode(from);
+      const toId = declareNode(to);
       if (fromId && toId) {
         edges.push({
           from: fromId,
@@ -185,7 +197,7 @@ export const parse = (source: string): MermaidGraph => {
       continue;
     }
 
-    declare(line);
+    declareNode(line);
   }
 
   // Directives may precede or follow the node they name.

package/src/nudge.test.ts

@@ -0,0 +1,155 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { nudge } from './nudge.ts';
+import type * as Scene from './scene.ts';
+import { type Rect } from './uml-grid.ts';
+
+const orthogonal = (points: readonly Scene.Point[]) =>
+  points.slice(1).every((point, index) => point.x === points[index].x || point.y === points[index].y);
+
+/** Whether two orthogonal polylines share a collinear stretch of positive length. */
+const overlapping = (first: readonly Scene.Point[], second: readonly Scene.Point[]) => {
+  const segments = (points: readonly Scene.Point[]) =>
+    points.slice(1).map((end, index) => [points[index], end] as const);
+  return segments(first).some(([a0, a1]) =>
+    segments(second).some(([b0, b1]) => {
+      if (a0.x === a1.x && b0.x === b1.x && a0.x === b0.x) {
+        const lo = Math.max(Math.min(a0.y, a1.y), Math.min(b0.y, b1.y));
+        const hi = Math.min(Math.max(a0.y, a1.y), Math.max(b0.y, b1.y));
+        return hi - lo > 0;
+      }
+      if (a0.y === a1.y && b0.y === b1.y && a0.y === b0.y) {
+        const lo = Math.max(Math.min(a0.x, a1.x), Math.min(b0.x, b1.x));
+        const hi = Math.min(Math.max(a0.x, a1.x), Math.max(b0.x, b1.x));
+        return hi - lo > 0;
+      }
+      return false;
+    }),
+  );
+};
+
+const onBorder = (point: Scene.Point, rect: Rect) =>
+  ((point.y === rect.y || point.y === rect.y + rect.h) && point.x >= rect.x && point.x <= rect.x + rect.w) ||
+  ((point.x === rect.x || point.x === rect.x + rect.w) && point.y >= rect.y && point.y <= rect.y + rect.h);
+
+describe('nudge', () => {
+  const source: Rect = { x: 0, y: 0, w: 128, h: 64 };
+  const left: Rect = { x: 0, y: 200, w: 128, h: 64 };
+  const right: Rect = { x: 200, y: 200, w: 128, h: 64 };
+  // A fork: both leave the same port and run down x = 64 together before one turns right.
+  const straight = {
+    points: [
+      { x: 64, y: 64 },
+      { x: 64, y: 200 },
+    ],
+    source,
+    target: left,
+  };
+  const turning = {
+    points: [
+      { x: 64, y: 64 },
+      { x: 64, y: 132 },
+      { x: 264, y: 132 },
+      { x: 264, y: 200 },
+    ],
+    source,
+    target: right,
+  };
+
+  test('two edges sharing a vertical run are separated and stay orthogonal', ({ expect }) => {
+    const [first, second] = nudge([straight, turning], { obstacles: [source, left, right] });
+    expect(orthogonal(first)).toBe(true);
+    expect(orthogonal(second)).toBe(true);
+    // The edge that turns right takes the right-hand lane, so its turn-off does not cut the other.
+    expect(second[0].x - first[0].x).toBeGreaterThanOrEqual(8);
+    expect(second[1].x).toBe(second[0].x);
+    expect(onBorder(first[0], source) && onBorder(second[0], source)).toBe(true);
+    expect(first[first.length - 1]).toEqual({ x: first[0].x, y: 200 });
+    expect(second[second.length - 1]).toEqual({ x: 264, y: 200 });
+  });
+
+  test('a fork sharing a vertical run and then a horizontal run is fully separated', ({ expect }) => {
+    const far: Rect = { x: 400, y: 200, w: 128, h: 64 };
+    const near = {
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 132 },
+        { x: 264, y: 132 },
+        { x: 264, y: 200 },
+      ],
+      source,
+      target: right,
+    };
+    const away = {
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 132 },
+        { x: 464, y: 132 },
+        { x: 464, y: 200 },
+      ],
+      source,
+      target: far,
+    };
+    const [first, second] = nudge([near, away], { obstacles: [source, right, far] });
+    expect(orthogonal(first) && orthogonal(second)).toBe(true);
+    expect(overlapping(first, second)).toBe(false);
+  });
+
+  test('a fixed bus never moves; the edge lying on it is pushed off', ({ expect }) => {
+    const bus = [
+      { x: 100, y: 100 },
+      { x: 200, y: 100 },
+    ];
+    const edge = {
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 100 },
+        { x: 264, y: 100 },
+        { x: 264, y: 200 },
+      ],
+      source,
+      target: right,
+    };
+    const fixed = [bus];
+    const [moved] = nudge([edge], { obstacles: [source, right], fixed });
+    expect(fixed[0]).toEqual(bus);
+    expect(Math.abs(moved[1].y - 100)).toBeGreaterThanOrEqual(8);
+    expect(moved[0]).toEqual({ x: 64, y: 64 });
+    expect(orthogonal(moved)).toBe(true);
+  });
+
+  test('ports stay put when separation would leave the box side', ({ expect }) => {
+    const narrow: Rect = { x: 0, y: 0, w: 16, h: 64 };
+    const below: Rect = { x: 0, y: 200, w: 16, h: 64 };
+    const path = {
+      points: [
+        { x: 8, y: 64 },
+        { x: 8, y: 200 },
+      ],
+      source: narrow,
+      target: below,
+    };
+    const result = nudge([path, path], { obstacles: [narrow, below] });
+    expect(result).toEqual([path.points, path.points]);
+  });
+
+  test('a run is never pushed through a box', ({ expect }) => {
+    // Both lanes beside the shared run are blocked by boxes hugging it.
+    const wall = (x: number): Rect => ({ x, y: 80, w: 40, h: 100 });
+    const edge = (y: number) => ({
+      points: [
+        { x: 64, y: 64 },
+        { x: 64, y: 200 },
+      ],
+      source,
+      target: { x: 0, y, w: 128, h: 64 },
+    });
+    const obstacles = [source, wall(20), wall(68), { x: 0, y: 200, w: 128, h: 64 }];
+    const result = nudge([edge(200), edge(200)], { obstacles });
+    expect(result.map((points) => points[0].x)).toEqual([64, 64]);
+  });
+});

package/src/nudge.ts

@@ -0,0 +1,385 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Scene from './scene.ts';
+import { type Rect } from './uml-grid.ts';
+
+type Point = Scene.Point;
+type Axis = 'h' | 'v';
+
+/** One axis-aligned segment of a line: `points[start] → points[start + 1]`. */
+type Run = { owner: number; start: number; axis: Axis; coord: number; lo: number; hi: number };
+
+/** A routed connector: its orthogonal polyline and the boxes its ends are attached to. */
+export type NudgePath = {
+  points: readonly Point[];
+  /** Box the first point sits on; without it the start port is never moved. */
+  source?: Rect;
+  /** Box the last point sits on; without it the end port is never moved. */
+  target?: Rect;
+};
+
+export type NudgeOptions = {
+  /** Gap between separated parallel runs (default 8). */
+  spacing?: number;
+  /** Boxes no run may be pushed through. */
+  obstacles?: readonly Rect[];
+  /** Lines that never move but that paths must not be pushed onto (e.g. an inheritance bus). */
+  fixed?: readonly (readonly Point[])[];
+  /** Minimum distance between a moved port and its box's corner (default `spacing`). */
+  margin?: number;
+};
+
+const EPSILON = 0.5;
+
+const along = (axis: Axis, point: Point) => (axis === 'v' ? point.y : point.x);
+const across = (axis: Axis, point: Point) => (axis === 'v' ? point.x : point.y);
+const sign = (value: number) => (value > EPSILON ? 1 : value < -EPSILON ? -1 : 0);
+
+/** Drops repeated waypoints and the midpoints of straight runs, so each run is one maximal segment. */
+const simplify = (points: readonly Point[]): Point[] => {
+  const distinct = points.filter(
+    (point, index) =>
+      index === 0 ||
+      Math.abs(point.x - points[index - 1].x) >= EPSILON ||
+      Math.abs(point.y - points[index - 1].y) >= EPSILON,
+  );
+  return distinct.filter((point, index) => {
+    if (index === 0 || index === distinct.length - 1) {
+      return true;
+    }
+    const [previous, next] = [distinct[index - 1], distinct[index + 1]];
+    const vertical = Math.abs(previous.x - point.x) < EPSILON && Math.abs(point.x - next.x) < EPSILON;
+    const horizontal = Math.abs(previous.y - point.y) < EPSILON && Math.abs(point.y - next.y) < EPSILON;
+    return !vertical && !horizontal;
+  });
+};
+
+const runsOf = (points: readonly Point[], owner: number): Run[] =>
+  points.slice(0, -1).flatMap((from, start): Run[] => {
+    const to = points[start + 1];
+    const axis: Axis | undefined =
+      Math.abs(from.x - to.x) < EPSILON ? 'v' : Math.abs(from.y - to.y) < EPSILON ? 'h' : undefined;
+    if (!axis) {
+      return [];
+    }
+    const [a, b] = [along(axis, from), along(axis, to)];
+    return [{ owner, start, axis, coord: across(axis, from), lo: Math.min(a, b), hi: Math.max(a, b) }];
+  });
+
+const shared = (left: Run, right: Run): boolean =>
+  left.axis === right.axis &&
+  Math.abs(left.coord - right.coord) < EPSILON &&
+  Math.min(left.hi, right.hi) - Math.max(left.lo, right.lo) > EPSILON;
+
+const crosses = (left: Run, right: Run): boolean => {
+  if (left.axis === right.axis) {
+    return false;
+  }
+  return (
+    right.coord > left.lo + EPSILON &&
+    right.coord < left.hi - EPSILON &&
+    left.coord > right.lo + EPSILON &&
+    left.coord < right.hi - EPSILON
+  );
+};
+
+/** Length of the run inside the rect's interior; a run along a border or into a port is free. */
+const interiorRun = (run: Run, rect: Rect): number => {
+  const [crossLo, crossHi, alongLo, alongHi] =
+    run.axis === 'v'
+      ? [rect.x, rect.x + rect.w, rect.y, rect.y + rect.h]
+      : [rect.y, rect.y + rect.h, rect.x, rect.x + rect.w];
+  if (run.coord <= crossLo + EPSILON || run.coord >= crossHi - EPSILON) {
+    return 0;
+  }
+  return Math.max(0, Math.min(run.hi, alongHi - EPSILON) - Math.max(run.lo, alongLo + EPSILON));
+};
+
+/**
+ * Pairs `{changed, other}` related by `related`: per line pair, or per run pair with `perRun`, which
+ * overlaps need so that separating one of two channels two lines share still lowers the count.
+ */
+const pairCount = (
+  lines: readonly Point[][],
+  changed: ReadonlySet<number>,
+  related: (a: Run, b: Run) => boolean,
+  perRun = false,
+) => {
+  const runs = lines.map((points, owner) => runsOf(points, owner));
+  let count = 0;
+  for (const owner of changed) {
+    runs.forEach((others, other) => {
+      if (other === owner || (changed.has(other) && other < owner)) {
+        return;
+      }
+      if (perRun) {
+        for (const run of runs[owner]) {
+          count += others.filter((candidate) => related(run, candidate)).length;
+        }
+      } else if (runs[owner].some((run) => others.some((candidate) => related(run, candidate)))) {
+        count++;
+      }
+    });
+  }
+  return count;
+};
+
+/** Collinear runs of different lines that overlap, grouped transitively along each shared line. */
+const channelsOf = (lines: readonly Point[][], movable: number): Run[][] => {
+  const runs = lines
+    .flatMap((points, owner) => runsOf(points, owner))
+    .sort((a, b) =>
+      a.axis === b.axis
+        ? Math.abs(a.coord - b.coord) < EPSILON
+          ? a.lo - b.lo
+          : a.coord - b.coord
+        : a.axis < b.axis
+          ? -1
+          : 1,
+    );
+  const channels: Run[][] = [];
+  let current: Run[] = [];
+  let reach = -Infinity;
+  const flush = () => {
+    const owners = new Set(current.map((run) => run.owner));
+    // A line that doubles back on itself, or a channel of fixed lines alone, is not ours to separate.
+    if (owners.size > 1 && owners.size === current.length && current.some((run) => run.owner < movable)) {
+      channels.push(current);
+    }
+  };
+  for (const run of runs) {
+    const head = current[0];
+    if (head && head.axis === run.axis && Math.abs(head.coord - run.coord) < EPSILON && run.lo < reach - EPSILON) {
+      current.push(run);
+      reach = Math.max(reach, run.hi);
+    } else {
+      flush();
+      current = [run];
+      reach = run.hi;
+    }
+  }
+  flush();
+  return channels;
+};
+
+/** Side (−1, 0, +1 across the run) the line turns toward at the run's low or high end; 0 at a terminal. */
+const turn = (lines: readonly Point[][], run: Run, end: 'lo' | 'hi'): number => {
+  const points = lines[run.owner];
+  const startIsLow = along(run.axis, points[run.start]) < along(run.axis, points[run.start + 1]);
+  const neighbor = (end === 'lo') === startIsLow ? run.start - 1 : run.start + 2;
+  return neighbor < 0 || neighbor >= points.length ? 0 : sign(across(run.axis, points[neighbor]) - run.coord);
+};
+
+/**
+ * Order across the channel that keeps each run's turn-offs from cutting the others: a run that
+ * leaves the shared stretch early sits on the side it turns toward.
+ */
+const order = (lines: readonly Point[][], channel: readonly Run[]): Run[] => {
+  const compare = (left: Run, right: Run): number => {
+    let vote = 0;
+    if (left.lo > right.lo + EPSILON) {
+      vote += turn(lines, left, 'lo');
+    } else if (right.lo > left.lo + EPSILON) {
+      vote -= turn(lines, right, 'lo');
+    } else {
+      vote += sign(turn(lines, left, 'lo') - turn(lines, right, 'lo'));
+    }
+    if (left.hi < right.hi - EPSILON) {
+      vote += turn(lines, left, 'hi');
+    } else if (right.hi < left.hi - EPSILON) {
+      vote -= turn(lines, right, 'hi');
+    } else {
+      vote += sign(turn(lines, left, 'hi') - turn(lines, right, 'hi'));
+    }
+    return vote !== 0 ? vote : left.owner - right.owner;
+  };
+  return [...channel].sort(compare);
+};
+
+/**
+ * Shift one run across its axis by `offset`, dragging the adjacent waypoints with it so the line
+ * stays orthogonal; undefined when that would detach a port, reverse a neighbour or crush an end stub.
+ */
+const shift = (
+  points: readonly Point[],
+  run: Run,
+  offset: number,
+  path: NudgePath | undefined,
+  spacing: number,
+  margin: number,
+): Point[] | undefined => {
+  const move = (point: Point): Point =>
+    run.axis === 'v' ? { x: point.x + offset, y: point.y } : { x: point.x, y: point.y + offset };
+  const next = points.map((point, index) => (index === run.start || index === run.start + 1 ? move(point) : point));
+  const last = points.length - 1;
+  for (const [index, rect] of [
+    [0, path?.source],
+    [last, path?.target],
+  ] as const) {
+    if (index !== run.start && index !== run.start + 1) {
+      continue;
+    }
+    // A port slides along its own side only: the side must lie across the run, and the port must stay clear of the corners.
+    const port = points[index];
+    if (!rect) {
+      return undefined;
+    }
+    const [sideLo, sideHi, crossLo, crossHi] =
+      run.axis === 'v'
+        ? [rect.y, rect.y + rect.h, rect.x, rect.x + rect.w]
+        : [rect.x, rect.x + rect.w, rect.y, rect.y + rect.h];
+    const onSide =
+      Math.abs(along(run.axis, port) - sideLo) < EPSILON || Math.abs(along(run.axis, port) - sideHi) < EPSILON;
+    const moved = across(run.axis, next[index]);
+    if (!onSide || moved < crossLo + margin - EPSILON || moved > crossHi - margin + EPSILON) {
+      return undefined;
+    }
+  }
+  for (const segment of [run.start - 1, run.start + 1]) {
+    if (segment < 0 || segment >= last) {
+      continue;
+    }
+    const before = across(run.axis, points[segment + 1]) - across(run.axis, points[segment]);
+    const after = across(run.axis, next[segment + 1]) - across(run.axis, next[segment]);
+    if (sign(after) !== 0 && sign(after) !== sign(before)) {
+      return undefined;
+    }
+    // End stubs carry the arrowhead and the port's exit direction, so they may not shrink below one step.
+    const terminal = segment === 0 || segment === last - 1;
+    if (terminal && Math.abs(after) < Math.min(Math.abs(before), spacing) - EPSILON) {
+      return undefined;
+    }
+  }
+  return next;
+};
+
+type Candidate = { lines: Point[][]; overlaps: number; crossings: number; reversed: number; travel: number };
+
+/**
+ * Separates the runs of one channel by `spacing`, preferring the channel's order; tries every window
+ * of offsets (and single moves as a fallback) and keeps the one that resolves the most overlaps
+ * without adding crossings or cutting through a box.
+ */
+const separate = (
+  lines: readonly Point[][],
+  channel: readonly Run[],
+  paths: readonly NudgePath[],
+  obstacles: readonly Rect[],
+  spacing: number,
+  margin: number,
+): Point[][] | undefined => {
+  const movable = paths.length;
+  const fixed = channel.filter((run) => run.owner >= movable);
+  if (fixed.length > 1) {
+    return undefined;
+  }
+  const sorted = order(lines, channel);
+  const assignments: { offsets: Map<Run, number>; reversed: number }[] = [];
+  [sorted, [...sorted].reverse()].forEach((ordered, reversed) => {
+    const anchor = ordered.findIndex((run) => run.owner >= movable);
+    const shifts = anchor >= 0 ? [-anchor] : ordered.map((_, index) => -index);
+    for (const base of shifts) {
+      assignments.push({
+        offsets: new Map(ordered.map((run, index) => [run, (index + base) * spacing])),
+        reversed,
+      });
+    }
+  });
+  for (const run of channel) {
+    if (run.owner < movable) {
+      for (const steps of [1, -1, 2, -2]) {
+        assignments.push({ offsets: new Map([[run, steps * spacing]]), reversed: 1 });
+      }
+    }
+  }
+
+  const changedOf = (offsets: Map<Run, number>) =>
+    new Set([...offsets].filter(([, offset]) => offset !== 0).map(([run]) => run.owner));
+  const obstructed = (candidate: readonly Point[][], owners: ReadonlySet<number>) =>
+    [...owners].reduce(
+      (total, owner) =>
+        total +
+        runsOf(candidate[owner], owner).filter((run) => obstacles.some((rect) => interiorRun(run, rect) > EPSILON))
+          .length,
+      0,
+    );
+
+  let best: Candidate | undefined;
+  for (const { offsets, reversed } of assignments) {
+    const changed = changedOf(offsets);
+    if (changed.size === 0 || [...changed].some((owner) => owner >= movable)) {
+      continue;
+    }
+    const candidate = [...lines];
+    let valid = true;
+    for (const [run, offset] of offsets) {
+      if (offset === 0) {
+        continue;
+      }
+      const moved = shift(lines[run.owner], run, offset, paths[run.owner], spacing, margin);
+      if (!moved) {
+        valid = false;
+        break;
+      }
+      candidate[run.owner] = moved;
+    }
+    if (!valid) {
+      continue;
+    }
+    const overlaps = pairCount(candidate, changed, shared, true);
+    const crossings = pairCount(candidate, changed, crosses);
+    if (
+      overlaps >= pairCount(lines, changed, shared, true) ||
+      crossings > pairCount(lines, changed, crosses) ||
+      obstructed(candidate, changed) > obstructed(lines, changed)
+    ) {
+      continue;
+    }
+    const travel = [...offsets.values()].reduce((total, offset) => total + Math.abs(offset), 0);
+    const better =
+      !best ||
+      overlaps < best.overlaps ||
+      (overlaps === best.overlaps &&
+        (crossings < best.crossings ||
+          (crossings === best.crossings &&
+            (reversed < best.reversed || (reversed === best.reversed && travel < best.travel)))));
+    if (better) {
+      best = { lines: candidate, overlaps, crossings, reversed, travel };
+    }
+  }
+  return best?.lines.map((points, owner) => (points === lines[owner] ? points : simplify(points)));
+};
+
+/**
+ * Nudging (Wybrow, Marriott & Stuckey 2010): distinct connectors that share a collinear run are
+ * pulled apart across it by `spacing`, ordered so their turn-offs do not cross, with ports sliding
+ * along their box side. Fixed lines (a deliberate bus) never move. Paths that need no change come
+ * back as given.
+ */
+export const nudge = (paths: readonly NudgePath[], options: NudgeOptions = {}): Point[][] => {
+  const { spacing = 8, obstacles = [], fixed = [], margin = spacing } = options;
+  let lines: Point[][] = [...paths.map((path) => simplify(path.points)), ...fixed.map((points) => [...points])];
+  const touched = new Set<number>();
+  const attempted = new Set<string>();
+  const signature = (channel: readonly Run[]) =>
+    `${channel[0].axis}:${Math.round(channel[0].coord)}:${channel
+      .map((run) => `${run.owner}@${Math.round(run.lo)}-${Math.round(run.hi)}`)
+      .sort()
+      .join(',')}`;
+  // Each separation strictly lowers the overlap count and a failed channel is never retried, so this terminates.
+  for (;;) {
+    const channel = channelsOf(lines, paths.length).find((candidate) => !attempted.has(signature(candidate)));
+    if (!channel) {
+      break;
+    }
+    attempted.add(signature(channel));
+    const next = separate(lines, channel, paths, obstacles, spacing, margin);
+    if (next) {
+      next.forEach((points, owner) => points !== lines[owner] && touched.add(owner));
+      lines = next;
+    }
+  }
+  return paths.map((path, owner) => (touched.has(owner) ? lines[owner] : [...path.points]));
+};

package/src/objective.test.ts

@@ -29,6 +29,8 @@ describe('objective', () => {
     expect(evaluation.violations).toEqual([]);
     expect(evaluation.terms.map(({ id }) => id)).toEqual([
       'crossings',
+      'edge-overlaps',
+      'text-overlaps',
       'bends',
       'connector-length',
       'uneven-frame-gaps',