@dxos/diagram 0.11.1

package/src/mermaid.test.ts

@@ -0,0 +1,138 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { compile, 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. */
+export const FLOWCHART = `
+flowchart TB
+    X[X]
+
+    subgraph CORE[" "]
+        A[A]
+        B[B]
+        C[C]
+
+        A --> B
+        A --> C
+    end
+
+    Y[Y]
+
+    X --> A
+    X --> B
+    X --> C
+    C --> Y
+    Y --> C
+`;
+
+const objectsOf = (commands: Scene.Command[]) =>
+  commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));
+
+describe('mermaid', () => {
+  test('parses nodes, subgraph membership and edges', ({ expect }) => {
+    const graph = parse(FLOWCHART);
+
+    expect(graph.direction).toBe('TB');
+    expect(graph.nodes.map((node) => node.id).sort()).toEqual(['A', 'B', 'C', 'X', 'Y']);
+    expect(graph.groups.map((group) => group.id)).toEqual(['CORE']);
+    expect(graph.groups[0].children.sort()).toEqual(['A', 'B', 'C']);
+    // Nodes declared outside the subgraph carry no group.
+    expect(graph.nodes.find((node) => node.id === 'X')?.group).toBeUndefined();
+    expect(graph.nodes.find((node) => node.id === 'A')?.group).toBe('CORE');
+    expect(graph.edges.map((edge) => `${edge.from}->${edge.to}`)).toEqual([
+      'A->B',
+      'A->C',
+      'X->A',
+      'X->B',
+      'X->C',
+      'C->Y',
+      'Y->C',
+    ]);
+  });
+
+  test('compiles to one object per node plus a frame and an edge object', ({ expect }) => {
+    const objects = objectsOf(compile(FLOWCHART));
+
+    expect(objects.map((object) => object.id)).toEqual(['CORE', 'X', 'A', 'B', 'C', 'Y', 'edges']);
+    // Every node is a single labelled box; the label is the mermaid text, not the id.
+    for (const id of ['X', 'A', 'B', 'C', 'Y']) {
+      const [element] = objects.find((object) => object.id === id)!.elements;
+      expect(element).toMatchObject({ kind: 'rect', id: 'box', text: id });
+    }
+    // The blank subgraph label yields a frame with no text.
+    const frame = objects.find((object) => object.id === 'CORE')!.elements[0];
+    expect(frame).toMatchObject({ kind: 'rect', id: 'frame', stroke: 'dashed' });
+    expect(frame).not.toHaveProperty('text');
+  });
+
+  test('ranks nodes by longest path and breaks the C/Y cycle', ({ expect }) => {
+    const objects = objectsOf(compile(FLOWCHART));
+    const y = (id: string) => objects.find((object) => object.id === id)!.origin!.y;
+
+    // X feeds everything, so it leads; B and C sit past A because the longest path wins over the
+    // direct X edge. `Y --> C` is a back edge and must not push C below Y.
+    expect(y('X')).toBeLessThan(y('A'));
+    expect(y('A')).toBeLessThan(y('B'));
+    expect(y('A')).toBeLessThan(y('C'));
+    expect(y('B')).toBe(y('C'));
+    expect(y('C')).toBeLessThan(y('Y'));
+  });
+
+  test('binds arrows to node boxes, including both directions of the cycle', ({ expect }) => {
+    const edges = objectsOf(compile(FLOWCHART)).find((object) => object.id === 'edges')!;
+    const refs = edges.elements.map((element) => (element.kind === 'arrow' ? `${element.from}->${element.to}` : ''));
+
+    expect(refs).toContain('C/box->Y/box');
+    expect(refs).toContain('Y/box->C/box');
+    expect(edges.elements.every((element) => element.kind === 'arrow')).toBe(true);
+  });
+
+  test('frame encloses its members', ({ expect }) => {
+    const objects = objectsOf(compile(FLOWCHART));
+    const core = objects.find((object) => object.id === 'CORE')!;
+    const frame = core.elements[0] as Scene.Box;
+
+    for (const id of ['A', 'B', 'C']) {
+      const node = objects.find((object) => object.id === id)!;
+      expect(node.origin!.x).toBeGreaterThanOrEqual(core.origin!.x);
+      expect(node.origin!.y).toBeGreaterThanOrEqual(core.origin!.y);
+      expect(node.origin!.x).toBeLessThanOrEqual(core.origin!.x + frame.w);
+      expect(node.origin!.y).toBeLessThanOrEqual(core.origin!.y + frame.h);
+    }
+  });
+
+  test('gap options spread the layout', ({ expect }) => {
+    const compact = objectsOf(compile(FLOWCHART));
+    const spread = objectsOf(compile(FLOWCHART, { gapMain: 200, gapCross: 120 }));
+
+    expect(origin(spread, 'A').y - origin(spread, 'X').y).toBeGreaterThan(
+      origin(compact, 'A').y - origin(compact, 'X').y,
+    );
+    expect(Math.abs(origin(spread, 'C').x - origin(spread, 'B').x)).toBeGreaterThan(
+      Math.abs(origin(compact, 'C').x - origin(compact, 'B').x),
+    );
+  });
+
+  test('LR flowcharts advance the main axis by node width', ({ expect }) => {
+    const objects = objectsOf(compile(['flowchart LR', 'A[A]', 'B[B]', 'A --> B'].join('\n')));
+
+    // Main-axis step = NODE_W (100) + gapMain (60); lanes share the cross axis.
+    expect(origin(objects, 'B').x - origin(objects, 'A').x).toBe(160);
+    expect(origin(objects, 'B').y).toBe(origin(objects, 'A').y);
+  });
+
+  test('ignores comments and tolerates unknown syntax', ({ expect }) => {
+    const graph = parse(['flowchart LR', '%% a comment', 'A[A]', 'A --> B', 'click A callback'].join('\n'));
+
+    expect(graph.direction).toBe('LR');
+    expect(graph.nodes.map((node) => node.id)).toEqual(['A', 'B']);
+    expect(graph.edges).toEqual([{ from: 'A', to: 'B', kind: 'reference' }]);
+  });
+});
+
+const origin = (objects: Scene.WorldObject[], id: string) => objects.find((object) => object.id === id)!.origin!;

