@dxos/diagram 0.11.1 → 0.14.0

package/src/dx-svg.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The `.dx.svg` container: an SVG that renders anywhere and carries the data it was drawn from, as
+// draw.io's editable SVG does. The payload (for the illustrator, a `.dx.json` with the drawing's ECHO
+// objects) is JSON text in a `<metadata id="dx-payload">` element: unlike an attribute or a comment,
+// `<metadata>` survives browsers, GitHub and DOMPurify. Format-only and ECHO-agnostic; the illustrator
+// builds and reads the payload.
+//
+
+/** The container format; versions the slot and encoding, not the payload, which versions itself. */
+export const FORMAT = 'org.dxos.dx-svg@1';
+
+const NAMESPACE = 'https://dxos.org/ns/dx-svg';
+
+const MEDIA_TYPE = 'application/vnd.dxos.dx+json';
+
+const NOTICE =
+  '<!-- Drawn in DXOS: the embedded data is the source; edits to the picture alone are not reflected in it. -->';
+
+/**
+ * JSON with `<`, `>` and `&` as unicode escapes, so the text needs neither CDATA nor entity decoding
+ * and `JSON.parse` restores it exactly. A top-level `objects` array goes one object per line, so a
+ * changed drawing diffs by object.
+ */
+const encode = (payload: unknown): string => {
+  const escape = (json: string) => json.replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    !Array.isArray(payload) &&
+    'objects' in payload &&
+    Array.isArray(payload.objects)
+  ) {
+    const { objects, ...rest } = payload;
+    const head = JSON.stringify(rest);
+    const body = objects.map((object: unknown) => escape(JSON.stringify(object))).join(',\n');
+    return `${escape(head.slice(0, -1))}${head.length > 2 ? ',' : ''}"objects":[\n${body}\n]}`;
+  }
+  return escape(JSON.stringify(payload));
+};
+
+/** Embeds a payload in a standalone SVG: a marker on the root and the payload as its first child. */
+export const embed = (svg: string, payload: unknown): string => {
+  const root = /<svg\b[^>]*>/.exec(svg);
+  if (!root) {
+    throw new Error('Not an SVG document: no <svg> element.');
+  }
+  if (/\bdx:payload=/.test(root[0])) {
+    throw new Error('The SVG already carries a dx-svg payload.');
+  }
+  const open = root[0].replace(/<svg\b/, `<svg xmlns:dx="${NAMESPACE}" dx:payload="${FORMAT}"`);
+  const metadata = `<metadata id="dx-payload" data-type="${MEDIA_TYPE}" data-version="1" data-encoding="json">\n${encode(payload)}\n</metadata>`;
+  return `${svg.slice(0, root.index)}${NOTICE}\n${open}${metadata}${svg.slice(root.index + root[0].length)}`;
+};
+
+/** Whether an SVG carries a payload, without parsing it. */
+export const isDxSvg = (svg: string): boolean => /<metadata\b[^>]*\bid="dx-payload"/.test(svg);
+
+/**
+ * The payload of a `.dx.svg`, or undefined for a plain SVG. Works on the text alone, so it runs in node,
+ * workers and the browser. An encoding this version does not know is an error, not a missing payload.
+ */
+export const extract = (svg: string): unknown => {
+  const match = /<metadata\b([^>]*)\bid="dx-payload"([^>]*)>([\s\S]*?)<\/metadata>/.exec(svg);
+  if (!match) {
+    return undefined;
+  }
+  const attributes = `${match[1]} ${match[2]}`;
+  const encoding = /\bdata-encoding="([^"]*)"/.exec(attributes)?.[1] ?? 'json';
+  if (encoding !== 'json') {
+    throw new Error(`Unsupported dx-svg payload encoding: ${encoding}.`);
+  }
+  return JSON.parse(match[3]);
+};

