@dxos/diagram 0.11.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dxos/diagram",
+  "version": "0.11.1",
+  "description": "Renderer-neutral scene DSL, diagram dialects, and layout engines.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing.ts",
+      "types": "./dist/types/src/testing.d.ts",
+      "import": "./dist/lib/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@dagrejs/dagre": "^3.1.1",
+    "elkjs": "^0.12.0",
+    "@dxos/invariant": "0.11.1",
+    "@dxos/util": "0.11.1"
+  },
+  "devDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__snapshots__/diagnostics.test.ts.snap

@@ -0,0 +1,36 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`layout quality (dagre) > soft metrics 1`] = `
+{
+  "bends": 2,
+  "crossings": 0,
+}
+`;
+
+exports[`layout quality (elk) > soft metrics 1`] = `
+{
+  "bends": 3,
+  "crossings": 0,
+}
+`;
+
+exports[`layout quality (grid) > soft metrics 1`] = `
+{
+  "bends": 3,
+  "crossings": 0,
+}
+`;
+
+exports[`layout quality (rules) > soft metrics 1`] = `
+{
+  "bends": 6,
+  "crossings": 0,
+}
+`;
+
+exports[`layout quality (search) > soft metrics 1`] = `
+{
+  "bends": 2,
+  "crossings": 0,
+}
+`;

package/src/__snapshots__/mermaid-engine.test.ts.snap

@@ -0,0 +1,22 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`mermaid-engine > basic: no hard defects, every connector straight or one bend 1`] = `
+{
+  "arrangement": "columns",
+  "cost": 4.96,
+}
+`;
+
+exports[`mermaid-engine > basic: no hard defects, every connector straight or one bend 2`] = `
+{
+  "bends": 1,
+  "crossings": 0,
+}
+`;
+
+exports[`mermaid-engine > has no hard defects and records its soft metrics 1`] = `
+{
+  "bends": 3,
+  "crossings": 0,
+}
+`;

package/src/content.ts

