@dxos/diagram 0.11.1

package/src/uml-rules.ts

@@ -0,0 +1,319 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Rule-based pluggable layout: prioritized rules claim disjoint node GROUPS and lay each out in
+// group-local coordinates; groups then pack as super-nodes (ranked by their cross-group edges)
+// with non-overlapping borders, and the shared router connects nodes across them. Rules capture
+// domain shape the generic engines cannot: an inheritance tree reads as a tree, a call chain as
+// a column. See `docs/DESIGN.md`.
+//
+
+import * as Layout from './layout.ts';
+import type * as Scene from './scene.ts';
+import {
+  type Cell,
+  GRID,
+  type CompileOptions as GridCompileOptions,
+  type Rect,
+  emit,
+  measureCell,
+} from './uml-grid.ts';
+import { type UmlModel, parse, relationRanks } from './uml.ts';
+
+const GAP = GRID * 2;
+const GROUP_GAP = GRID * 3;
+const FRAME_PAD = GRID;
+
+const snap = (value: number) => Math.round(value / GRID) * GRID;
+
+/** A laid-out group: member rects in group-local coordinates plus the packed bounds. */
+export type Group = {
+  id: string;
+  /** Rule that claimed the group (frame label; singletons carry none). */
+  rule?: string;
+  rects: Map<string, Rect>;
+  w: number;
+  h: number;
+};
+
+/**
+ * A layout rule: claims disjoint groups from the still-unclaimed nodes and lays each out
+ * internally. Rules run in priority order; unclaimed nodes fall through to singleton groups.
+ */
+export type GroupRule = {
+  id: string;
+  apply: (model: UmlModel, unclaimed: Set<string>, cell: Cell) => Group[];
+};
+
+/** Relations oriented so the target should sit ABOVE the source (arrows read upward). */
+const upEdges = (model: UmlModel): { from: string; to: string }[] =>
+  model.relations.map((relation) =>
+    relation.kind === 'inheritance' || relation.kind === 'realization' || relation.kind === 'dependency'
+      ? { from: relation.from, to: relation.to }
+      : { from: relation.to, to: relation.from },
+  );
+
+/**
+ * Inheritance trees: each supertype with claimable subtypes forms a group — the hierarchy stacks
+ * vertically (root on top, arrows up) and peers share a horizontal axis, packed as a tidy tree
+ * (each parent centered over its subtree).
+ */
+export const inheritanceTreeRule: GroupRule = {
+  id: 'inheritance',
+  apply: (model, unclaimed, cell) => {
+    const children = new Map<string, string[]>();
+    const hasParent = new Set<string>();
+    for (const relation of model.relations) {
+      if (
+        (relation.kind === 'inheritance' || relation.kind === 'realization') &&
+        unclaimed.has(relation.from) &&
+        unclaimed.has(relation.to)
+      ) {
+        // relation: subtype → supertype.
+        children.set(relation.to, [...(children.get(relation.to) ?? []), relation.from]);
+        hasParent.add(relation.from);
+      }
+    }
+
+    const groups: Group[] = [];
+    for (const [root] of children) {
+      if (hasParent.has(root)) {
+        continue;
+      }
+      const rects = new Map<string, Rect>();
+      // Cyclic or diamond hierarchies (LLM/user input) must not recurse forever; each node
+      // renders once, on first visit.
+      const claimable = (id: string) => unclaimed.has(id) && !rects.has(id);
+      const widths = new Map<string, number>();
+      // Tidy-tree: a subtree is as wide as its children row (or one cell); parent centers over it.
+      const layoutSubtree = (id: string, x: number, depth: number): number => {
+        rects.set(id, { x: 0, y: 0, w: cell.w, h: cell.h });
+        const kids = (children.get(id) ?? []).filter(claimable);
+        const kidWidths = kids.map((kid) => subtreeWidth(kid));
+        const rowWidth = kidWidths.reduce((sum, w) => sum + w, 0) + Math.max(0, kids.length - 1) * GAP;
+        const width = Math.max(cell.w, rowWidth);
+        let childX = x + (width - rowWidth) / 2;
+        for (const [index, kid] of kids.entries()) {
+          layoutSubtree(kid, childX, depth + 1);
+          childX += kidWidths[index] + GAP;
+        }
+        rects.set(id, { x: x + (width - cell.w) / 2, y: depth * (cell.h + GAP), w: cell.w, h: cell.h });
+        return width;
+      };
+      const subtreeWidth = (id: string, seen: Set<string> = new Set()): number => {
+        const cached = widths.get(id);
+        if (cached !== undefined) {
+          return cached;
+        }
+        if (seen.has(id)) {
+          return cell.w;
+        }
+        seen.add(id);
+        const kids = (children.get(id) ?? []).filter((kid) => unclaimed.has(kid) && !rects.has(kid) && !seen.has(kid));
+        const width =
+          kids.length === 0
+            ? cell.w
+            : Math.max(cell.w, kids.reduce((sum, kid) => sum + subtreeWidth(kid, seen), 0) + (kids.length - 1) * GAP);
+        widths.set(id, width);
+        return width;
+      };
+      const width = layoutSubtree(root, 0, 0);
+      const depth = Math.max(...[...rects.values()].map((rect) => rect.y)) + cell.h;
+      if (rects.size < 2) {
+        continue;
+      }
+      for (const id of rects.keys()) {
+        unclaimed.delete(id);
+      }
+      groups.push({ id: `tree:${root}`, rule: 'inheritance', rects, w: width, h: depth });
+    }
+    return groups;
+  },
+};
+
+/**
+ * Longest linear chain: the longest path through the still-unclaimed up-oriented relation graph
+ * renders left to right (each target directly right of its source).
+ */
+export const linearChainRule: GroupRule = {
+  id: 'chain',
+  apply: (model, unclaimed, cell) => {
+    const edges = upEdges(model).filter((edge) => unclaimed.has(edge.from) && unclaimed.has(edge.to));
+    const back = Layout.backEdges([...unclaimed], edges);
+    const forward = edges.filter((edge) => !back.has(edge));
+    const next = new Map<string, string[]>();
+    for (const edge of forward) {
+      next.set(edge.from, [...(next.get(edge.from) ?? []), edge.to]);
+    }
+
+    // Longest path by DFS memo (the forward graph is acyclic after back-edge removal).
+    const memo = new Map<string, string[]>();
+    const longestFrom = (id: string): string[] => {
+      const cached = memo.get(id);
+      if (cached) {
+        return cached;
+      }
+      let best: string[] = [];
+      for (const target of next.get(id) ?? []) {
+        const path = longestFrom(target);
+        if (path.length > best.length) {
+          best = path;
+        }
+      }
+      const result = [id, ...best];
+      memo.set(id, result);
+      return result;
+    };
+
+    let chain: string[] = [];
+    for (const id of unclaimed) {
+      const path = longestFrom(id);
+      if (path.length > chain.length) {
+        chain = path;
+      }
+    }
+    if (chain.length < 3) {
+      return [];
+    }
+
+    const rects = new Map<string, Rect>();
+    // Chain runs source → target, reading left to right.
+    chain.forEach((id, index) => {
+      rects.set(id, { x: index * (cell.w + GAP), y: 0, w: cell.w, h: cell.h });
+      unclaimed.delete(id);
+    });
+    return [
+      { id: `chain:${chain[0]}`, rule: 'chain', rects, w: chain.length * cell.w + (chain.length - 1) * GAP, h: cell.h },
+    ];
+  },
+};
+
+export type CompileOptions = Omit<GridCompileOptions, 'route'> & {
+  /** Grouping rules, highest priority first. */
+  rules?: GroupRule[];
+};
+
+/** Run the rules over the model; leftovers become singleton groups. */
+export const buildGroups = (model: UmlModel, cell: Cell, rules: GroupRule[]): Group[] => {
+  const unclaimed = new Set(model.classes.map((entry) => entry.id));
+  const groups: Group[] = [];
+  for (const rule of rules) {
+    groups.push(...rule.apply(model, unclaimed, cell));
+  }
+  for (const id of unclaimed) {
+    groups.push({
+      id: `node:${id}`,
+      rects: new Map([[id, { x: 0, y: 0, w: cell.w, h: cell.h }]]),
+      w: cell.w,
+      h: cell.h,
+    });
+  }
+  return groups;
+};
+
+/**
+ * Pack groups as super-nodes: rank by up-oriented cross-group edges (target group above), then
+ * lay ranks out as rows, bottom rank last — mirroring the node-level convention.
+ */
+export const packGroups = (model: UmlModel, groups: Group[]): Map<string, Scene.Point> => {
+  const groupOf = new Map<string, Group>();
+  for (const group of groups) {
+    for (const id of group.rects.keys()) {
+      groupOf.set(id, group);
+    }
+  }
+  const crossEdges = upEdges(model)
+    .map((edge) => ({ from: groupOf.get(edge.from)!.id, to: groupOf.get(edge.to)!.id }))
+    .filter((edge) => edge.from !== edge.to);
+  const groupRanks = Layout.rank(
+    groups.map((group) => group.id),
+    // Rank grows downward from sources; cross edges point up, so invert.
+    crossEdges.map((edge) => ({ from: edge.to, to: edge.from })),
+  );
+
+  const lanes = new Map<number, Group[]>();
+  for (const group of groups) {
+    const rank = groupRanks.get(group.id) ?? 0;
+    lanes.set(rank, [...(lanes.get(rank) ?? []), group]);
+  }
+  const origins = new Map<string, Scene.Point>();
+  let y = 0;
+  for (const rank of [...lanes.keys()].sort((left, right) => left - right)) {
+    const members = lanes.get(rank)!;
+    let x = 0;
+    for (const group of members) {
+      origins.set(group.id, { x: snap(x), y: snap(y) });
+      x += group.w + GROUP_GAP;
+    }
+    y += Math.max(...members.map((group) => group.h)) + GROUP_GAP;
+  }
+  return origins;
+};
+
+/** Absolute node rects for a (possibly partial) group placement. */
+export const resolveRects = (groups: Group[], origins: Map<string, Scene.Point>): Map<string, Rect> => {
+  const rects = new Map<string, Rect>();
+  for (const group of groups) {
+    const at = origins.get(group.id);
+    if (!at) {
+      continue;
+    }
+    for (const [id, rect] of group.rects) {
+      rects.set(id, { ...rect, x: at.x + rect.x, y: at.y + rect.y });
+    }
+  }
+  return rects;
+};
+
+/** Dashed frames behind multi-node groups. */
+export const frameCommands = (
+  groups: Group[],
+  origins: Map<string, Scene.Point>,
+  { origin = { x: 0, y: 0 }, scale = 1 }: { origin?: Scene.Point; scale?: number } = {},
+): Scene.Command[] =>
+  groups
+    .filter((group) => group.rects.size > 1 && origins.has(group.id))
+    .map((group) => {
+      const at = origins.get(group.id)!;
+      return {
+        op: 'upsert-object',
+        object: {
+          id: `group:${group.id}`,
+          origin: { x: origin.x + (at.x - FRAME_PAD) * scale, y: origin.y + (at.y - FRAME_PAD) * scale },
+          scale,
+          elements: [
+            {
+              kind: 'rect',
+              id: 'frame',
+              x: 0,
+              y: 0,
+              w: group.w + FRAME_PAD * 2,
+              h: group.h + FRAME_PAD * 2,
+              stroke: 'dashed',
+              color: 'grey',
+            },
+          ],
+        },
+      };
+    });
+
+/**
+ * Compile with rule-based grouping: rules claim groups, leftovers become singletons, groups pack
+ * as super-nodes ranked by their cross-group edges (lanes advance vertically; no borders overlap
+ * by construction), and multi-node groups render a dashed frame behind their members.
+ */
+export const compile = (source: string, options: CompileOptions = {}): Scene.Command[] => {
+  const { origin = { x: 0, y: 0 }, scale = 1, maxWidth = GRID * 6 } = options;
+  const rules = options.rules ?? [inheritanceTreeRule, linearChainRule];
+  const model = parse(source);
+  const cell = measureCell(model, { maxWidth, cell: options.cell, titleHeight: options.titleHeight });
+  const groups = buildGroups(model, cell, rules);
+  const origins = packGroups(model, groups);
+  const rects = resolveRects(groups, origins);
+  return [
+    ...frameCommands(groups, origins, { origin, scale }),
+    ...emit({ model, cell, rects, ranks: relationRanks(model) }, { origin, scale }),
+  ];
+};