package/src/extension/complete.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type CompletionContext, type CompletionResult, autocompletion } from '@codemirror/autocomplete';
+import { syntaxTree } from '@codemirror/language';
+import { type Extension } from '@codemirror/state';
+import { type SyntaxNode } from '@lezer/common';
+
+import {
+  type AttrSpec,
+  DIAGRAM_ATTRS,
+  EDGE_ATTRS,
+  ELEMENT_ATTRS,
+  ELEMENT_KINDS,
+  type ElementKind,
+  GROUP_ATTRS,
+  NODE_ATTRS,
+  OBJECT_ATTRS,
+  RELATION_WORDS,
+  STATEMENT_KEYWORDS,
+} from '../dsl/vocabulary.ts';
+
+/** What a semantic statement accepts after its id: attributes, plus relations or edge clauses. */
+const SEMANTIC: Record<string, { attrs: readonly AttrSpec[]; words: readonly string[] }> = {
+  DiagramDecl: { attrs: DIAGRAM_ATTRS, words: [] },
+  GroupDecl: { attrs: GROUP_ATTRS, words: [...RELATION_WORDS, 'compact'] },
+  NodeDecl: { attrs: NODE_ATTRS, words: RELATION_WORDS },
+  EdgeDecl: { attrs: EDGE_ATTRS, words: ['via', 'bus'] },
+};
+
+const attributeOptions = (attrs: readonly AttrSpec[]) =>
+  attrs.map(({ name, type }) => ({
+    label: name,
+    type: 'property',
+    detail: type === 'enum' ? undefined : type,
+    apply: `${name}=`,
+  }));
+
+/** The element kind a completion is inside, read off the tree rather than re-lexing the line. */
+const enclosingKind = (context: CompletionContext, pos: number): ElementKind | undefined => {
+  let node = syntaxTree(context.state).resolveInner(pos, -1);
+  while (node.parent) {
+    if (node.name === 'Element') {
+      const shape = node.firstChild;
+      const keyword = shape && (shape.getChild('BoxKind') ?? shape.getChild('PathKind'))?.firstChild;
+      const word = context.state.doc.sliceString(
+        (keyword ?? shape?.firstChild)?.from ?? 0,
+        (keyword ?? shape?.firstChild)?.to ?? 0,
+      );
+      return ELEMENT_KINDS.find((kind) => kind === word);
+    }
+    if (node.name === 'ObjectDecl' || node.name === 'ElementsDecl') {
+      // Inside the declaration but outside any element: the object's own attributes.
+      return undefined;
+    }
+    node = node.parent;
+  }
+  return undefined;
+};
+
+/** Node names from the cursor out to the document, so a position is classified by where it sits. */
+const ancestorsOf = (context: CompletionContext, pos: number): string[] => {
+  const names: string[] = [];
+  for (let node: SyntaxNode | null = syntaxTree(context.state).resolveInner(pos, -1); node; node = node.parent) {
+    names.push(node.name);
+  }
+  return names;
+};
+
+const source = (context: CompletionContext): CompletionResult | null => {
+  const word = context.matchBefore(/[\w-]*/);
+  if (!word || (word.from === word.to && !context.explicit)) {
+    return null;
+  }
+
+  const ancestors = ancestorsOf(context, context.pos);
+  // Inside a semantic statement the innermost one decides; a group's body holds nodes and edges.
+  const innermost = ancestors.find((name) => name in SEMANTIC || name === 'GroupBody');
+  if (innermost === 'GroupBody') {
+    return { from: word.from, options: ['node', 'edge'].map((label) => ({ label, type: 'keyword' })) };
+  }
+  if (innermost) {
+    const { attrs, words } = SEMANTIC[innermost];
+    return {
+      from: word.from,
+      options: [...words.map((label) => ({ label, type: 'keyword' })), ...attributeOptions(attrs)],
+    };
+  }
+  // Outside any declaration only a statement can start.
+  if (!ancestors.includes('ObjectDecl') && !ancestors.includes('ElementsDecl')) {
+    return { from: word.from, options: STATEMENT_KEYWORDS.map((label) => ({ label, type: 'keyword' })) };
+  }
+
+  // A `Body` holds elements and nothing else, so an empty position in one wants a kind; inside an
+  // element it wants that kind's attributes, and in the header it wants the object's.
+  const kind = enclosingKind(context, context.pos);
+  if (!kind && ancestors.includes('Body')) {
+    return { from: word.from, options: ELEMENT_KINDS.map((label) => ({ label, type: 'keyword' })) };
+  }
+
+  return { from: word.from, options: attributeOptions(kind ? ELEMENT_ATTRS[kind] : OBJECT_ATTRS) };
+};
+
+export const diagramComplete: Extension = autocompletion({ override: [source] });