@@ -0,0 +1,180 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Renderer-neutral command application over a canvas content map. Every renderer stores its
+// canvas as `Record<recordId, record>` and stamps DSL identity onto each managed record, so the
+// upsert/remove/move bookkeeping is identical; only the encoding differs. Renderers supply that
+// encoding via `ContentHandler` and inherit the command semantics.
+//
+
+import { invariant } from '@dxos/invariant';
+
+import type * as Scene from './scene.ts';
+
+/** Opaque map of record id → renderer record. */
+export type ContentMap = Record<string, any>;
+
+/** DSL identity stamped onto a managed record. */
+export type Identity = {
+  object: string;
+  element: string;
+  /** Set on companion records that belong to an element rather than being one (e.g. arrow labels). */
+  part?: string;
+};
+
+/** Where an object sits on the canvas: `canvas = origin + local * scale`. */
+export type Placement = {
+  origin: Scene.Point;
+  scale: number;
+};
+
+/** An object as accepted by the renderer's compiler; `upsert-elements` supplies only a subset. */
+export type ObjectInput = Scene.WorldObject | { id: string; elements: readonly Scene.Element[] };
+
+/** A world object as derived from the canvas: placement is always resolved. */
+export type ReadWorldObject = Scene.WorldObject & Placement;
+
+export type ReadResult = {
+  scene: { objects: ReadWorldObject[] };
+  /** Records on the canvas not managed by the DSL (drawn by hand). */
+  unmanaged: number;
+};
+
+export type ApplyResult = {
+  /** Object ids created or modified. */
+  upserted: string[];
+  /** Records removed. */
+  removed: number;
+};
+
+/**
+ * The renderer-specific half of command application: how records carry identity, how objects
+ * compile to records, and any bookkeeping the renderer's store requires.
+ */
+export type ContentHandler = {
+  /** DSL identity for a record, or undefined when the record isn't managed by the DSL. */
+  identify: (record: any) => Identity | undefined;
+  /** Compile an object's elements into records keyed by record id. */
+  render: (object: ObjectInput, placement: Placement, content: ContentMap) => ContentMap;
+  /** Derive the scene from the content map. */
+  read: (content: ContentMap) => ReadResult;
+  /** Translate an object move into a per-record mutation. */
+  translate: (record: any, delta: Scene.Point) => void;
+  /** Create any scaffolding the renderer needs before its first record (e.g. a page). */
+  scaffold?: (content: ContentMap) => void;
+  /** Merge compiled records into the content map; defaults to a plain assign. */
+  merge?: (content: ContentMap, records: ContentMap) => void;
+  /** Clean up after deletions (e.g. drop bindings left dangling). */
+  prune?: (content: ContentMap) => void;
+};
+
+/** Apply a batch of edit commands to the canvas content (mutates `content`). */
+export const applyCommands = (
+  content: ContentMap,
+  commands: readonly Scene.Command[],
+  handler: ContentHandler,
+): ApplyResult => {
+  handler.scaffold?.(content);
+  const upserted = new Set<string>();
+  let removed = 0;
+
+  const find = (objectId: string) => handler.read(content).scene.objects.find((object) => object.id === objectId);
+
+  const merge = (object: ObjectInput, placement: Placement) => {
+    const records = handler.render(object, placement, content);
+    if (handler.merge) {
+      handler.merge(content, records);
+    } else {
+      Object.assign(content, records);
+    }
+  };
+
+  // Companion records (labels) are deleted alongside their element but aren't themselves
+  // elements, so they don't count toward the reported total.
+  const remove = (predicate: (identity: Identity) => boolean): number => {
+    let count = 0;
+    for (const [key, record] of Object.entries(content)) {
+      const identity = handler.identify(record);
+      if (identity && predicate(identity)) {
+        // Read before delete: ECHO proxies dereference lazily, so fields vanish once removed.
+        const isPart = identity.part !== undefined;
+        delete content[key];
+        if (!isPart) {
+          count++;
+        }
+      }
+    }
+    handler.prune?.(content);
+    return count;
+  };
+
+  for (const command of commands) {
+    switch (command.op) {
+      case 'upsert-object': {
+        const previous = find(command.object.id);
+        removed += remove((identity) => identity.object === command.object.id);
+        merge(command.object, {
+          origin: command.object.origin ?? previous?.origin ?? { x: 0, y: 0 },
+          scale: command.object.scale ?? previous?.scale ?? 1,
+        });
+        upserted.add(command.object.id);
+        break;
+      }
+
+      case 'upsert-elements': {
+        const previous = find(command.objectId);
+        invariant(previous, `unknown object: ${command.objectId} (use upsert-object to create it)`);
+        const ids = new Set(command.elements.map((element) => element.id));
+        removed += remove((identity) => identity.object === command.objectId && ids.has(identity.element));
+        merge({ id: command.objectId, elements: command.elements }, previous);
+        upserted.add(command.objectId);
+        break;
+      }
+
+      case 'remove-elements': {
+        const ids = new Set(command.elementIds);
+        removed += remove((identity) => identity.object === command.objectId && ids.has(identity.element));
+        break;
+      }
+
+      case 'remove-object': {
+        removed += remove((identity) => identity.object === command.objectId);
+        break;
+      }
+
+      case 'move-object': {
+        const previous = find(command.objectId);
+        invariant(previous, `unknown object: ${command.objectId}`);
+        const delta = { x: command.origin.x - previous.origin.x, y: command.origin.y - previous.origin.y };
+        for (const record of Object.values(content)) {
+          if (handler.identify(record)?.object === command.objectId) {
+            handler.translate(record, delta);
+          }
+        }
+        upserted.add(command.objectId);
+        break;
+      }
+    }
+  }
+
+  return { upserted: [...upserted], removed };
+};
+
+/** Seed a fractional-index counter past any existing `a<n>` indexes. */
+export const nextIndex = (content: ContentMap, isCounted: (record: any) => boolean = () => true): number => {
+  let max = 0;
+  let count = 0;
+  for (const record of Object.values(content)) {
+    if (!record || !isCounted(record)) {
+      continue;
+    }
+    count++;
+    const match = /^a(\d+)$/.exec(record.index ?? '');
+    if (match) {
+      max = Math.max(max, Number(match[1]));
+    }
+  }
+  return Math.max(max, count);
+};