package/src/uml-search.test.ts

@@ -0,0 +1,108 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { trim } from '@dxos/util';
+
+import type * as Scene from './scene.ts';
+import { measureCell } from './uml-grid.ts';
+import { buildGroups, inheritanceTreeRule, linearChainRule, packGroups, resolveRects } from './uml-rules.ts';
+import { compile, scoreLayout, searchPlacement } from './uml-search.ts';
+import { parse } from './uml.ts';
+
+/** The reference shape: a chain A→B→C→D plus a hierarchy Z <|- X, Z <|- Y linked into it. */
+const SOURCE = trim`
+  classDiagram
+      class A
+      class B
+      class C
+      class D
+      class X
+      class Y
+      class Z
+
+      A ..> B
+      B ..> C
+      C ..> D
+      Z <|-- X
+      Z <|-- Y
+      X ..> B
+`;
+
+describe('uml-search', () => {
+  test('score rewards straight lines and punishes crossings', ({ expect }) => {
+    const model = parse(['classDiagram', 'class A', 'class B', 'A ..> B'].join('\n'));
+    const straight = new Map([
+      ['A', { x: 0, y: 200, w: 100, h: 50 }],
+      ['B', { x: 0, y: 0, w: 100, h: 50 }],
+    ]);
+    const jogged = new Map([
+      ['A', { x: 300, y: 200, w: 100, h: 50 }],
+      ['B', { x: 0, y: 0, w: 100, h: 50 }],
+    ]);
+    expect(scoreLayout(model, straight)).toBe(1);
+    expect(scoreLayout(model, jogged)).toBe(0);
+
+    // Two edges forced across each other score −2 relative to two straight columns.
+    const crossing = parse(
+      ['classDiagram', 'class A', 'class B', 'class C', 'class D', 'A ..> B', 'C ..> D'].join('\n'),
+    );
+    const crossed = new Map([
+      ['A', { x: 0, y: 200, w: 100, h: 50 }],
+      ['B', { x: 300, y: 0, w: 100, h: 50 }],
+      ['C', { x: 300, y: 200, w: 100, h: 50 }],
+      ['D', { x: 0, y: 0, w: 100, h: 50 }],
+    ]);
+    expect(scoreLayout(crossing, crossed)).toBeLessThan(0);
+  });
+
+  test('search starts from the chain and compile keeps the higher-scoring layout', ({ expect }) => {
+    const model = parse(SOURCE);
+    const cell = measureCell(model, { maxWidth: 192 });
+    const groups = buildGroups(model, cell, [inheritanceTreeRule, linearChainRule]);
+
+    const searched = searchPlacement(model, groups);
+    const packed = packGroups(model, groups);
+    const searchedScore = scoreLayout(model, resolveRects(groups, searched));
+    const packedScore = scoreLayout(model, resolveRects(groups, packed));
+
+    // The guarantee is the SELECTION, not search superiority (the search is greedy): the compiled
+    // layout scores at least as high as either candidate.
+    const compiled = objectsOf(compile(SOURCE)).filter(
+      (object) => !object.id.startsWith('group:') && object.id !== 'edges',
+    );
+    const rects = new Map(
+      compiled.map((object) => {
+        const frame = object.elements[0] as Scene.Box;
+        return [object.id, { x: object.origin!.x, y: object.origin!.y, w: frame.w, h: frame.h }];
+      }),
+    );
+    expect(scoreLayout(model, rects)).toBeGreaterThanOrEqual(Math.max(searchedScore, packedScore));
+
+    // The chain group anchors the layout; the hierarchy sits axis-aligned next to it.
+    const chain = groups.find((group) => group.rule === 'chain')!;
+    expect([...chain.rects.keys()]).toEqual(['A', 'B', 'C', 'D']);
+    expect(searched.has(chain.id)).toBe(true);
+  });
+
+  test('compiles every node and both group frames without overlap', ({ expect }) => {
+    const objects = objectsOf(compile(SOURCE));
+    const nodes = objects.filter((object) => !object.id.startsWith('group:') && object.id !== 'edges');
+    expect(nodes.length).toBe(7);
+
+    const frames = objects.filter((object) => object.id.startsWith('group:'));
+    expect(frames.length).toBe(2);
+    const bounds = frames.map((frame) => {
+      const rect = frame.elements[0] as Scene.Box;
+      return { x: frame.origin!.x, y: frame.origin!.y, w: rect.w, h: rect.h };
+    });
+    const [a, b] = bounds;
+    const overlap = a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+    expect(overlap).toBe(false);
+  });
+});
+
+const objectsOf = (commands: Scene.Command[]) =>
+  commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));