package/src/extension/extension.test.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { HighlightStyle } from '@codemirror/language';
+import { highlightTree } from '@lezer/highlight';
+import { vscodeDarkStyle, vscodeLightStyle } from '@uiw/codemirror-theme-vscode';
+import { describe, test } from 'vitest';
+
+import { printCommands } from '../dsl/print.ts';
+import { diagramHighlightStyle } from './highlight.ts';
+import { diagram } from './language.ts';
+import { diagramDiagnostics } from './lint.ts';
+import { diagramLanguage } from './syntax.ts';
+
+describe('diagram language', () => {
+  test('the mode composes without an editor', ({ expect }) => {
+    expect(diagram({ layout: true })).toBeDefined();
+    expect(diagramLanguage.name).toEqual('diagram');
+  });
+
+  test('highlighting comes off the tree, not a regex', ({ expect }) => {
+    const source = 'object A @ 0,0 {\n  rect box 0,0 10x10 "hi" color=red\n}\n';
+    const tree = diagramLanguage.parser.parse(source);
+    const names: string[] = [];
+    const cursor = tree.cursor();
+    do {
+      names.push(cursor.name);
+    } while (cursor.next());
+    expect(names).toContain('ObjectDecl');
+    expect(names).toContain('BoxElement');
+    expect(names).toContain('AttrName');
+    expect(names).not.toContain('⚠');
+  });
+
+  //
+  // The tags are standard so the theme colours most of a document, but `vscode*Style` defines
+  // neither `attributeValue` nor `null` — enum values and the unbound arrow end rendered plain
+  // until `diagramHighlightStyle` filled them. Asserting against the real theme is what catches
+  // the next tag added to `styleTags` with nothing to colour it.
+  //
+  for (const [mode, themeStyle] of [
+    ['light', vscodeLightStyle],
+    ['dark', vscodeDarkStyle],
+  ] as const) {
+    test(`every token is coloured under the ${mode} theme`, ({ expect }) => {
+      expect(uncoloured(SAMPLE, themeStyle)).toEqual([]);
+    });
+
+    test(`every semantic token is coloured under the ${mode} theme`, ({ expect }) => {
+      expect(uncoloured(SEMANTIC_SAMPLE, themeStyle)).toEqual([]);
+    });
+  }
+});
+
+/** Every element kind, both arrow forms, a quoted id, a comment — one of each tag the grammar emits. */
+const SAMPLE = `# comment
+object pkgA @ -24,-24 scale=1 index="a1" {
+  rect frame 0,0 248x172 "Package A" color=grey stroke=dashed
+  line path 0,0 10,10 closed=true
+  arc smile 50,50 20 0..180
+  arrow e1 A/box#left -> B/box "extends" head=triangle
+  arrow e2 10,20 -> _
+  portal "1st" 0,0 10x10 ref="dxn:echo:@:01"
+}
+`;
+
+/** The semantic statements, with soft sides, a compact group, an aspect ratio and a fan-in bus. */
+const SEMANTIC_SAMPLE = `diagram flow=down aspect=4:3
+group g "G" compact max-width=2 ~right-of h { node A  node B below A }
+group h { node C }
+edge A:~left|top, B -> C "joins" bus
+`;
+
+/** Non-whitespace runs that no highlighter claimed, as `offset:"text"`. */
+const uncoloured = (source: string, themeStyle: Parameters<typeof HighlightStyle.define>[0]): string[] => {
+  const covered = new Uint8Array(source.length);
+  for (const style of [HighlightStyle.define(themeStyle), diagramHighlightStyle()]) {
+    highlightTree(diagramLanguage.parser.parse(source), style, (from, to, classes) => {
+      if (classes) {
+        covered.fill(1, from, to);
+      }
+    });
+  }
+
+  const gaps: string[] = [];
+  let run = '';
+  let start = 0;
+  for (let index = 0; index <= source.length; index++) {
+    const bare = index < source.length && !covered[index] && !/\s/.test(source[index]);
+    if (bare) {
+      if (!run) {
+        start = index;
+      }
+      run += source[index];
+    } else if (run) {
+      gaps.push(`${start}:${JSON.stringify(run)}`);
+      run = '';
+    }
+  }
+  return gaps;
+};
+
+describe('diagram lint', () => {
+  test('a clean document reports nothing', ({ expect }) => {
+    expect(diagramDiagnostics('object A @ 0,0 {\n  rect box 0,0 10x10\n}\n', { layout: true })).toEqual([]);
+  });
+
+  test('parse problems carry a range inside the document', ({ expect }) => {
+    const source = 'object A @ 0,0 {\n  rect box 0,0 10x10 colour=red\n}\n';
+    const [diagnostic, ...rest] = diagramDiagnostics(source);
+    expect(rest).toEqual([]);
+    expect(diagnostic.message).toContain('colour');
+    expect(source.slice(diagnostic.from, diagnostic.to)).toEqual('colour=red');
+  });
+
+  test('a layout error points at the object that caused it, not the top of the file', ({ expect }) => {
+    // Two boxes on the same spot — `node-overlap`, which `Diagnostics` reports against both refs.
+    const source = printCommands([
+      { op: 'upsert-object', object: { id: 'A', origin: { x: 0, y: 0 }, elements: [box('a')] } },
+      { op: 'upsert-object', object: { id: 'B', origin: { x: 0, y: 0 }, elements: [box('b')] } },
+    ]);
+    const overlaps = diagramDiagnostics(source, { layout: true }).filter(({ source: code }) => code === 'node-overlap');
+    expect(overlaps.length).toBeGreaterThan(0);
+    expect(overlaps[0].from).toBeGreaterThan(0);
+    expect(source.slice(overlaps[0].from, overlaps[0].to)).toContain('rect');
+  });
+
+  test('layout is not analysed while the document has a syntax error', ({ expect }) => {
+    const diagnostics = diagramDiagnostics('object A @ 0,0 {\n  rect box 0,0\n}\n', { layout: true });
+    expect(diagnostics.every(({ source }) => source === undefined)).toBe(true);
+  });
+});
+
+const box = (id: string) => ({ kind: 'rect', id, x: 0, y: 0, w: 100, h: 50 }) as const;

