@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/src/utils/parts.ts

@@ -3,65 +3,87 @@
 //
 
 //
-// Text parts of a node: the pieces a node type renders as text and lets the user edit in place. A
-// part is named by the node property it edits; list properties read and write as one entry per line.
+// Text parts of a node: the properties a node type renders as text and lets the user edit in place. Each
+// type declares its parts in its registry definition, so a type a host adds edits the same way as a built-in
+// one. A part is named by the property it edits; a `lines` part reads and writes a list one entry per line.
 //
 
-import { type Node, type NodeValues, isBoxNode, isClassNode, isEllipseNode, isNoteNode } from '../model/types.ts';
+import { nodeDef } from '../model/node-def.ts';
+import { type NodeRegistry } from '../model/registry.ts';
+import { type Node, type NodeValues } from '../model/types.ts';
 
-export type PartKey = 'label' | 'text' | 'name' | 'attributes' | 'methods';
+/** A part's name: the node property it edits. */
+export type PartKey = string;
+
+/** A text property of a node type, as its definition declares it. */
+export type PartField = {
+  /** The node property the part edits. */
+  field: PartKey;
+  /** A list of strings, one per line; implies `multiline`. */
+  lines?: boolean;
+  /** Enter breaks the line and Mod-Enter commits, rather than Enter committing. */
+  multiline?: boolean;
+};
 
 /** A part edited in place: which one, and how the editor hands its result back. */
 export type PartEditing = {
   part: PartKey;
+  multiline: boolean;
   commit: (text: string) => void;
   cancel: () => void;
 };
 
-const PARTS: readonly PartKey[] = ['label', 'text', 'name', 'attributes', 'methods'];
-
-/** The part a `data-part` attribute names, if it names one. */
-export const partKey = (value: string | null | undefined): PartKey | undefined => PARTS.find((part) => part === value);
-
-const LINES: readonly PartKey[] = ['text', 'attributes', 'methods'];
-
-/** Enter inserts a line in a multi-line part; Mod-Enter commits. */
-export const isMultiline = (part: PartKey): boolean => LINES.includes(part);
-
-const lines = (text: string): string[] =>
+const toLines = (text: string): string[] =>
   text
     .split('\n')
     .map((line) => line.trim())
     .filter((line) => line.length > 0);
 