package/src/mermaid.ts

@@ -0,0 +1,326 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Mermaid flowchart dialect: parses the subset needed for block diagrams (node declarations,
+// subgraphs, directed edges) and compiles it to scene commands with a layered layout. Mermaid
+// carries no coordinates, so the dialect owns placement — see `dialect.ts` for the contract.
+//
+
+import * as Layout from './layout.ts';
+import type * as Scene from './scene.ts';
+
+export type Direction = 'TB' | 'BT' | 'LR' | 'RL';
+
+export type MermaidNode = {
+  id: string;
+  label: string;
+  /** Enclosing subgraph id, when declared inside one. */
+  group?: string;
+  /** What the node depicts (DXN or URI), from a `%% ref <id> <target>` directive. */
+  ref?: string;
+};
+
+export type MermaidGroup = {
+  id: string;
+  label: string;
+  children: string[];
+};
+
+/** Relationship kind, from the edge token; drawn with the UML end markers in `markers`. */
+export type RelationKind = 'reference' | 'inheritance' | 'hasMany' | 'contains';
+
+export type MermaidEdge = {
+  from: string;
+  to: string;
+  kind: RelationKind;
+  label?: string;
+};
+
+/**
+ * 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.
+ */
+const EDGE_KINDS: Record<string, RelationKind> = {
+  '-->': 'reference',
+  '---': 'reference',
+  '-.->': 'reference',
+  '==>': 'reference',
+  '--|>': 'inheritance',
+  '--{': '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*$/;
+
+/**
+ * Rewrite the UML edge tokens into mermaid-legal labelled arrows, for rendering the source with
+ * mermaid.js itself (as a reference beside our layout). Lossy by design: mermaid flowcharts have no
+ * triangle or crow's foot, so the kind becomes the label unless the edge already has one; `%% ref`
+ * lines are already comments.
+ */
+export const toStandard = (source: string): string =>
+  source
+    .split('\n')
+    .map((line) => {
+      const match = UML_EDGE.exec(line);
+      return match ? `${match[1]} -->|${match[3] ?? UML_LABELS[match[2]]}| ${match[4]}` : line;
+    })
+    .join('\n');
+
+/** Scene arrow markers for a relationship kind. */
+export const markers = (kind: RelationKind): Pick<Scene.Arrow, 'head' | 'tail'> => {
+  switch (kind) {
+    case 'inheritance':
+      return { head: 'triangle' };
+    case 'hasMany':
+      return { head: 'crowsfoot' };
+    case 'contains':
+      return { tail: 'circle' };
+    default:
+      return {};
+  }
+};
+
+export type MermaidGraph = {
+  direction: Direction;
+  nodes: MermaidNode[];
+  groups: MermaidGroup[];
+  edges: MermaidEdge[];
+};
+
+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*)?(.+)$/;
+const SUBGRAPH = /^subgraph\s+([A-Za-z0-9_-]+)(?:\s*\[(.*?)\])?\s*$/;
+
+// `%% ref A packages/core/echo` — a comment to mermaid proper, so sources stay portable.
+const REF = /^%%\s*ref\s+([A-Za-z0-9_-]+)\s+(\S+)\s*$/;
+
+const unquote = (value: string) => value.trim().replace(/^"(.*)"$/, '$1');
+
+/** Parse a mermaid flowchart into a neutral graph. Unrecognised lines are ignored. */
+export const parse = (source: string): MermaidGraph => {
+  const nodes = new Map<string, MermaidNode>();
+  const groups: MermaidGroup[] = [];
+  const edges: MermaidEdge[] = [];
+  let direction: Direction = 'TB';
+  const stack: string[] = [];
+
+  const declare = (token: string): string | undefined => {
+    const match = NODE.exec(token.trim());
+    if (!match) {
+      return undefined;
+    }
+    const [, id, square, round, curly] = match;
+    const label = unquote(square ?? round ?? curly ?? id);
+    const group = stack[stack.length - 1];
+    const existing = nodes.get(id);
+    if (existing) {
+      // A later declaration with an explicit label wins; the first mention fixes the group.
+      if (square ?? round ?? curly) {
+        existing.label = label;
+      }
+      return id;
+    }
+    nodes.set(id, { id, label, ...(group ? { group } : {}) });
+    if (group) {
+      groups.find((entry) => entry.id === group)?.children.push(id);
+    }
+    return id;
+  };
+
+  const refs = new Map<string, string>();
+  for (const raw of source.split('\n')) {
+    const line = raw.trim();
+    const ref = REF.exec(line);
+    if (ref) {
+      refs.set(ref[1], ref[2]);
+      continue;
+    }
+    if (!line || line.startsWith('%%')) {
+      continue;
+    }
+
+    const header = /^(?:flowchart|graph)\s+([A-Za-z]{2})$/.exec(line);
+    if (header) {
+      const value = header[1].toUpperCase() as Direction;
+      direction = DIRECTIONS.includes(value) ? value : 'TB';
+      continue;
+    }
+
+    const subgraph = SUBGRAPH.exec(line);
+    if (subgraph) {
+      const [, id, label] = subgraph;
+      groups.push({ id, label: unquote(label ?? id), children: [] });
+      stack.push(id);
+      continue;
+    }
+
+    if (line === 'end') {
+      stack.pop();
+      continue;
+    }
+
+    const edge = EDGE.exec(line);
+    if (edge) {
+      const [, from, token, label, to] = edge;
+      const fromId = declare(from);
+      const toId = declare(to);
+      if (fromId && toId) {
+        edges.push({
+          from: fromId,
+          to: toId,
+          kind: EDGE_KINDS[token] ?? 'reference',
+          ...(label ? { label: unquote(label) } : {}),
+        });
+      }
+      continue;
+    }
+
+    declare(line);
+  }
+
+  // Directives may precede or follow the node they name.
+  return {
+    direction,
+    nodes: [...nodes.values()].map((node) => (refs.has(node.id) ? { ...node, ref: refs.get(node.id) } : node)),
+    groups,
+    edges,
+  };
+};
+
+/** Layout constants in scene units. */
+const NODE_W = 100;
+const NODE_H = 50;
+const GAP_MAIN = 60;
+const GAP_CROSS = 40;
+const GROUP_PAD = 24;
+
+/** Assign each node a rank one past its deepest forward predecessor. */
+const rank = (graph: MermaidGraph): Map<string, number> =>
+  Layout.rank(
+    graph.nodes.map((node) => node.id),
+    graph.edges,
+  );
+
+export type CompileOptions = {
+  /** Canvas position of the diagram's top-left, in canvas px. */
+  origin?: Scene.Point;
+  /** Canvas px per scene unit. */
+  scale?: number;
+  /** Gap between ranks along the flow direction, in scene units (default 60). */
+  gapMain?: number;
+  /** Gap between nodes within a rank, in scene units (default 40). */
+  gapCross?: number;
+};
+
+/**
+ * Compile a mermaid flowchart into scene commands: one world object per node (element `box`),
+ * one per subgraph frame, and an `edges` object holding the connectors as bound arrows.
+ */
+export const compile = (source: string, options: CompileOptions = {}): Scene.Command[] => {
+  const graph = parse(source);
+  const { origin = { x: 0, y: 0 }, scale = 1, gapMain = GAP_MAIN, gapCross = GAP_CROSS } = options;
+  const ranks = rank(graph);
+  const horizontal = graph.direction === 'LR' || graph.direction === 'RL';
+
+  // Group nodes by rank, preserving declaration order within each.
+  const lanes = new Map<number, MermaidNode[]>();
+  for (const node of graph.nodes) {
+    const value = ranks.get(node.id) ?? 0;
+    lanes.set(value, [...(lanes.get(value) ?? []), node]);
+  }
+  const widest = Math.max(...[...lanes.values()].map((lane) => lane.length), 1);
+
+  // Axis-specific node sizes: for LR/RL the main axis advances by width and lanes stack by height.
+  const mainSize = horizontal ? NODE_W : NODE_H;
+  const crossSize = horizontal ? NODE_H : NODE_W;
+  const positions = new Map<string, Scene.Point>();
+  for (const [lane, members] of lanes) {
+    const span = members.length * crossSize + (members.length - 1) * gapCross;
+    const offset = (widest * crossSize + (widest - 1) * gapCross - span) / 2;
+    members.forEach((node, index) => {
+      const cross = offset + index * (crossSize + gapCross);
+      const main = lane * (mainSize + gapMain);
+      positions.set(node.id, horizontal ? { x: main, y: cross } : { x: cross, y: main });
+    });
+  }
+
+  const commands: Scene.Command[] = [];
+
+  // Frames first so nodes paint above them.
+  for (const group of graph.groups) {
+    const members = group.children.map((id) => positions.get(id)).filter((point): point is Scene.Point => !!point);
+    if (members.length === 0) {
+      continue;
+    }
+    const minX = Math.min(...members.map((point) => point.x)) - GROUP_PAD;
+    const minY = Math.min(...members.map((point) => point.y)) - GROUP_PAD;
+    const maxX = Math.max(...members.map((point) => point.x)) + NODE_W + GROUP_PAD;
+    const maxY = Math.max(...members.map((point) => point.y)) + NODE_H + GROUP_PAD;
+    commands.push({
+      op: 'upsert-object',
+      object: {
+        id: group.id,
+        origin: { x: origin.x + minX * scale, y: origin.y + minY * scale },
+        scale,
+        elements: [
+          {
+            kind: 'rect',
+            id: 'frame',
+            x: 0,
+            y: 0,
+            w: maxX - minX,
+            h: maxY - minY,
+            stroke: 'dashed',
+            color: 'grey',
+            ...(group.label.trim() ? { text: group.label } : {}),
+          },
+        ],
+      },
+    });
+  }
+
+  for (const node of graph.nodes) {
+    const point = positions.get(node.id)!;
+    commands.push({
+      op: 'upsert-object',
+      object: {
+        id: node.id,
+        origin: { x: origin.x + point.x * scale, y: origin.y + point.y * scale },
+        scale,
+        ...(node.ref ? { ref: node.ref } : {}),
+        elements: [{ kind: 'rect', id: 'box', x: 0, y: 0, w: NODE_W, h: NODE_H, text: node.label }],
+      },
+    });
+  }
+
+  if (graph.edges.length > 0) {
+    commands.push({
+      op: 'upsert-object',
+      object: {
+        id: 'edges',
+        origin,
+        scale,
+        elements: graph.edges.map((edge) => ({
+          kind: 'arrow' as const,
+          id: `${edge.from}-${edge.to}`,
+          from: `${edge.from}/box`,
+          to: `${edge.to}/box`,
+          ...markers(edge.kind),
+          ...(edge.label ? { text: edge.label } : {}),
+        })),
+      },
+    });
+  }
+
+  return commands;
+};

package/src/objective.test.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { analyze } from './diagnostics.ts';
+import { DEFAULT, type Layout, evaluate, framesApart, select } from './objective.ts';
+import type * as Scene from './scene.ts';
+import { GRID } from './uml-grid.ts';
+
+const box = (id: string, x: number, y: number, w = 64, h = 64): Scene.WorldObject => ({
+  id,
+  origin: { x, y },
+  elements: [{ kind: 'rect', id: 'frame', x: 0, y: 0, w, h }],
+});
+
+const layoutOf = (objects: Scene.WorldObject[]): Layout => ({ objects, report: analyze(objects) });
+
+describe('objective', () => {
+  test('a clean layout has no violations and a cost from the soft terms only', ({ expect }) => {
+    const layout = layoutOf([
+      box('a', 0, 0),
+      box('b', 0, 200),
+      { id: 'edges', elements: [{ kind: 'arrow', id: 'a-b', start: { x: 32, y: 64 }, end: { x: 32, y: 200 } }] },
+    ]);
+    const evaluation = evaluate(DEFAULT, layout);
+
+    expect(evaluation.violations).toEqual([]);
+    expect(evaluation.terms.map(({ id }) => id)).toEqual([
+      'crossings',
+      'bends',
+      'connector-length',
+      'uneven-frame-gaps',
+      'compactness',
+    ]);
+    expect(evaluation.cost).toBeGreaterThan(0);
+  });
+
+  test('overlapping nodes violate the hard-defect constraint', ({ expect }) => {
+    const evaluation = evaluate(DEFAULT, layoutOf([box('a', 0, 0), box('b', 32, 32)]));
+
+    expect(evaluation.violations.map(({ constraint }) => constraint)).toEqual(['no-hard-defects']);
+  });
+
+  test('frames closer than the gap violate frames-apart; uneven gaps cost', ({ expect }) => {
+    // Three frames in a row, each enclosing a node so they count as containers.
+    const frames = (gap1: number, gap2: number) => {
+      const x1 = 0;
+      const x2 = x1 + 128 + gap1;
+      const x3 = x2 + 128 + gap2;
+      return layoutOf([
+        box('f1', x1, 0, 128, 128),
+        box('n1', x1 + 32, 32, 32, 32),
+        box('f2', x2, 0, 128, 128),
+        box('n2', x2 + 32, 32, 32, 32),
+        box('f3', x3, 0, 128, 128),
+        box('n3', x3 + 32, 32, 32, 32),
+      ]);
+    };
+
+    expect(framesApart(GRID).violations(frames(GRID / 2, GRID))).toHaveLength(1);
+    expect(framesApart(GRID).violations(frames(GRID, GRID))).toEqual([]);
+
+    const even = evaluate(DEFAULT, frames(GRID, GRID));
+    const uneven = evaluate(DEFAULT, frames(GRID, GRID * 3));
+    expect(even.terms.find(({ id }) => id === 'uneven-frame-gaps')?.value).toBe(0);
+    expect(uneven.terms.find(({ id }) => id === 'uneven-frame-gaps')?.value).toBe(2);
+    expect(uneven.cost).toBeGreaterThan(even.cost);
+  });
+
+  test('select prefers feasibility over cost, then lowest cost', ({ expect }) => {
+    const feasibleCostly = { name: 'feasible-costly', layout: layoutOf([box('a', 0, 0), box('b', 0, 2000)]) };
+    const feasibleTight = { name: 'feasible-tight', layout: layoutOf([box('a', 0, 0), box('b', 0, 200)]) };
+    const infeasible = { name: 'infeasible', layout: layoutOf([box('a', 0, 0), box('b', 16, 16)]) };
+
+    const { chosen, ranked } = select(DEFAULT, [infeasible, feasibleCostly, feasibleTight]);
+
+    expect(chosen.candidate.name).toBe('feasible-tight');
+    expect(ranked.map(({ candidate }) => candidate.name)).toEqual(['feasible-tight', 'feasible-costly', 'infeasible']);
+  });
+});