package/src/extension/highlight.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { HighlightStyle } from '@codemirror/language';
+import { tags } from '@lezer/highlight';
+
+/**
+ * Fills the gaps the editor's own highlight style leaves. The grammar emits standard
+ * `@lezer/highlight` tags, so most of a document is coloured by whatever style the theme installs
+ * and inherits its palette — but `vscodeLightStyle`/`vscodeDarkStyle` define neither
+ * `attributeValue` nor `null`, which in this language are the enum values (`grey`, `dashed`,
+ * `triangle`) and the unbound arrow end. Those are the most scannable part of a diagram, so
+ * leaving them uncoloured is the one thing worth overriding.
+ *
+ * Classes are semantic theme tokens rather than hues, as in `mermaidHighlightStyle`, so light and
+ * dark follow the palette.
+ */
+export const diagramHighlightStyle = () =>
+  HighlightStyle.define([
+    { tag: tags.attributeValue, class: 'text-accent' },
+    { tag: tags.null, class: 'text-fg-subtle' },
+  ]);

package/src/extension/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { diagram, diagramBlockDescription } from './language.ts';
+export { type LintOptions, diagramDiagnostics, diagramLint } from './lint.ts';
+export { diagramComplete } from './complete.ts';
+export { diagramHighlightStyle } from './highlight.ts';
+export { diagramLanguage } from './syntax.ts';

package/src/extension/language.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { LanguageDescription, LanguageSupport, syntaxHighlighting } from '@codemirror/language';
+import { type Extension } from '@codemirror/state';
+
+import { diagramComplete } from './complete.ts';
+import { diagramHighlightStyle } from './highlight.ts';
+import { type LintOptions, diagramLint } from './lint.ts';
+import { diagramLanguage } from './syntax.ts';
+
+/**
+ * The fence dispatch point. Pass this alongside deus's `mdlBlockDescription` in
+ * `createMarkdownExtensions({ codeLanguages: [...] })` and a ```diagram block inside a `.mdl`
+ * document parses with the diagram grammar — a sibling of MDL's, not a nesting inside it. See
+ * `docs/DSL.md`.
+ */
+export const diagramBlockDescription = LanguageDescription.of({
+  name: 'diagram',
+  alias: ['dxd'],
+  support: new LanguageSupport(diagramLanguage),
+});
+
+/** The whole editing surface for a standalone DSL buffer: mode, highlighting, completion, lint. */
+export const diagram = (options: LintOptions = {}): Extension => [
+  new LanguageSupport(diagramLanguage),
+  syntaxHighlighting(diagramHighlightStyle()),
+  diagramComplete,
+  diagramLint(options),
+];