-/** The part's text, or none when the node type has no such part. */
-export const partText = (node: Node, part: PartKey): string | undefined => {
-  switch (part) {
-    case 'label':
-      return isBoxNode(node) || isEllipseNode(node) ? (node.label ?? '') : undefined;
-    case 'text':
-      return isNoteNode(node) ? node.text : undefined;
-    case 'name':
-      return isClassNode(node) ? node.name : undefined;
-    case 'attributes':
-      return isClassNode(node) ? node.attributes.join('\n') : undefined;
-    case 'methods':
-      return isClassNode(node) ? node.methods.join('\n') : undefined;
+/** The core base's one part: the label a node of an unknown type is edited by (see `BaseNode`). */
+const BASE_PARTS: readonly PartField[] = [{ field: 'label' }];
+
+/** The parts a node's type declares; a type the registry does not know has the core base's label. */
+export const nodeParts = (registry: NodeRegistry, node: Node): readonly PartField[] => {
+  const def = nodeDef(registry, node);
+  return def ? (def.parts ?? []) : BASE_PARTS;
+};
+
+const partOf = (registry: NodeRegistry, node: Node, part: PartKey): PartField | undefined =>
+  nodeParts(registry, node).find(({ field }) => field === part);
+
+/** Whether the part takes several lines. */
+export const isMultiline = (part: PartField): boolean => part.lines === true || part.multiline === true;
+
+/** The part's text, or none when the node's type has no such part. */
+export const partText = (registry: NodeRegistry, node: Node, part: PartKey): string | undefined => {
+  const field = partOf(registry, node, part);
+  if (!field) {
+    return undefined;
+  }
+  const value: unknown = Reflect.get(node, field.field);
+  if (field.lines) {
+    return Array.isArray(value) ? value.filter((line) => typeof line === 'string').join('\n') : '';
   }
+  return typeof value === 'string' ? value : '';
 };
 
-/** The `update` values that set the part's text, or none when the node type has no such part. */
-export const partValues = (node: Node, part: PartKey, text: string): NodeValues | undefined => {
-  switch (part) {
-    case 'label':
-      return isBoxNode(node) || isEllipseNode(node) ? { label: text } : undefined;
-    case 'text':
-      return isNoteNode(node) ? { text } : undefined;
-    case 'name':
-      return isClassNode(node) ? { name: text.trim() } : undefined;
-    case 'attributes':
-      return isClassNode(node) ? { attributes: lines(text) } : undefined;
-    case 'methods':
-      return isClassNode(node) ? { methods: lines(text) } : undefined;
+/** The `update` values that set the part's text, or none when the node's type has no such part. */
+export const partValues = (registry: NodeRegistry, node: Node, part: PartKey, text: string): NodeValues | undefined => {
+  const field = partOf(registry, node, part);
+  if (!field) {
+    return undefined;
   }
+  return { [field.field]: field.lines ? toLines(text) : text };
+};
+
+/** A node's main text: its first part's, which a diagram or a DSL export shows as the node's name. */
+export const nodeTitle = (registry: NodeRegistry, node: Node): string | undefined => {
+  const [first] = nodeParts(registry, node);
+  return first ? partText(registry, node, first.field) : undefined;
+};
+
+/** The node with its main text (its first part) set; a type without parts is returned as is. */
+export const withTitle = <N extends Node>(registry: NodeRegistry, node: N, text: string): N => {
+  const [first] = nodeParts(registry, node);
+  return first ? { ...node, ...partValues(registry, node, first.field, text) } : node;
 };

package/src/utils/ports.ts

@@ -128,8 +128,8 @@ const distance2 = (left: Point, right: Point) => (left.x - right.x) ** 2 + (left
  * source end only leaves a port that accepts `out`, the target end only lands on one that accepts `in`.
  */
 export const pairPorts = (source: PortTerminal, target: PortTerminal): PortPair | undefined => {
-  const sources = candidates(source, 'out');
-  const targets = candidates(target, 'in');
+  const sources = portCandidates(source, 'out');
+  const targets = portCandidates(target, 'in');
   if (sources.length === 0 || targets.length === 0) {
     return undefined;
   }
@@ -156,7 +156,7 @@ export const nearestPort = (
 ): Port | undefined => {
   let best: Port | undefined;
   let bestDistance = Infinity;
-  for (const port of candidates(terminal, direction)) {
+  for (const port of portCandidates(terminal, direction)) {
     const value = distance2(portPoint(terminal.bounds, port), point);
     if (value < bestDistance) {
       bestDistance = value;
@@ -167,7 +167,10 @@ export const nearestPort = (
 };
 
 /** The ports an end may use: those accepting its direction, narrowed to the pinned one when it is among them. */
-const candidates = ({ ports, port }: PortTerminal, direction: Exclude<PortDirection, 'any'>): readonly Port[] => {
+export const portCandidates = (
+  { ports, port }: PortTerminal,
+  direction: Exclude<PortDirection, 'any'>,
+): readonly Port[] => {
   const allowed = ports.filter((candidate) => portAccepts(candidate, direction));
   if (port === undefined) {
     return allowed;

package/src/utils/properties.test.ts

@@ -7,7 +7,7 @@ import { describe, test } from 'vitest';
 
 import { getPropertySignatures } from '@dxos/effect/SchemaAST';
 
-import { ClassNode, EllipseNode, LineLink, RectNode } from '../model/types.ts';
+import { EllipseNode, LineLink, NoteNode, RectNode } from '../model/types.ts';
 import { commonSchema, mergeValues, patchValues } from './properties.ts';
 
 const names = (schema: Schema.Codec<any, any> | undefined) =>
@@ -24,12 +24,20 @@ describe('properties', () => {
     expect(rectEllipse).toContain('style');
     expect(rectEllipse).not.toContain('type');
 
-    const rectClass = names(commonSchema([RectNode, ClassNode]));
-    expect(rectClass).toContain('style');
-    expect(rectClass).not.toContain('label');
+    const rectNote = names(commonSchema([RectNode, NoteNode]));
+    expect(rectNote).toContain('style');
+    expect(rectNote).not.toContain('label');
 
-    // A node and a link share only what both declare: here `locked` (and the hidden `id`/`z`).
-    expect(names(commonSchema([RectNode, LineLink]))).toEqual(['id', 'z', 'locked']);
+    // A node and a link share only what both declare: `locked`, `layer`, `class` and `style` (and the hidden `id`/`z`),
+    // the style narrowed to the common base both kinds' styles extend.
+    const shared = commonSchema([RectNode, LineLink]);
+    expect(names(shared)).toEqual(['id', 'z', 'locked', 'layer', 'class', 'style']);
+    const style = shared && getPropertySignatures(shared.ast).find((property) => property.name === 'style');
+    const struct = style?.type._tag === 'Union' ? style.type.types.find((type) => type._tag === 'Objects') : undefined;
+    expect(struct?._tag === 'Objects' && struct.propertySignatures.map((property) => property.name)).toEqual([
+      'hue',
+      'lineStyle',
+    ]);
     expect(commonSchema([Schema.Struct({ a: Schema.String }), Schema.Struct({ b: Schema.String })])).toBeUndefined();
   });
 
@@ -52,6 +60,15 @@ describe('properties', () => {
     expect([...mixed].sort()).toEqual(['center.x', 'style.hue']);
   });
 
+  test('an instance value (a reference) is kept whole, not merged field by field', ({ expect }) => {
+    class Reference {
+      constructor(readonly uri: string) {}
+    }
+    const reference = new Reference('echo://space/object');
+    const { values } = mergeValues([{ drawing: reference }], ['drawing']);
+    expect(values.drawing).toBe(reference);
+  });
+
   test('a patch writes only the changed paths and keeps the rest of a nested value', ({ expect }) => {
     const element = { label: 'A', style: { hue: 'red', rounded: true }, center: { x: 0, y: 16 } };
     const values = { label: 'B', style: { hue: 'blue', rounded: false }, center: { x: 48, y: 0 } };

package/src/utils/properties.ts

@@ -8,14 +8,20 @@
 //
 
 import * as Schema from 'effect/Schema';
-import type * as SchemaAST from 'effect/SchemaAST';
+import * as SchemaAST from 'effect/SchemaAST';
 
-import { getChecks, getPropertySignatures, pick } from '@dxos/effect/SchemaAST';
+import { getChecks, getPropertySignatures } from '@dxos/effect/SchemaAST';
 
 type Values = Readonly<Record<string, unknown>>;
 
-const isPlainObject = (value: unknown): value is Values =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A record of fields to merge into; an instance (an ECHO `Ref`, a date) is a value, compared and kept whole. */
+const isPlainObject = (value: unknown): value is Values => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
 
 const isOptional = (ast: SchemaAST.AST) => ast.context?.isOptional ?? false;
 
@@ -76,24 +82,68 @@ const sameList = (left: readonly SchemaAST.AST[], right: readonly SchemaAST.AST[
   left.length === right.length && left.every((type, index) => sameType(type, right[index]));
 
 /**
- * The properties every schema declares alike, as one struct over the first schema's declarations;
- * `undefined` when they share none. One schema is its own common schema.
+ * What two property types share: the type itself when they are the same, and for two structs (a node's style and a
+ * link's, say) the struct of the fields they declare alike, recursively; none when they share nothing.
+ */
+const commonType = (left: SchemaAST.AST, right: SchemaAST.AST): SchemaAST.AST | undefined => {
+  if (sameType(left, right)) {
+    return left;
+  }
+  // An optional struct is a union with `undefined`: intersect member by member.
+  if (left._tag === 'Union' && right._tag === 'Union' && left.types.length === right.types.length) {
+    const types = left.types.map((type, index) => commonType(type, right.types[index]));
+    return types.every((type) => type !== undefined)
+      ? new SchemaAST.Union(
+          types.flatMap((type) => (type ? [type] : [])),
+          left.options,
+          left.annotations,
+          left.checks,
+          left.encoding,
+          left.context,
+          left.encodingChecks,
+        )
+      : undefined;
+  }
+  if (left._tag !== 'Objects' || right._tag !== 'Objects' || isOptional(left) !== isOptional(right)) {
+    return undefined;
+  }
+  const shared = left.propertySignatures.flatMap((property) => {
+    const other = right.propertySignatures.find((candidate) => candidate.name === property.name);
+    const type = other && commonType(property.type, other.type);
+    return type ? [new SchemaAST.PropertySignature(property.name, type)] : [];
+  });
+  return shared.length > 0
+    ? new SchemaAST.Objects(
+        shared,
+        left.indexSignatures,
+        left.annotations,
+        left.checks,
+        left.encoding,
+        left.context,
+        left.encodingChecks,
+      )
+    : undefined;
+};
+
+/**
+ * The properties every schema declares alike, as one struct over the first schema's declarations, a struct
+ * property narrowed to the fields every schema's declares alike; `undefined` when they share none. One schema is
+ * its own common schema.
  */
 export const commonSchema = (schemas: readonly Schema.Codec<any, any>[]): Schema.Codec<any, any> | undefined => {
   const [first, ...rest] = schemas;
   if (!first) {
     return undefined;
   }
-  const shared = getPropertySignatures(first.ast)
-    .filter((property) =>
-      rest.every((schema) =>
-        getPropertySignatures(schema.ast).some(
-          (other) => other.name === property.name && sameType(property.type, other.type),
-        ),
-      ),
-    )
-    .map((property) => property.name);
-  return shared.length > 0 ? Schema.make<Schema.Codec<any, any>>(pick(first.ast, shared)) : undefined;
+  const shared = getPropertySignatures(first.ast).flatMap((property) => {
+    let type: SchemaAST.AST | undefined = property.type;
+    for (const schema of rest) {
+      const other = getPropertySignatures(schema.ast).find((candidate) => candidate.name === property.name);
+      type = type && other ? commonType(type, other.type) : undefined;
+    }
+    return type ? [new SchemaAST.PropertySignature(property.name, type)] : [];
+  });
+  return shared.length > 0 ? Schema.make<Schema.Codec<any, any>>(new SchemaAST.Objects(shared, [])) : undefined;
 };
 
 const equal = (left: unknown, right: unknown): boolean => {

package/src/utils/route.test.ts

@@ -5,9 +5,18 @@
 import { describe, test } from 'vitest';
 
 import { defaultNodeRegistry } from '../model/registry.ts';
-import { type Link } from '../model/types.ts';
+import { type Link, type Scene } from '../model/types.ts';
 import { SceneBuilder } from './builder.ts';
-import { insertIndex, linkGeometry, linkPath, sideToward, smartPoints, splinePath } from './route.ts';
+import { DEFAULT_LATTICE } from './lattice.ts';
+import {
+  insertIndex,
+  linkGeometry,
+  linkPath,
+  sceneLinkGeometry,
+  sideToward,
+  smartPoints,
+  splinePath,
+} from './route.ts';
 
 const from = { point: { x: 0, y: 0 }, side: 'e' as const };
 const to = { point: { x: 300, y: 0 }, side: 'w' as const };
@@ -98,4 +107,44 @@ describe('route', () => {
     expect(half?.target).toEqual({ point: { x: 256, y: 64 }, side: 'e' });
     expect(half?.source.side).toBe('w');
   });
+
+  test('a route runs straight to a free end rather than turning to its side', ({ expect }) => {
+    const port = { point: { x: 0, y: 0 }, side: 'e' as const };
+    const free = { point: { x: 100, y: 37 }, side: 'w' as const, free: true };
+    // A curve's control point at a free end is the end itself, and a smart link has no stub there.
+    expect(
+      linkPath({ type: 'curve', id: 'c', z: 'a', source: { node: 'n' }, target: { point: free.point } }, port, free),
+    ).toMatch(/, 100 37, 100 37$/);
+    expect(smartPoints(port, free)).toEqual([port.point, { x: 32, y: 0 }, free.point]);
+  });
+
+  test('on a lattice a smart link takes the ports whose gutter route bends least', ({ expect }) => {
+    // MESH on (4, 1) and EDGE on (3, 4), as the Composer overview has them: the nearest ports (MESH's bottom-left,
+    // EDGE's top-right) need two bends round EDGE's corner; down the free column and in from the east needs one.
+    const box = (id: string, col: number, row: number) => ({
+      type: 'rect',
+      id,
+      z: 'a0',
+      center: { x: col * 384, y: row * 192 },
+      size: { width: 256, height: 128 },
+    });
+    const link: Link = { type: 'smart', id: 'link', z: 'a1', source: { node: 'mesh' }, target: { node: 'edge' } };
+    const scene: Scene = {
+      id: 'root',
+      nodes: { mesh: box('mesh', 4, 1), edge: box('edge', 3, 4) },
+      links: { link },
+    };
+    const [geometry] = sceneLinkGeometry(scene, defaultNodeRegistry, [link], DEFAULT_LATTICE);
+    expect([geometry.source.side, geometry.source.point, geometry.target.side, geometry.target.point]).toEqual([
+      's',
+      { x: 1536, y: 256 },
+      'e',
+      { x: 1280, y: 768 },
+    ]);
+    // One bend: a single rounded corner between the two straight runs.
+    expect(geometry.path.match(/Q/g)).toHaveLength(1);
+    // The same choice for the link on its own, so hit-testing and handles agree with what is drawn.
+    const single = linkGeometry(scene, defaultNodeRegistry, link, DEFAULT_LATTICE);
+    expect([single?.source.side, single?.target.side]).toEqual(['s', 'e']);
+  });
 });

package/src/utils/route.ts

@@ -25,9 +25,17 @@ import {
   type Side,
   isPointEndpoint,
 } from '../model/types.ts';
-import { gutterRoute } from './gutter-route.ts';
+import { gutterRoute, gutterRouteWithCost } from './gutter-route.ts';
 import { type LatticeSpec } from './lattice.ts';
-import { type PortTerminal, nearestPort, nodePorts, pairPorts, portPoint, sideNormal } from './ports.ts';
+import {
+  type PortTerminal,
+  nearestPort,
+  nodePorts,
+  pairPorts,
+  portCandidates,
+  portPoint,
+  sideNormal,
+} from './ports.ts';
 import { nodeBounds } from './shapes.ts';
 
 const MIN_TANGENT = 40;
@@ -42,7 +50,11 @@ const CORNER_RADIUS = DEFAULT_GRID;
 /** How far a smart link's stub leaves its port, in scene px (half a major cell). */
 const SMART_STUB = MAJOR_GRID / 2;
 
-export type RouteEnd = { point: Point; side: Side };
+/**
+ * A resolved link end. `free` marks a point end (one being dragged, or left on empty canvas): it has no port to
+ * leave along, so a route runs straight to it rather than turning to its side's normal.
+ */
+export type RouteEnd = { point: Point; side: Side; free?: boolean };
 
 const pt = ({ x, y }: Point) => `${x} ${y}`;
 
@@ -52,12 +64,12 @@ const curveControls = (from: RouteEnd, to: RouteEnd): [Point, Point] => {
   const dx = to.point.x - from.point.x;
   const dy = to.point.y - from.point.y;
   const tangent = Math.max(MIN_TANGENT, Math.hypot(dx, dy) * TANGENT_RATIO);
-  const fromNormal = sideNormal(from.side);
-  const toNormal = sideNormal(to.side);
-  return [
-    { x: from.point.x + fromNormal.x * tangent, y: from.point.y + fromNormal.y * tangent },
-    { x: to.point.x + toNormal.x * tangent, y: to.point.y + toNormal.y * tangent },
-  ];
+  // A free end takes no tangent: its control point sits on the end, so the curve arrives straight at it.
+  const control = (end: RouteEnd): Point => {
+    const normal = sideNormal(end.side);
+    return end.free ? end.point : { x: end.point.x + normal.x * tangent, y: end.point.y + normal.y * tangent };
+  };
+  return [control(from), control(to)];
 };
 
 /** Cubic Bézier whose control points sit `tangent` px out along each port's normal. */
@@ -122,7 +134,14 @@ export const linkPath = (link: Link, from: RouteEnd, to: RouteEnd, lattice?: Lat
     case 'spline':
       return splinePath([from.point, ...link.points, to.point]);
     case 'smart':
-      return splinePath((lattice && gutterRoute(lattice.nodes, lattice.spec, from, to)) ?? smartPoints(from, to));
+      // A free end (one being dragged) takes no gutter: the route runs straight to it.
+      return splinePath(
+        (lattice && !from.free && !to.free && gutterRoute(lattice.nodes, lattice.spec, from, to)) ||
+          smartPoints(from, to),
+      );
+    default:
+      // A link type this engine does not know (saved by a newer one) draws as the core base: a straight line.
+      return linePath(from.point, to.point);
   }
 };
 
@@ -135,14 +154,12 @@ export type LatticeRoute = { spec: LatticeSpec; nodes: readonly Node[] };
  * ports imply rather than a straight line cutting across their own nodes.
  */
 export const smartPoints = (from: RouteEnd, to: RouteEnd): Point[] => {
-  const fromNormal = sideNormal(from.side);
-  const toNormal = sideNormal(to.side);
-  return [
-    from.point,
-    { x: from.point.x + fromNormal.x * SMART_STUB, y: from.point.y + fromNormal.y * SMART_STUB },
-    { x: to.point.x + toNormal.x * SMART_STUB, y: to.point.y + toNormal.y * SMART_STUB },
-    to.point,
-  ];
+  // A free end has no stub: the route runs straight to it.
+  const stub = (end: RouteEnd): Point[] => {
+    const normal = sideNormal(end.side);
+    return end.free ? [] : [{ x: end.point.x + normal.x * SMART_STUB, y: end.point.y + normal.y * SMART_STUB }];
+  };
+  return [from.point, ...stub(from), ...stub(to).reverse(), to.point];
 };
 
 export type LinkGeometry = { link: Link; path: string; source: RouteEnd; target: RouteEnd };
@@ -165,6 +182,90 @@ const routeEnd = (terminal: PortTerminal, port: Port): RouteEnd => ({
   side: port.side,
 });
 
+/** Port pairs searched per tier of fewest possible bends. */
+const PAIRS_PER_TIER = 3;
+
+/**
+ * The fewest bends any right-angled route between two ports could take: none when they face each other on one line,
+ * one when their sides are perpendicular and each points toward the corner they share, otherwise at least two.
+ */
+const leastBends = (from: RouteEnd, to: RouteEnd): number => {
+  const out = sideNormal(from.side);
+  // A route arrives at its target moving against the target side's normal.
+  const arrive = sideNormal(to.side);
+  const [dx, dy] = [to.point.x - from.point.x, to.point.y - from.point.y];
+  const ahead = (normal: Point, x: number, y: number) => normal.x * x + normal.y * y > 0;
+  if (out.x === -arrive.x && out.y === -arrive.y) {
+    const aligned = out.x !== 0 ? dy === 0 : dx === 0;
+    return aligned && ahead(out, dx, dy) ? 0 : 2;
+  }
+  if (out.x * arrive.x + out.y * arrive.y === 0) {
+    // The corner is where the source's line meets the target's.
+    const corner = out.x !== 0 ? { x: to.point.x, y: from.point.y } : { x: from.point.x, y: to.point.y };
+    const first = ahead(out, corner.x - from.point.x, corner.y - from.point.y);
+    const second = ahead({ x: -arrive.x, y: -arrive.y }, to.point.x - corner.x, to.point.y - corner.y);
+    return first && second ? 1 : 2;
+  }
+  return 2;
+};
+
+/**
+ * The ends and gutter route of a smart link between two nodes on a lattice: of the pairs of side-centre ports (or the
+ * pinned ones), the one whose route is cheapest, fewest bends first, so a link leaves straight down a free column
+ * rather than from the nearest port round a corner. Pairs are tried nearest first, so a tie keeps the nearest.
+ */
+const latticeEnds = (
+  scene: Scene,
+  registry: NodeRegistry,
+  link: Link,
+  route: LatticeRoute,
+): { from: RouteEnd; to: RouteEnd; points: Point[] } | undefined => {
+  if (link.type !== 'smart' || isPointEndpoint(link.source) || isPointEndpoint(link.target)) {
+    return undefined;
+  }
+  const source = terminalOf(scene, registry, link.source);
+  const target = terminalOf(scene, registry, link.target);
+  if (!source || !target) {
+    return undefined;
+  }
+  // A side's centre, where a side has one; a pinned port or a custom layout keeps what it offers.
+  const centres = (ports: readonly Port[]) => {
+    const middle = ports.filter((port) => port.offset === 0.5);
+    return middle.length > 0 ? middle : ports;
+  };
+  const sources = centres(portCandidates(source, 'out'));
+  const targets = centres(portCandidates(target, 'in'));
+  // Fewest possible bends first, then nearest: the search stops once no pair left could bend less than the best found.
+  const pairs = sources
+    .flatMap((from) => targets.map((to) => ({ from: routeEnd(source, from), to: routeEnd(target, to) })))
+    .map((pair) => ({
+      ...pair,
+      least: leastBends(pair.from, pair.to),
+      distance: Math.hypot(pair.from.point.x - pair.to.point.x, pair.from.point.y - pair.to.point.y),
+    }))
+    .sort((left, right) => left.least - right.least || left.distance - right.distance);
+  let best: { from: RouteEnd; to: RouteEnd; points: Point[]; bends: number } | undefined;
+  // Within a tier only the nearest few are searched: a farther pair seldom routes better, and each search has a cost.
+  const tried = new Map<number, number>();
+  for (const pair of pairs) {
+    if (best && pair.least >= best.bends) {
+      break;
+    }
+    const count = tried.get(pair.least) ?? 0;
+    if (count >= PAIRS_PER_TIER) {
+      continue;
+    }
+    tried.set(pair.least, count + 1);
+    const routed = gutterRouteWithCost(route.nodes, route.spec, pair.from, pair.to);
+    // The route's points are its ends and its corners.
+    const bends = routed ? routed.points.length - 2 : Infinity;
+    if (routed && (!best || bends < best.bends)) {
+      best = { from: pair.from, to: pair.to, points: routed.points, bends };
+    }
+  }
+  return best;
+};
+
 /**
  * Resolve a link's ends and route it by its type: two node ends take the automatic (or pinned) port pair,
  * a node end facing a free point takes the port nearest that point, and two free points face each other.
@@ -175,12 +276,16 @@ export const linkGeometry = (
   link: Link,
   lattice?: LatticeSpec,
 ): LinkGeometry | undefined => {
+  const route = lattice ? { spec: lattice, nodes: Object.values(scene.nodes) } : undefined;
+  const routed = route && latticeEnds(scene, registry, link, route);
+  if (routed) {
+    return { link, path: splinePath(routed.points), source: routed.from, target: routed.to };
+  }
   const ends = resolveEnds(scene, registry, link.source, link.target);
   if (!ends) {
     return undefined;
   }
   const [from, to] = ends;
-  const route = lattice ? { spec: lattice, nodes: Object.values(scene.nodes) } : undefined;
   return { link, path: linkPath(link, from, to, route), source: from, target: to };
 };
 
@@ -193,8 +298,8 @@ const resolveEnds = (
   if (isPointEndpoint(source)) {
     if (isPointEndpoint(target)) {
       return [
-        { point: source.point, side: sideToward(source.point, target.point) },
-        { point: target.point, side: sideToward(target.point, source.point) },
+        { point: source.point, side: sideToward(source.point, target.point), free: true },
+        { point: target.point, side: sideToward(target.point, source.point), free: true },
       ];
     }
     const terminal = terminalOf(scene, registry, target);
@@ -203,7 +308,7 @@ const resolveEnds = (
       return undefined;
     }
     const to = routeEnd(terminal, port);
-    return [{ point: source.point, side: sideToward(source.point, to.point) }, to];
+    return [{ point: source.point, side: sideToward(source.point, to.point), free: true }, to];
   }
   if (isPointEndpoint(target)) {
     const terminal = terminalOf(scene, registry, source);
@@ -212,7 +317,7 @@ const resolveEnds = (
       return undefined;
     }
     const from = routeEnd(terminal, port);
-    return [from, { point: target.point, side: sideToward(target.point, from.point) }];
+    return [from, { point: target.point, side: sideToward(target.point, from.point), free: true }];
   }
   const sourceTerminal = terminalOf(scene, registry, source);
   const targetTerminal = terminalOf(scene, registry, target);
@@ -249,7 +354,12 @@ export const sceneLinkGeometry = (
     const node = isPointEndpoint(end) ? undefined : scene.nodes[end.node];
     return node ? rect(nodeBounds(node)) : undefined;
   };
+  const route = { spec: lattice, nodes };
   const routed = links.flatMap((link) => {
+    const chosen = latticeEnds(scene, registry, link, route);
+    if (chosen) {
+      return [{ link, from: chosen.from, to: chosen.to, points: chosen.points }];
+    }
     const ends = resolveEnds(scene, registry, link.source, link.target);
     if (!ends) {
       return [];