package/src/diagnostics.test.ts

@@ -0,0 +1,173 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { analyze, errors } from './diagnostics.ts';
+import type * as Scene from './scene.ts';
+import { CLASS_DIAGRAM } from './testing.ts';
+import * as UmlEngine from './uml-engine.ts';
+import * as UmlGrid from './uml-grid.ts';
+import * as UmlRules from './uml-rules.ts';
+import * as UmlSearch from './uml-search.ts';
+
+const objectsOf = (commands: readonly Scene.Command[]) =>
+  commands.flatMap((command) => (command.op === 'upsert-object' ? [command.object] : []));
+
+const box = (id: string, x: number, y: number, w = 64, h = 64, text?: string): Scene.WorldObject => ({
+  id,
+  origin: { x, y },
+  elements: [{ kind: 'rect', id: 'frame', x: 0, y: 0, w, h, text }],
+});
+
+const arrow = (id: string, start: Scene.Point, end: Scene.Point): Scene.Element => ({ kind: 'arrow', id, start, end });
+
+describe('diagnostics', () => {
+  test('a clean scene reports nothing', ({ expect }) => {
+    const report = analyze([
+      box('a', 0, 0),
+      box('b', 0, 200),
+      { id: 'edges', elements: [arrow('a-b', { x: 32, y: 64 }, { x: 32, y: 200 })] },
+    ]);
+
+    expect(report.diagnostics).toEqual([]);
+    expect(report.metrics).toMatchObject({ nodes: 2, connectors: 1, crossings: 0, bends: 0 });
+  });
+
+  test('detects partially overlapping nodes, but not containment', ({ expect }) => {
+    const overlapping = analyze([box('a', 0, 0), box('b', 32, 32)]);
+    expect(overlapping.diagnostics.map(({ code }) => code)).toEqual(['node-overlap']);
+
+    // Exactly stacked nodes are the strongest overlap, not a container and its member.
+    const stacked = analyze([box('a', 0, 0), box('b', 0, 0)]);
+    expect(stacked.diagnostics.map(({ code }) => code)).toEqual(['node-overlap']);
+
+    // A subgraph frame enclosing its members is a container, not a collision.
+    const contained = analyze([box('frame', 0, 0, 400, 400), box('a', 32, 32)]);
+    expect(contained.diagnostics).toEqual([]);
+  });
+
+  test('detects a connector drawn across a node it does not terminate at', ({ expect }) => {
+    const report = analyze([
+      box('a', 0, 0),
+      box('blocker', 0, 128),
+      box('b', 0, 320),
+      { id: 'edges', elements: [arrow('a-b', { x: 32, y: 64 }, { x: 32, y: 320 })] },
+    ]);
+
+    expect(report.diagnostics.map(({ code }) => code)).toEqual(['route-through-node']);
+    expect(report.diagnostics[0].refs).toEqual(['edges/a-b', 'blocker/frame']);
+  });
+
+  test('a connector ending on a border is not a crossing', ({ expect }) => {
+    const report = analyze([
+      box('a', 0, 0),
+      box('b', 0, 200),
+      { id: 'edges', elements: [arrow('a-b', { x: 32, y: 64 }, { x: 32, y: 200 })] },
+    ]);
+
+    expect(report.metrics.routesThroughNodes).toBe(0);
+  });
+
+  test('detects a label that cannot fit its shape', ({ expect }) => {
+    const report = analyze([box('a', 0, 0, 64, 32, 'A very long label that will never fit')]);
+
+    expect(report.diagnostics.map(({ code }) => code)).toEqual(['label-overflow']);
+  });
+
+  test('counts proper crossings between distinct connectors, ignoring shared ports', ({ expect }) => {
+    const crossing = analyze([
+      {
+        id: 'edges',
+        elements: [arrow('h', { x: 0, y: 50 }, { x: 100, y: 50 }), arrow('v', { x: 50, y: 0 }, { x: 50, y: 100 })],
+      },
+    ]);
+    expect(crossing.metrics.crossings).toBe(1);
+    expect(crossing.diagnostics[0].severity).toBe('warning');
+
+    const fanIn = analyze([
+      {
+        id: 'edges',
+        elements: [arrow('a', { x: 0, y: 0 }, { x: 50, y: 50 }), arrow('b', { x: 100, y: 0 }, { x: 50, y: 50 })],
+      },
+    ]);
+    expect(fanIn.metrics.crossings).toBe(0);
+  });
+
+  test('rejoins a routed path with its arrow head and counts its bends', ({ expect }) => {
+    const report = analyze([
+      {
+        id: 'edges',
+        elements: [
+          {
+            kind: 'line',
+            id: 'a-b-path',
+            points: [
+              { x: 0, y: 0 },
+              { x: 0, y: 50 },
+              { x: 100, y: 50 },
+            ],
+          },
+          arrow('a-b', { x: 100, y: 50 }, { x: 100, y: 100 }),
+        ],
+      },
+    ]);
+
+    expect(report.metrics.connectors).toBe(1);
+    expect(report.metrics.bends).toBe(2);
+    expect(analyze(objectsOf([]), { maxBends: 1 }).diagnostics).toEqual([]);
+    expect(
+      analyze(
+        [
+          {
+            id: 'edges',
+            elements: [
+              {
+                kind: 'line',
+                id: 'z-path',
+                points: [
+                  { x: 0, y: 0 },
+                  { x: 0, y: 10 },
+                  { x: 10, y: 10 },
+                  { x: 10, y: 20 },
+                ],
+              },
+              arrow('z', { x: 10, y: 20 }, { x: 20, y: 20 }),
+            ],
+          },
+        ],
+        { maxBends: 2 },
+      ).diagnostics.map(({ code }) => code),
+    ).toEqual(['excessive-bends']);
+  });
+});
+
+//
+// Tier 1: every placement strategy must produce a scene free of hard defects for the shared
+// fixture. Soft metrics are recorded in the snapshot so a layout change reads as a diff.
+//
+
+const strategies: Record<string, (source: string) => Promise<readonly Scene.Command[]>> = {
+  grid: async (source) => UmlGrid.compile(source),
+  dagre: (source) => UmlEngine.compile(source, { engine: 'dagre' }),
+  elk: (source) => UmlEngine.compile(source, { engine: 'elk' }),
+  rules: async (source) => UmlRules.compile(source),
+  search: async (source) => UmlSearch.compile(source),
+};
+
+describe.each(Object.entries(strategies))('layout quality (%s)', (_name, compile) => {
+  test('the class-diagram fixture has no hard defects', async ({ expect }) => {
+    const report = analyze(objectsOf(await compile(CLASS_DIAGRAM)));
+
+    expect(errors(report).map(({ message }) => message)).toEqual([]);
+    expect(report.metrics.nodes).toBeGreaterThan(0);
+    expect(report.metrics.connectors).toBe(5);
+  });
+
+  test('soft metrics', async ({ expect }) => {
+    const { crossings, bends } = analyze(objectsOf(await compile(CLASS_DIAGRAM))).metrics;
+
+    expect({ crossings, bends }).toMatchSnapshot();
+  });
+});