package/src/extension/lint.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Diagnostic, linter } from '@codemirror/lint';
+import { type Extension } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+
+import * as Diagnostics from '../diagnostics.ts';
+import { parse, read, toScene } from '../dsl/parse.ts';
+
+export type LintOptions = {
+  /**
+   * Also report the layout diagnostics — overlaps, a connector through a node, a label that does
+   * not fit. Off by default because a document being typed is briefly nonsense; the bench and the
+   * agent loop both want it on.
+   */
+  layout?: boolean;
+};
+
+/**
+ * What is wrong with a document: everything `parse` found, and optionally everything
+ * `Diagnostics.analyze` finds in the scene it produced, each carrying the range of the statement
+ * or element that produced it — a layout error is only actionable when it points at the box it is
+ * about. Separate from the CodeMirror wrapper so it needs no editor, which is also how the
+ * agent-facing path reports the same problems.
+ */
+export const diagramDiagnostics = (text: string, { layout = false }: LintOptions = {}): Diagnostic[] => {
+  // Laying out semantic statements is a search; without the layout report only the reading is needed.
+  const { commands, problems, ranges } = layout ? parse(text) : read(text);
+  const clamp = (value: number) => Math.max(0, Math.min(value, text.length));
+
+  const diagnostics: Diagnostic[] = problems.map(({ severity, message, from, to }) => ({
+    severity,
+    message,
+    from: clamp(from),
+    to: clamp(to),
+  }));
+
+  // A document with a syntax error has a scene that is missing pieces, so its layout report would
+  // be noise on top of an error the author is already fixing.
+  if (layout && !problems.some(({ severity }) => severity === 'error')) {
+    for (const diagnostic of Diagnostics.analyze(toScene(commands).objects).diagnostics) {
+      const range = diagnostic.refs.flatMap((ref) => ranges.get(ref) ?? []).at(0);
+      diagnostics.push({
+        severity: diagnostic.severity,
+        source: diagnostic.code,
+        message: diagnostic.message,
+        from: clamp(range?.from ?? 0),
+        to: clamp(range?.to ?? Math.min(1, text.length)),
+      });
+    }
+  }
+
+  return diagnostics.sort((left, right) => left.from - right.from);
+};
+
+/** The CodeMirror linter over {@link diagramDiagnostics}. */
+export const diagramLint = (options: LintOptions = {}): Extension =>
+  linter((view: EditorView): Diagnostic[] => diagramDiagnostics(view.state.doc.toString(), options));

package/src/extension/syntax.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { LRLanguage } from '@codemirror/language';
+import { styleTags, tags } from '@lezer/highlight';
+
+import { parser } from '../dsl/gen/diagram.ts';
+
+//
+// Unlike deus's MDL mode — which keeps highlighting on a regex ViewPlugin so prose inside a block
+// cannot trip LR error recovery — the diagram grammar covers its whole input, so highlighting comes
+// off the tree. The tags are the standard ones, so most of a document inherits the editor's own
+// palette; `highlight.ts` covers only the two the theme leaves undefined.
+//
+
+export const diagramLanguage = LRLanguage.define({
+  name: 'diagram',
+  parser: parser.configure({
+    props: [
+      styleTags({
+        'object elements move remove diagram group node edge': tags.definitionKeyword,
+        'cell via bus compact': tags.keyword,
+        // Relation words and sides are plain names the reader checks, so they are tagged by position.
+        'RelationKind Side': tags.keyword,
+        'Soft': tags.modifier,
+        'rect ellipse diamond triangle circle line curve arc text arrow portal': tags.keyword,
+        // A quoted id is still an id, not a string.
+        'Id/String': tags.variableName,
+        'Id': tags.variableName,
+        'Ref': tags.propertyName,
+        'Label': tags.string,
+        'String': tags.string,
+        'Number': tags.number,
+        'Size': tags.number,
+        'Ratio': tags.number,
+        'AttrName': tags.attributeName,
+        // On the leaf, not on `AttrValue`/`Unbound`: a named child with no tag of its own does not
+        // inherit its parent's, so tagging the wrapper colours nothing. A numeric or quoted value
+        // keeps its own number/string tag; this is the bare enum word (`grey`, `dashed`).
+        'Word': tags.attributeValue,
+        // `head=triangle`, `head=arrow`, `tail=circle`: schema literals that are also element-kind
+        // keywords, so without the path they would colour as keywords while every other enum value
+        // colours as a value. Listed in full, like the grammar's own `Word` alternation, so a
+        // literal that starts colliding later is already covered.
+        'Word/object Word/elements Word/move Word/remove Word/rect Word/ellipse Word/diamond Word/triangle Word/circle Word/line Word/curve Word/arc Word/text Word/arrow Word/portal Word/diagram Word/group Word/node Word/edge Word/cell Word/via Word/bus Word/compact':
+          tags.attributeValue,
+        '_': tags.null,
+        'Comment': tags.lineComment,
+        '-> <-> -- @ .. : | ~': tags.operator,
+        '( )': tags.paren,
+        '=': tags.definitionOperator,
+        ',': tags.separator,
+        '{ }': tags.brace,
+      }),
+    ],
+  }),
+  languageData: {
+    commentTokens: { line: '#' },
+    closeBrackets: { brackets: ['{', '"'] },
+  },
+});