package/src/uml-search.ts

@@ -0,0 +1,266 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Scored placement search: the longest chain anchors the center; a greedy tree search walks the
+// relation graph outward, trying candidate positions for each still-unplaced group next to its
+// placed neighbour (above/below preferred, connecting nodes axis-aligned) and keeping the
+// highest-scoring one. The final layout is the better of the search and the rank packing, under
+// one score: +1 per straight connector, −1 per crossing. Entirely custom by necessity — ELK and
+// dagre are one-shot global optimizers with no scoring callback or incremental placement API —
+// but either can still lay out a group's interior or contribute a candidate to the same scorer.
+// See `docs/DESIGN.md`.
+//
+
+import type * as Scene from './scene.ts';
+import { GRID, type CompileOptions as GridCompileOptions, type Rect, emit, measureCell, zRouter } from './uml-grid.ts';
+import {
+  type Group,
+  type GroupRule,
+  buildGroups,
+  frameCommands,
+  inheritanceTreeRule,
+  linearChainRule,
+  packGroups,
+  resolveRects,
+} from './uml-rules.ts';
+import { type UmlModel, parse, relationRanks } from './uml.ts';
+
+const GAP = GRID * 3;
+
+const snap = (value: number) => Math.round(value / GRID) * GRID;
+
+type Point = Scene.Point;
+type Segment = [Point, Point];
+
+const segmentsOf = (points: readonly Point[]): Segment[] =>
+  points.slice(0, -1).map((point, index) => [point, points[index + 1]]);
+
+/** Orthogonal segment crossing: proper intersections plus collinear overlaps. */
+const crosses = ([a1, a2]: Segment, [b1, b2]: Segment): boolean => {
+  const aVertical = a1.x === a2.x;
+  const bVertical = b1.x === b2.x;
+  if (aVertical !== bVertical) {
+    const [v1, v2] = aVertical ? [a1, a2] : [b1, b2];
+    const [h1, h2] = aVertical ? [b1, b2] : [a1, a2];
+    return (
+      v1.x > Math.min(h1.x, h2.x) &&
+      v1.x < Math.max(h1.x, h2.x) &&
+      h1.y > Math.min(v1.y, v2.y) &&
+      h1.y < Math.max(v1.y, v2.y)
+    );
+  }
+  if (aVertical) {
+    return a1.x === b1.x && Math.min(a1.y, a2.y) < Math.max(b1.y, b2.y) && Math.min(b1.y, b2.y) < Math.max(a1.y, a2.y);
+  }
+  return a1.y === b1.y && Math.min(a1.x, a2.x) < Math.max(b1.x, b2.x) && Math.min(b1.x, b2.x) < Math.max(a1.x, a2.x);
+};
+
+/** Direction changes along a polyline, ignoring zero-length segments. */
+const bends = (route: readonly Point[]): number => {
+  const points = route.filter(
+    (point, index) => index === 0 || point.x !== route[index - 1].x || point.y !== route[index - 1].y,
+  );
+  let count = 0;
+  for (let index = 2; index < points.length; index++) {
+    const [a, b, c] = [points[index - 2], points[index - 1], points[index]];
+    if (!((a.x === b.x && b.x === c.x) || (a.y === b.y && b.y === c.y))) {
+      count++;
+    }
+  }
+  return count;
+};
+
+/**
+ * Layout score over the placed subset: +1 per straight or single-bend (L) route, −1 per crossing
+ * pair. Routes come from the cheap Z-router — the score ranks candidates, the A* router draws
+ * the final picture.
+ */
+export const scoreLayout = (model: UmlModel, rects: Map<string, Rect>): number => {
+  const horizontal = model.direction === 'LR' || model.direction === 'RL';
+  const routes: Point[][] = [];
+  for (const relation of model.relations) {
+    const from = rects.get(relation.from);
+    const to = rects.get(relation.to);
+    if (!from || !to) {
+      continue;
+    }
+    routes.push(zRouter({ relation, from, to, horizontal, offset: 0 }));
+  }
+
+  let score = 0;
+  for (const route of routes) {
+    if (bends(route) <= 1) {
+      score += 1;
+    }
+  }
+  for (let a = 0; a < routes.length; a++) {
+    for (let b = a + 1; b < routes.length; b++) {
+      const pairCrosses = segmentsOf(routes[a]).some((left) =>
+        segmentsOf(routes[b]).some((right) => crosses(left, right)),
+      );
+      if (pairCrosses) {
+        score -= 1;
+      }
+    }
+  }
+  return score;
+};
+
+const overlaps = (a: Rect, b: Rect): boolean =>
+  a.x < b.x + b.w + GAP && b.x < a.x + a.w + GAP && a.y < b.y + b.h + GAP && b.y < a.y + a.h + GAP;
+
+/**
+ * Greedy tree search: place the chain (or largest) group first, then repeatedly place the
+ * unplaced group connected to the earliest-placed node, trying axis-aligned candidates around
+ * the anchor (below and above preferred, then right/left, sliding off collisions) and keeping
+ * the best-scoring one.
+ */
+export const searchPlacement = (model: UmlModel, groups: Group[]): Map<string, Scene.Point> => {
+  const groupOf = new Map<string, Group>();
+  for (const group of groups) {
+    for (const id of group.rects.keys()) {
+      groupOf.set(id, group);
+    }
+  }
+
+  const seed =
+    groups.find((group) => group.rule === 'chain') ??
+    [...groups].sort((left, right) => right.rects.size - left.rects.size)[0];
+  // An empty or unparseable source yields no groups; compile then emits an empty scene.
+  if (!seed) {
+    return new Map();
+  }
+
+  const origins = new Map<string, Point>();
+  origins.set(seed.id, { x: 0, y: 0 });
+  const placedNodes: string[] = [...seed.rects.keys()];
+
+  const absolute = (id: string): Rect | undefined => {
+    const group = groupOf.get(id)!;
+    const at = origins.get(group.id);
+    if (!at) {
+      return undefined;
+    }
+    const local = group.rects.get(id)!;
+    return { ...local, x: at.x + local.x, y: at.y + local.y };
+  };
+  const placedBounds = (): Rect[] =>
+    groups.flatMap((group) => {
+      const at = origins.get(group.id);
+      return at ? [{ x: at.x, y: at.y, w: group.w, h: group.h }] : [];
+    });
+
+  while (origins.size < groups.length) {
+    // Frontier: the earliest-placed node with a relation into an unplaced group.
+    let anchorId: string | undefined;
+    let connection: { group: Group; node: string } | undefined;
+    for (const placed of placedNodes) {
+      for (const relation of model.relations) {
+        const other = relation.from === placed ? relation.to : relation.to === placed ? relation.from : undefined;
+        if (other && !origins.has(groupOf.get(other)!.id)) {
+          anchorId = placed;
+          connection = { group: groupOf.get(other)!, node: other };
+          break;
+        }
+      }
+      if (connection) {
+        break;
+      }
+    }
+    // Disconnected remainder: park it right of everything placed so far.
+    if (!connection || !anchorId) {
+      const group = groups.find((candidate) => !origins.has(candidate.id))!;
+      const rightmost = Math.max(...placedBounds().map((rect) => rect.x + rect.w), 0);
+      origins.set(group.id, { x: snap(rightmost + GAP), y: 0 });
+      placedNodes.push(...group.rects.keys());
+      continue;
+    }
+
+    const anchor = absolute(anchorId)!;
+    const local = connection.group.rects.get(connection.node)!;
+    const anchorCenterX = anchor.x + anchor.w / 2;
+    const anchorCenterY = anchor.y + anchor.h / 2;
+    // Candidates align the connecting node's axis with the anchor's, above/below preferred.
+    const candidates: Point[] = [
+      { x: anchorCenterX - local.x - local.w / 2, y: anchor.y + anchor.h + GAP },
+      { x: anchorCenterX - local.x - local.w / 2, y: anchor.y - GAP - connection.group.h },
+      { x: anchor.x + anchor.w + GAP, y: anchorCenterY - local.y - local.h / 2 },
+      { x: anchor.x - GAP - connection.group.w, y: anchorCenterY - local.y - local.h / 2 },
+    ];
+
+    let best: { at: Point; score: number } | undefined;
+    for (const [candidateIndex, candidate] of candidates.entries()) {
+      // Slide along the placement axis (in grid steps) until the group's border clears others.
+      const at = { x: snap(candidate.x), y: snap(candidate.y) };
+      const bounds = placedBounds();
+      let tries = 0;
+      // The first two candidates are the below/above placements; index, not coordinate
+      // coincidence, decides the slide axis.
+      const vertical = candidateIndex < 2;
+      while (
+        bounds.some((rect) => overlaps(rect, { x: at.x, y: at.y, w: connection.group.w, h: connection.group.h })) &&
+        tries < 24
+      ) {
+        if (vertical) {
+          at.x += GRID * 2;
+        } else {
+          at.y += GRID * 2;
+        }
+        tries++;
+      }
+      if (tries >= 24) {
+        continue;
+      }
+      origins.set(connection.group.id, at);
+      const score = scoreLayout(model, resolveRects(groups, originsSubset(groups, origins)));
+      origins.delete(connection.group.id);
+      // Strict >, so earlier (preferred: below, then above) candidates win ties.
+      if (!best || score > best.score) {
+        best = { at, score };
+      }
+    }
+
+    const at = best?.at ?? { x: snap(Math.max(...placedBounds().map((rect) => rect.x + rect.w)) + GAP), y: 0 };
+    origins.set(connection.group.id, at);
+    placedNodes.push(...connection.group.rects.keys());
+  }
+
+  // Normalize the top-left to (0, 0).
+  const minX = Math.min(...[...origins.values()].map((point) => point.x));
+  const minY = Math.min(...[...origins.values()].map((point) => point.y));
+  return new Map([...origins].map(([id, point]) => [id, { x: point.x - minX, y: point.y - minY }]));
+};
+
+/** Placement restricted to placed groups, so partial layouts score without phantom rects. */
+const originsSubset = (groups: Group[], origins: Map<string, Point>): Map<string, Point> =>
+  new Map(groups.filter((group) => origins.has(group.id)).map((group) => [group.id, origins.get(group.id)!]));
+
+export type CompileOptions = Omit<GridCompileOptions, 'route'> & {
+  rules?: GroupRule[];
+};
+
+/**
+ * Compile via the scored search, falling back to whichever of {search, rank packing} scores
+ * higher — the search is greedy, so the packing occasionally beats it.
+ */
+export const compile = (source: string, options: CompileOptions = {}): Scene.Command[] => {
+  const { origin = { x: 0, y: 0 }, scale = 1, maxWidth = GRID * 6 } = options;
+  const rules = options.rules ?? [inheritanceTreeRule, linearChainRule];
+  const model = parse(source);
+  const cell = measureCell(model, { maxWidth, cell: options.cell, titleHeight: options.titleHeight });
+  const groups = buildGroups(model, cell, rules);
+
+  const searched = searchPlacement(model, groups);
+  const packed = packGroups(model, groups);
+  const searchedScore = scoreLayout(model, resolveRects(groups, searched));
+  const packedScore = scoreLayout(model, resolveRects(groups, packed));
+  const origins = searchedScore >= packedScore ? searched : packed;
+
+  const rects = resolveRects(groups, origins);
+  return [
+    ...frameCommands(groups, origins, { origin, scale }),
+    ...emit({ model, cell, rects, ranks: relationRanks(model) }, { origin, scale }),
+  ];
+};