@dxos/diagram 0.11.1

package/src/objective.ts

@@ -0,0 +1,157 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The layout objective: how heuristics are expressed. A heuristic is either a CONSTRAINT (hard —
+// a layout that violates it is not acceptable) or a COST TERM (soft — weighted, minimized). Both
+// are evaluated over the emitted scene through `Diagnostics`, so the objective that picks a layout
+// and the report that grades one are the same measurements. Engines and rules are candidate
+// generators; the objective is the judge. See `docs/DESIGN.md`.
+//
+
+import { invariant } from '@dxos/invariant';
+
+import type * as Diagnostics from './diagnostics.ts';
+import type * as Scene from './scene.ts';
+import { GRID } from './uml-grid.ts';
+
+/** A candidate layout: the scene plus its analysis. */
+export type Layout = {
+  objects: readonly Scene.WorldObject[];
+  report: Diagnostics.Report;
+};
+
+/** Hard requirement; `violations` names each way the layout breaks it, empty when it holds. */
+export type Constraint = {
+  id: string;
+  description: string;
+  violations: (layout: Layout) => readonly string[];
+};
+
+/** Soft preference; `measure` is in the term's natural unit and `weight` converts it to cost. */
+export type CostTerm = {
+  id: string;
+  description: string;
+  weight: number;
+  measure: (layout: Layout) => number;
+};
+
+export type Objective = {
+  constraints: readonly Constraint[];
+  costs: readonly CostTerm[];
+};
+
+export type Evaluation = {
+  violations: readonly { constraint: string; message: string }[];
+  /** Weighted sum of the cost terms. */
+  cost: number;
+  terms: readonly { id: string; value: number; weighted: number }[];
+};
+
+export const evaluate = (objective: Objective, layout: Layout): Evaluation => {
+  const violations = objective.constraints.flatMap((constraint) =>
+    constraint.violations(layout).map((message) => ({ constraint: constraint.id, message })),
+  );
+  const terms = objective.costs.map((term) => {
+    const value = term.measure(layout);
+    return { id: term.id, value, weighted: value * term.weight };
+  });
+  return { violations, cost: terms.reduce((total, term) => total + term.weighted, 0), terms };
+};
+
+export type Ranked<T> = { candidate: T; evaluation: Evaluation };
+
+/**
+ * Picks the best candidate: fewest constraint violations first (so an infeasible set still yields
+ * the least-bad layout rather than nothing), then lowest cost. Stable on ties, so the generator's
+ * own order breaks them.
+ */
+export const select = <T extends { layout: Layout }>(
+  objective: Objective,
+  candidates: readonly T[],
+): { chosen: Ranked<T>; ranked: readonly Ranked<T>[] } => {
+  invariant(candidates.length > 0, 'select needs at least one candidate');
+  const ranked = candidates
+    .map((candidate) => ({ candidate, evaluation: evaluate(objective, candidate.layout) }))
+    .sort(
+      (left, right) =>
+        left.evaluation.violations.length - right.evaluation.violations.length ||
+        left.evaluation.cost - right.evaluation.cost,
+    );
+  return { chosen: ranked[0], ranked };
+};
+
+//
+// Built-in constraints and cost terms. Weights are in "one crossing ≈ three bends" units; the
+// corpus snapshots are where a weight change shows its consequences.
+//
+
+/** Every `error` diagnostic is a violation: overlaps, routes through nodes, labels that do not fit. */
+export const noHardDefects: Constraint = {
+  id: 'no-hard-defects',
+  description: 'No node overlaps, no connector through a node, every label fits its shape.',
+  violations: ({ report }) =>
+    report.diagnostics.filter(({ severity }) => severity === 'error').map(({ message }) => message),
+};
+
+/** Containers keep at least `gap` between them, so packages read as separate. */
+export const framesApart = (gap: number = GRID): Constraint => ({
+  id: 'frames-apart',
+  description: `Frames are at least ${gap} apart.`,
+  violations: ({ report }) =>
+    report.metrics.containers >= 2 && report.metrics.frameGapMin < gap
+      ? [`Frames are ${report.metrics.frameGapMin} apart; at least ${gap} required.`]
+      : [],
+});
+
+export const crossings: CostTerm = {
+  id: 'crossings',
+  description: 'Connector pairs that cross.',
+  weight: 3,
+  measure: ({ report }) => report.metrics.crossings,
+};
+
+export const bends: CostTerm = {
+  id: 'bends',
+  description: 'Turns taken by connectors.',
+  weight: 1,
+  measure: ({ report }) => report.metrics.bends,
+};
+
+/**
+ * Uneven gutters between frames, in grid units. Weighted so a whole cell of unevenness costs about
+ * half a crossing: on the pipeline corpus diagram a weight of 2 made the objective accept three
+ * crossings to even out a 7-unit spread, which no reader would.
+ */
+export const unevenFrameGaps: CostTerm = {
+  id: 'uneven-frame-gaps',
+  description: 'Spread of the gaps between neighbouring frames.',
+  weight: 0.5,
+  measure: ({ report }) => report.metrics.frameGapSpread / GRID,
+};
+
+/**
+ * Total connector length in grid units: a long edge is hard to follow even when it is straight.
+ * Weighted so ~100 grid units of extra connector cost one crossing — at 0.1 the objective traded
+ * crossings for shorter edges on the compute and edge corpus diagrams.
+ */
+export const connectorLength: CostTerm = {
+  id: 'connector-length',
+  description: 'Total connector length.',
+  weight: 0.03,
+  measure: ({ report }) => report.metrics.length / GRID,
+};
+
+/** Bounding perimeter in grid units; a light preference for the tighter of otherwise-equal layouts. */
+export const compactness: CostTerm = {
+  id: 'compactness',
+  description: 'Bounding width + height.',
+  weight: 0.05,
+  measure: ({ report }) => (report.metrics.width + report.metrics.height) / GRID,
+};
+
+export const DEFAULT: Objective = {
+  constraints: [noHardDefects, framesApart()],
+  costs: [crossings, bends, connectorLength, unevenFrameGaps, compactness],
+};

package/src/ortho-router.ts

@@ -0,0 +1,372 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Obstacle-avoiding orthogonal router: A* over a fine grid with a turn-dominant cost, so a
+// connector never crosses a node and takes the fewest bends that avoidance allows (length breaks
+// ties). A shared usage penalty nudges later edges off cells earlier edges already run through.
+// Plugs into the dialects via the `Router` contract (`uml-grid.ts`).
+//
+
+import type * as Scene from './scene.ts';
+import type { Rect, RoutedRelation, Router } from './uml-grid.ts';
+
+/** Clearance kept between a route and any node border, in steps. */
+const CLEARANCE = 1;
+/** One bend costs as much as this many steps — turns dominate, distance breaks ties. */
+const TURN_COST = 1000;
+/** Traversing a cell another edge already used costs this many extra steps. */
+const USED_COST = 24;
+/** Margin around the diagram bounds the search may roam into, in steps. */
+const MARGIN = 8;
+
+type Point = Scene.Point;
+
+/** Directions: right, down, left, up. */
+const DX = [1, 0, -1, 0];
+const DY = [0, 1, 0, -1];
+
+export type AvoidingRouterOptions = {
+  /** Search-cell size (scene px): a fraction of the layout grid, so routes can hug node borders. */
+  step: number;
+};
+
+/**
+ * Creates a router that avoids the given node rects. Stateful across edges: earlier routes
+ * penalize (not block) the cells they occupy, spreading parallel runs apart. `fallback` handles
+ * the (fenced-in) edges the search cannot reach. The step is passed in rather than derived from
+ * `uml-grid`'s `GRID`, which keeps this module free of a value import cycle with the dialects.
+ */
+export const makeAvoidingRouter = (
+  obstacles: Rect[],
+  fallback: Router,
+  { step: STEP }: AvoidingRouterOptions,
+): Router => {
+  const xs = obstacles.flatMap((rect) => [rect.x, rect.x + rect.w]);
+  const ys = obstacles.flatMap((rect) => [rect.y, rect.y + rect.h]);
+  const bounds = {
+    x0: Math.floor(Math.min(...xs) / STEP) - MARGIN,
+    y0: Math.floor(Math.min(...ys) / STEP) - MARGIN,
+    x1: Math.ceil(Math.max(...xs) / STEP) + MARGIN,
+    y1: Math.ceil(Math.max(...ys) / STEP) + MARGIN,
+  };
+  const width = bounds.x1 - bounds.x0 + 1;
+  const height = bounds.y1 - bounds.y0 + 1;
+  const inBounds = (x: number, y: number) => x >= bounds.x0 && x <= bounds.x1 && y >= bounds.y0 && y <= bounds.y1;
+  const cellIndex = (x: number, y: number) => (y - bounds.y0) * width + (x - bounds.x0);
+
+  // Flat grids in place of per-cell string keys: the search touches every cell many times over and
+  // the string building was half its running time.
+  const blockedGrid = new Uint8Array(width * height);
+  for (const rect of obstacles) {
+    const x0 = Math.floor(rect.x / STEP) - CLEARANCE;
+    const y0 = Math.floor(rect.y / STEP) - CLEARANCE;
+    const x1 = Math.ceil((rect.x + rect.w) / STEP) + CLEARANCE;
+    const y1 = Math.ceil((rect.y + rect.h) / STEP) + CLEARANCE;
+    for (let y = Math.max(bounds.y0, y0 + 1); y < Math.min(bounds.y1 + 1, y1); y++) {
+      for (let x = Math.max(bounds.x0, x0 + 1); x < Math.min(bounds.x1 + 1, x1); x++) {
+        blockedGrid[cellIndex(x, y)] = 1;
+      }
+    }
+  }
+  const blocked = (x: number, y: number) => inBounds(x, y) && blockedGrid[cellIndex(x, y)] !== 0;
+  const usedGrid = new Uint8Array(width * height);
+  const isUsed = (x: number, y: number) => inBounds(x, y) && usedGrid[cellIndex(x, y)] !== 0;
+  const markUsed = (x: number, y: number) => {
+    if (inBounds(x, y)) {
+      usedGrid[cellIndex(x, y)] = 1;
+    }
+  };
+  // Settled costs per (cell, heading), reused across searches through a generation stamp so no
+  // search pays to clear them.
+  const settledCost = new Float64Array(width * height * 4);
+  const settledGen = new Int32Array(width * height * 4);
+  let generation = 0;
+
+  /** `f` is cost + estimate, the heap's key. */
+  type State = { x: number; y: number; dir: number; cost: number; f: number; prev?: State };
+  type Terminal = { point: Point; dir: number };
+  type Found = { cost: number; cells: Point[] };
+
+  /** Binary min-heap on cost + estimate, so each pop is O(log n) instead of a frontier scan. */
+  const heapPush = (heap: State[], state: State) => {
+    heap.push(state);
+    let index = heap.length - 1;
+    while (index > 0) {
+      const parent = (index - 1) >> 1;
+      if (heap[parent].f <= heap[index].f) {
+        break;
+      }
+      [heap[parent], heap[index]] = [heap[index], heap[parent]];
+      index = parent;
+    }
+  };
+  const heapPop = (heap: State[]): State => {
+    const top = heap[0];
+    const last = heap.pop()!;
+    if (heap.length > 0) {
+      heap[0] = last;
+      let index = 0;
+      for (;;) {
+        const left = index * 2 + 1;
+        const right = left + 1;
+        let smallest = index;
+        if (left < heap.length && heap[left].f < heap[smallest].f) {
+          smallest = left;
+        }
+        if (right < heap.length && heap[right].f < heap[smallest].f) {
+          smallest = right;
+        }
+        if (smallest === index) {
+          break;
+        }
+        [heap[smallest], heap[index]] = [heap[index], heap[smallest]];
+        index = smallest;
+      }
+    }
+    return top;
+  };
+
+  /**
+   * Fewest turns any path from (x, y) heading `dir` needs to reach the target: none while aligned
+   * and heading at it, two when heading away along its axis, otherwise one. Admissible, and since
+   * a turn costs as much as a thousand steps it is what makes the search converge on a diagram
+   * hundreds of cells across — distance alone leaves it exploring almost uniformly.
+   */
+  const turnsNeeded = (x: number, y: number, dir: number, target: Point): number => {
+    const dx = target.x - x;
+    const dy = target.y - y;
+    if (dx !== 0 && dy !== 0) {
+      return 1;
+    }
+    if (dx === 0 && dy === 0) {
+      return 0;
+    }
+    const towards = dx !== 0 ? (dx > 0 ? 0 : 2) : dy > 0 ? 1 : 3;
+    return dir === towards ? 0 : (dir + 2) % 4 === towards ? 2 : 1;
+  };
+
+  const estimateFrom = (x: number, y: number, dir: number, target: Point): number =>
+    Math.abs(target.x - x) + Math.abs(target.y - y) + turnsNeeded(x, y, dir, target) * TURN_COST;
+
+  // Every cell in every heading, so a reachable target is never abandoned on a large diagram.
+  const budget = Math.max(50_000, (bounds.x1 - bounds.x0) * (bounds.y1 - bounds.y0) * 4);
+
+  /**
+   * Bounded A* between two stub ends (grid coordinates). Successors already dominated by a
+   * settled state are pruned before pushing; undefined when the target is unreachable.
+   */
+  const search = (source: Point, startDir: number, target: Point, endDir: number): Found | undefined => {
+    const open: State[] = [
+      { x: source.x, y: source.y, dir: startDir, cost: 0, f: estimateFrom(source.x, source.y, startDir, target) },
+    ];
+    generation++;
+    const settledAt = (index: number) => (settledGen[index] === generation ? settledCost[index] : undefined);
+    let found: State | undefined;
+
+    for (let iterations = 0; open.length > 0 && iterations < budget; iterations++) {
+      const current = heapPop(open);
+      if (current.x === target.x && current.y === target.y) {
+        found = current;
+        break;
+      }
+      const stateIndex = cellIndex(current.x, current.y) * 4 + current.dir;
+      const seen = settledAt(stateIndex);
+      if (seen !== undefined && seen <= current.cost) {
+        continue;
+      }
+      settledGen[stateIndex] = generation;
+      settledCost[stateIndex] = current.cost;
+
+      for (let dir = 0; dir < 4; dir++) {
+        if ((dir + 2) % 4 === current.dir) {
+          continue;
+        }
+        const x = current.x + DX[dir];
+        const y = current.y + DY[dir];
+        if (!inBounds(x, y)) {
+          continue;
+        }
+        const cell = cellIndex(x, y);
+        if (blockedGrid[cell] !== 0) {
+          continue;
+        }
+        const cost =
+          current.cost +
+          1 +
+          (dir === current.dir ? 0 : TURN_COST) +
+          (usedGrid[cell] !== 0 ? USED_COST : 0) +
+          // Entering the target off-axis forces one more bend at arrival; fold it in.
+          (x === target.x && y === target.y && dir !== endDir ? TURN_COST : 0);
+        const dominated = settledAt(cell * 4 + dir);
+        if (dominated !== undefined && dominated <= cost) {
+          continue;
+        }
+        heapPush(open, { x, y, dir, cost, f: cost + estimateFrom(x, y, dir, target), prev: current });
+      }
+    }
+
+    if (!found) {
+      return undefined;
+    }
+    const cells: Point[] = [];
+    for (let state: State | undefined = found; state; state = state.prev) {
+      cells.unshift({ x: state.x, y: state.y });
+    }
+    return { cost: found.cost, cells };
+  };
+
+  return (edge: RoutedRelation): Point[] => {
+    const { from, to, horizontal, ports } = edge;
+    // Flow-axis faces mirror the Z-router (and the port assignment in `emit`).
+    const sameLane = horizontal ? from.x === to.x : from.y === to.y;
+    const alongY = horizontal ? sameLane : !sameLane;
+
+    const down = to.y >= from.y;
+    const right = to.x >= from.x;
+    const flowStart: Terminal = alongY
+      ? { point: { x: ports?.start ?? from.x + from.w / 2, y: down ? from.y + from.h : from.y }, dir: down ? 1 : 3 }
+      : { point: { x: right ? from.x + from.w : from.x, y: ports?.start ?? from.y + from.h / 2 }, dir: right ? 0 : 2 };
+    const flowEnd: Terminal = alongY
+      ? { point: { x: ports?.end ?? to.x + to.w / 2, y: down ? to.y : to.y + to.h }, dir: down ? 1 : 3 }
+      : { point: { x: right ? to.x : to.x + to.w, y: ports?.end ?? to.y + to.h / 2 }, dir: right ? 0 : 2 };
+    // Cross-axis faces enable single-bend Ls when the displacement is diagonal — a fixed
+    // flow-face pair forces a Z between laterally offset nodes.
+    const crossStart: Terminal = alongY
+      ? { point: { x: right ? from.x + from.w : from.x, y: from.y + from.h / 2 }, dir: right ? 0 : 2 }
+      : { point: { x: from.x + from.w / 2, y: down ? from.y + from.h : from.y }, dir: down ? 1 : 3 };
+    const crossEnd: Terminal = alongY
+      ? { point: { x: right ? to.x : to.x + to.w, y: to.y + to.h / 2 }, dir: right ? 0 : 2 }
+      : { point: { x: to.x + to.w / 2, y: down ? to.y : to.y + to.h }, dir: down ? 1 : 3 };
+
+    const diagonal = alongY ? flowStart.point.x !== flowEnd.point.x : flowStart.point.y !== flowEnd.point.y;
+    const configurations: [Terminal, Terminal][] = diagonal
+      ? [
+          [flowStart, flowEnd],
+          [crossStart, flowEnd],
+          [flowStart, crossEnd],
+        ]
+      : [[flowStart, flowEnd]];
+
+    // Stubs step from the border past the clearance zone; A* runs between the stub ends.
+    // Rounded to whole cells: ports may sit on exact fractional coordinates (collision fallback),
+    // and a fractional goal cell would never match — the visible sub-cell offset lives in the
+    // first/last segment.
+    const stub = (point: Point, dir: number, out: boolean): Point => {
+      const sign = out ? 1 : -1;
+      return {
+        x: Math.round(point.x / STEP) + DX[dir] * (CLEARANCE + 1) * sign,
+        y: Math.round(point.y / STEP) + DY[dir] * (CLEARANCE + 1) * sign,
+      };
+    };
+
+    let start: Point | undefined;
+    let end: Point | undefined;
+    let best: Found | undefined;
+    for (const [startTerminal, endTerminal] of configurations) {
+      const result = search(
+        stub(startTerminal.point, startTerminal.dir, true),
+        startTerminal.dir,
+        stub(endTerminal.point, endTerminal.dir, false),
+        endTerminal.dir,
+      );
+      if (result && (!best || result.cost < best.cost)) {
+        best = result;
+        start = startTerminal.point;
+        end = endTerminal.point;
+      }
+    }
+    if (!best || !start || !end) {
+      return fallback(edge);
+    }
+
+    // Reconstruct and collapse collinear points; usage is marked from the FINAL path below, so
+    // the centering pass can distinguish foreign channels from this edge's own cells.
+    const points: Point[] = [start, ...best.cells.map((cell) => ({ x: cell.x * STEP, y: cell.y * STEP })), end];
+    const simplified: Point[] = [points[0]];
+    for (let index = 1; index < points.length - 1; index++) {
+      const previous = simplified[simplified.length - 1];
+      const next = points[index + 1];
+      const point = points[index];
+      const collinear =
+        (previous.x === point.x && point.x === next.x) || (previous.y === point.y && point.y === next.y);
+      if (!collinear) {
+        simplified.push(point);
+      }
+    }
+    simplified.push(points[points.length - 1]);
+
+    // A single-jog Z centers its middle run equidistant from the two node borders — the A* path
+    // is turn-minimal but expansion order lets it hug one node. Keep the shift only if the
+    // adjusted segments avoid every obstacle AND every cell earlier edges already run through,
+    // so parallel channels stay separated.
+    const clearRun = (a: Point, b: Point): boolean => {
+      const ax = Math.round(a.x / STEP);
+      const ay = Math.round(a.y / STEP);
+      const bx = Math.round(b.x / STEP);
+      const by = Math.round(b.y / STEP);
+      const steps = Math.max(Math.abs(bx - ax), Math.abs(by - ay));
+      const dx = Math.sign(bx - ax);
+      const dy = Math.sign(by - ay);
+      for (let step = 0; step <= steps; step++) {
+        if (blocked(ax + dx * step, ay + dy * step) || isUsed(ax + dx * step, ay + dy * step)) {
+          return false;
+        }
+      }
+      return true;
+    };
+    // Stub checks start past the terminal's own clearance zone, which is legitimately "blocked".
+    const past = (from: Point, to: Point): Point => ({
+      x: from.x + Math.sign(to.x - from.x) * (CLEARANCE + 1) * STEP,
+      y: from.y + Math.sign(to.y - from.y) * (CLEARANCE + 1) * STEP,
+    });
+    if (simplified.length === 4) {
+      const [p0, p1, p2, p3] = simplified;
+      if (p1.y === p2.y && p0.y !== p3.y) {
+        const mid = Math.round((p0.y + p3.y) / 2 / STEP) * STEP;
+        const shifted = [
+          { x: p1.x, y: mid },
+          { x: p2.x, y: mid },
+        ];
+        if (
+          clearRun(shifted[0], shifted[1]) &&
+          clearRun(past(p0, shifted[0]), shifted[0]) &&
+          clearRun(shifted[1], past(p3, shifted[1]))
+        ) {
+          simplified[1] = shifted[0];
+          simplified[2] = shifted[1];
+        }
+      } else if (p1.x === p2.x && p0.x !== p3.x) {
+        const mid = Math.round((p0.x + p3.x) / 2 / STEP) * STEP;
+        const shifted = [
+          { x: mid, y: p1.y },
+          { x: mid, y: p2.y },
+        ];
+        if (
+          clearRun(shifted[0], shifted[1]) &&
+          clearRun(past(p0, shifted[0]), shifted[0]) &&
+          clearRun(shifted[1], past(p3, shifted[1]))
+        ) {
+          simplified[1] = shifted[0];
+          simplified[2] = shifted[1];
+        }
+      }
+    }
+
+    // Mark the final path's cells so later edges route (and center) around it.
+    for (let index = 0; index < simplified.length - 1; index++) {
+      const a = simplified[index];
+      const b = simplified[index + 1];
+      const ax = Math.round(a.x / STEP);
+      const ay = Math.round(a.y / STEP);
+      const steps = Math.max(Math.abs(Math.round(b.x / STEP) - ax), Math.abs(Math.round(b.y / STEP) - ay));
+      const dx = Math.sign(b.x - a.x);
+      const dy = Math.sign(b.y - a.y);
+      for (let step = 0; step <= steps; step++) {
+        markUsed(ax + dx * step, ay + dy * step);
+      }
+    }
+    return simplified;
+  };
+};

package/src/scene.test.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { Element, formatRef, parseRef, resolveRef } from './scene.ts';
+
+describe('scene refs', () => {
+  test('parses every ref form', ({ expect }) => {
+    expect(parseRef('box')).toEqual({ element: 'box' });
+    expect(parseRef('face/box')).toEqual({ object: 'face', element: 'box' });
+    expect(parseRef('box#east')).toEqual({ element: 'box', port: 'east' });
+    expect(parseRef('face/box#east')).toEqual({ object: 'face', element: 'box', port: 'east' });
+  });
+
+  test('formatRef inverts parseRef', ({ expect }) => {
+    for (const ref of ['box', 'face/box', 'box#east', 'face/box#east']) {
+      expect(formatRef(parseRef(ref))).toBe(ref);
+    }
+  });
+
+  test('resolveRef yields the object/element handle without the port', ({ expect }) => {
+    expect(resolveRef('box', 'face')).toBe('face/box');
+    expect(resolveRef('box#east', 'face')).toBe('face/box');
+    expect(resolveRef('hat/brim#south', 'face')).toBe('hat/brim');
+  });
+});
+
+describe('scene elements', () => {
+  test('accepts a portal', ({ expect }) => {
+    const portal = { kind: 'portal', id: 'child', x: 0, y: 0, w: 128, h: 96, ref: 'dxn:echo:@:abc', text: 'Child' };
+    expect(Schema.decodeUnknownSync(Element)(portal)).toEqual(portal);
+  });
+});