package/src/index.ts

@@ -4,12 +4,25 @@
 
 export * from './content.ts';
 export * from './dialect.ts';
+export * as Aesthetics from './aesthetics.ts';
+export * as Appeal from './appeal.ts';
+export * as Architecture from './architecture.ts';
 export * as Diagnostics from './diagnostics.ts';
+export * as Dsl from './dsl/index.ts';
+export * as DxSvg from './dx-svg.ts';
 export * as Layout from './layout.ts';
 export * as Mermaid from './mermaid.ts';
 export * as MermaidEngine from './mermaid-engine.ts';
+export * as Nudge from './nudge.ts';
 export * as Objective from './objective.ts';
+export * as Ports from './ports.ts';
+export * as Rules from './rules.ts';
 export * as Scene from './scene.ts';
+export * as Semantic from './semantic.ts';
+export * as SemanticEngine from './semantic-engine.ts';
+export * as SemanticPlace from './semantic-place.ts';
+export * as SemanticRoute from './semantic-route.ts';
+export * as Score from './score.ts';
 export * from './svg-handler.ts';
 export * as Ui from './ui.ts';
 export * as Uml from './uml.ts';
@@ -17,3 +30,4 @@ export * as UmlEngine from './uml-engine.ts';
 export * as UmlGrid from './uml-grid.ts';
 export * as UmlRules from './uml-rules.ts';
 export * as UmlSearch from './uml-search.ts';
+export * as View from './view.ts';

package/src/mermaid-engine.test.ts

@@ -119,7 +119,7 @@ describe('mermaid-engine', { timeout: 120_000 }, () => {
     expect(edges.filter(({ id }) => /-stub-\d$/.test(id))).toHaveLength(2);
     const labelled = edges.filter((element) => element.kind === 'text' && element.text === 'via mixin');
     expect(labelled).toHaveLength(1);
-    expect(edges.filter((element) => element.kind === 'arrow' && element.head === 'triangle')).toHaveLength(2);
+    expect(edges.filter((element) => element.kind === 'arrow' && element.relation === 'inheritance')).toHaveLength(2);
   });
 
   test('toStandard rewrites the UML tokens into mermaid-legal labelled arrows', ({ expect }) => {
@@ -181,10 +181,10 @@ describe('mermaid-engine', { timeout: 120_000 }, () => {
       .elements.flatMap((element) => (element.kind === 'arrow' ? [element] : []));
     const byId = (prefix: string) => arrows.find(({ id }) => id.startsWith(prefix))!;
 
-    expect(byId('B-A')).toMatchObject({ head: 'triangle' });
-    expect(byId('X-Y')).toMatchObject({ head: 'crowsfoot' });
-    expect(byId('P-Q')).toMatchObject({ tail: 'circle' });
-    expect(byId('R-S').head).toBeUndefined();
+    expect(byId('B-A')).toMatchObject({ relation: 'inheritance' });
+    expect(byId('X-Y')).toMatchObject({ relation: 'one-to-many' });
+    expect(byId('P-Q')).toMatchObject({ relation: 'aggregation' });
+    expect(byId('R-S').relation).toBeUndefined();
   });
 
   test('basic: no hard defects, every connector straight or one bend', async ({ expect }) => {
@@ -204,7 +204,7 @@ describe('mermaid-engine', { timeout: 120_000 }, () => {
     const edges = objects.find(({ id }) => id === 'edges')!.elements;
     expect(edges.find(({ id }) => id === 'A-bus')?.kind).toBe('line');
     expect(edges.filter(({ id }) => id.endsWith('-stub-0') || id.endsWith('-stub-1'))).toHaveLength(2);
-    expect(edges.filter((element) => element.kind === 'arrow' && element.head === 'triangle')).toHaveLength(1);
+    expect(edges.filter((element) => element.kind === 'arrow' && element.relation === 'inheritance')).toHaveLength(1);
     // Nothing else needs a second bend, and the three frames sit at equal gaps.
     expect(report.metrics.frameGapSpread).toBe(0);