@dxos/diagram 0.11.1 → 0.13.0

package/src/dsl/print.ts

@@ -0,0 +1,198 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Canonical text for a scene. The form is fixed — two-space indent, one element per line, a blank
+// line between statements, attributes in the order `vocabulary.ts` lists them — because
+// `parse(print(x))` round-tripping is only worth anything if the text side is normalized too.
+//
+
+import type * as Scene from '../scene.ts';
+import { BARE_ID, BARE_REF, ELEMENT_ATTRS, OBJECT_ATTRS, RESERVED } from './vocabulary.ts';
+
+const ESCAPES: Record<string, string> = { '\\': '\\\\', '"': '\\"', '\n': '\\n', '\t': '\\t', '\r': '\\r' };
+
+/**
+ * Shortest form that reads back: integers keep no trailing zeros, negatives keep their sign, and
+ * the exponent notation `String` switches to outside ~1e-7..1e21 is spelled as-is, which the
+ * grammar accepts. `NaN` and `Infinity` have no readable form at all, so they are refused here
+ * rather than silently producing a document that cannot be parsed.
+ */
+export const formatNumber = (value: number): string => {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`A scene coordinate must be finite; got ${value}.`);
+  }
+  return String(value);
+};
+
+export const formatString = (value: string): string =>
+  `"${value.replace(/[\\"\n\t\r]/g, (character) => ESCAPES[character] ?? character)}"`;
+
+/** Bare where the grammar allows it, quoted where a word would be read as a keyword or fail to lex. */
+export const formatId = (id: string): string => (BARE_ID.test(id) && !RESERVED.has(id) ? id : formatString(id));
+
+const formatPoint = ({ x, y }: Scene.Point): string => `${formatNumber(x)},${formatNumber(y)}`;
+
+const formatSize = (w: number, h: number): string => `${formatNumber(w)}x${formatNumber(h)}`;
+
+/**
+ * Quoted unless every id in it is a bare word: a dialect may build a ref from a node id the
+ * grammar cannot lex, such as mermaid's `1st` becoming `1st/box`, and an unquoted one would make
+ * the printed scene fail to parse.
+ */
+const formatRef = (ref: string): string => (BARE_REF.test(ref) && !RESERVED.has(ref) ? ref : formatString(ref));
+
+/** `_` is the end the schema leaves unset; a bound end prints as its ref, a free one as a point. */
+const formatEndpoint = (ref: string | undefined, point: Scene.Point | undefined): string =>
+  ref !== undefined ? formatRef(ref) : point !== undefined ? formatPoint(point) : '_';
+
+type AttrValue = string | number | boolean;
+
+/** Prints `name=value` for the attributes of `kind` that are set, in the table's order. */
+const formatAttrs = (kind: keyof typeof ELEMENT_ATTRS, values: Partial<Record<string, AttrValue>>): string[] =>
+  ELEMENT_ATTRS[kind].flatMap(({ name, type }) => {
+    const value = values[name];
+    if (value === undefined) {
+      return [];
+    }
+    return [`${name}=${type === 'string' && typeof value === 'string' ? formatString(value) : String(value)}`];
+  });
+
+const style = ({ color, fill, stroke, weight }: Scene.Element): Partial<Record<string, AttrValue>> => ({
+  color,
+  fill,
+  stroke,
+  weight,
+});
+
+export const formatElement = (element: Scene.Element): string => {
+  switch (element.kind) {
+    case 'rect':
+    case 'ellipse':
+    case 'diamond':
+    case 'triangle':
+      return [
+        element.kind,
+        formatId(element.id),
+        formatPoint(element),
+        formatSize(element.w, element.h),
+        ...(element.text === undefined ? [] : [formatString(element.text)]),
+        ...formatAttrs(element.kind, { rotation: element.rotation, corners: element.corners, ...style(element) }),
+      ].join(' ');
+
+    case 'circle':
+      return [
+        'circle',
+        formatId(element.id),
+        formatPoint({ x: element.cx, y: element.cy }),
+        formatNumber(element.r),
+        ...(element.text === undefined ? [] : [formatString(element.text)]),
+        ...formatAttrs('circle', style(element)),
+      ].join(' ');
+
+    case 'line':
+      return [
+        'line',
+        formatId(element.id),
+        ...element.points.map(formatPoint),
+        ...formatAttrs('line', { closed: element.closed, ...style(element) }),
+      ].join(' ');
+
+    case 'curve':
+      return [
+        'curve',
+        formatId(element.id),
+        ...element.points.map(formatPoint),
+        ...formatAttrs('curve', style(element)),
+      ].join(' ');
+
+    case 'arc':
+      return [
+        'arc',
+        formatId(element.id),
+        formatPoint({ x: element.cx, y: element.cy }),
+        formatNumber(element.r),
+        `${formatNumber(element.startAngle)}..${formatNumber(element.endAngle)}`,
+        ...formatAttrs('arc', style(element)),
+      ].join(' ');
+
+    case 'text':
+      return [
+        'text',
+        formatId(element.id),
+        formatPoint(element),
+        formatString(element.text),
+        ...formatAttrs('text', { w: element.w, ...style(element) }),
+      ].join(' ');
+
+    case 'arrow':
+      return [
+        'arrow',
+        formatId(element.id),
+        formatEndpoint(element.from, element.start),
+        '->',
+        formatEndpoint(element.to, element.end),
+        ...(element.text === undefined ? [] : [formatString(element.text)]),
+        ...formatAttrs('arrow', {
+          head: element.head,
+          tail: element.tail,
+          relation: element.relation,
+          ...style(element),
+        }),
+      ].join(' ');
+
+    case 'portal':
+      return [
+        'portal',
+        formatId(element.id),
+        formatPoint(element),
+        formatSize(element.w, element.h),
+        ...(element.text === undefined ? [] : [formatString(element.text)]),
+        ...formatAttrs('portal', { ref: element.ref, ...style(element) }),
+      ].join(' ');
+  }
+};
+
+const block = (header: string, elements: readonly Scene.Element[]): string =>
+  [`${header} {`, ...elements.map((element) => `  ${formatElement(element)}`), '}'].join('\n');
+
+export const formatObject = (object: Scene.WorldObject): string =>
+  block(
+    [
+      'object',
+      formatId(object.id),
+      ...(object.origin === undefined ? [] : ['@', formatPoint(object.origin)]),
+      ...OBJECT_ATTRS.flatMap(({ name, type }) => {
+        const value = { scale: object.scale, index: object.index, ref: object.ref }[name];
+        if (value === undefined) {
+          return [];
+        }
+        return [`${name}=${type === 'string' && typeof value === 'string' ? formatString(value) : String(value)}`];
+      }),
+    ].join(' '),
+    object.elements,
+  );
+
+export const formatCommand = (command: Scene.Command): string => {
+  switch (command.op) {
+    case 'upsert-object':
+      return formatObject(command.object);
+    case 'upsert-elements':
+      return block(`elements ${formatId(command.objectId)}`, command.elements);
+    case 'move-object':
+      return `move ${formatId(command.objectId)} @ ${formatPoint(command.origin)}`;
+    case 'remove-object':
+      return `remove object ${formatId(command.objectId)}`;
+    case 'remove-elements':
+      return `remove elements ${formatId(command.objectId)} ${command.elementIds.map(formatId).join(' ')}`;
+  }
+};
+
+/** A whole document: statements separated by a blank line, newline-terminated. */
+export const printCommands = (commands: readonly Scene.Command[]): string =>
+  commands.length === 0 ? '' : `${commands.map(formatCommand).join('\n\n')}\n`;
+
+/** A scene document — every statement an `object`, which is what a drawing serializes to. */
+export const print = (scene: Scene.Scene): string =>
+  printCommands(scene.objects.map((object) => ({ op: 'upsert-object', object }) as const));

package/src/dsl/semantic.test.ts

@@ -0,0 +1,200 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { parse, read } from './parse.ts';
+import { formatId } from './print.ts';
+
+/** The problems of a document as `severity: text-at-range`, so a test names what each one underlines. */
+const problemsOf = (text: string) =>
+  parse(text).problems.map(({ severity, from, to }) => `${severity}: ${text.slice(from, to)}`);
+
+const messagesOf = (text: string) =>
+  parse(text)
+    .problems.map(({ message }) => message)
+    .join('\n');
+
+describe('semantic statements', () => {
+  test('diagram attributes', ({ expect }) => {
+    const { diagram, problems } = read('diagram @ 10,20 flow=right grid=384x224 box=160x64\nnode A');
+    expect(problems).toEqual([]);
+    expect(diagram?.flow).toBe('right');
+    expect(diagram?.origin).toEqual({ x: 10, y: 20 });
+    expect(diagram?.grid).toEqual({ w: 384, h: 224 });
+    expect(diagram?.box).toEqual({ w: 160, h: 64 });
+    expect(diagram?.hinted).toBe(true);
+  });
+
+  test('nodes: label, ref, style, pins and relations', ({ expect }) => {
+    const { diagram, problems } = read(`
+      node A "Alpha" ref="packages/a" color=blue shape=ellipse @cell(1,2)
+      node B right-of A ~below A
+      node C @ 384,0
+    `);
+    expect(problems).toEqual([]);
+    const [a, b, c] = diagram?.nodes ?? [];
+    expect(a).toMatchObject({
+      id: 'A',
+      label: 'Alpha',
+      ref: 'packages/a',
+      color: 'blue',
+      shape: 'ellipse',
+      pin: { kind: 'cell', col: 1, row: 2 },
+    });
+    expect(b.label).toBe('B');
+    expect(b.relations.map(({ kind, target, soft }) => ({ kind, target, soft }))).toEqual([
+      { kind: 'right-of', target: 'A', soft: false },
+      { kind: 'below', target: 'A', soft: true },
+    ]);
+    expect(c.pin).toMatchObject({ kind: 'point', x: 384, y: 0 });
+  });
+
+  test('groups hold nodes and edges and relate to each other', ({ expect }) => {
+    const { diagram, problems } = read(`
+      group left "Left" { node A  node B  edge A -> B }
+      group right "Right" right-of left gap=64 color=yellow { node C }
+    `);
+    expect(problems).toEqual([]);
+    expect(diagram?.nodes.map(({ id, group }) => `${id}:${group}`)).toEqual(['A:left', 'B:left', 'C:right']);
+    expect(diagram?.groups[1]).toMatchObject({ id: 'right', label: 'Right', gap: 64, color: 'yellow' });
+    expect(diagram?.groups[1].relations[0]).toMatchObject({ kind: 'right-of', target: 'left', soft: false });
+    expect(diagram?.edges).toHaveLength(1);
+  });
+
+  test('edges: sides, two-way, no head, fans, waypoints and style', ({ expect }) => {
+    const { diagram, problems } = read(`
+      node A  node B  node C
+      edge A:right -> B:top|left "calls" stroke=dashed head=triangle
+      edge A <-> B "talks"
+      edge B -- C
+      edge A -> B, C "both"
+      edge A -> C via 600,_ cell(1.5,_) _,40
+    `);
+    expect(problems).toEqual([]);
+    const edges = diagram?.edges ?? [];
+    expect(edges[0]).toMatchObject({
+      from: { node: 'A', sides: ['right'] },
+      to: { node: 'B', sides: ['top', 'left'] },
+      label: 'calls',
+      stroke: 'dashed',
+      head: 'triangle',
+    });
+    // A two-way edge is two connectors; only the first carries the label.
+    expect(edges.slice(1, 3).map(({ from, to, label }) => `${from.node}->${to.node}:${label ?? ''}`)).toEqual([
+      'A->B:talks',
+      'B->A:',
+    ]);
+    expect(edges[3].head).toBe('none');
+    // Without `bus`, a fan is one labelled edge per target.
+    expect(edges.slice(4, 6).map(({ to, label }) => `${to.node}:${label}`)).toEqual(['B:both', 'C:both']);
+    expect(edges[6].via.map(({ x, y, unit }) => ({ x, y, unit }))).toEqual([
+      { x: 600, y: undefined, unit: 'scene' },
+      { x: 1.5, y: undefined, unit: 'cell' },
+      { x: undefined, y: 40, unit: 'scene' },
+    ]);
+  });
+
+  test('buses: a fan with `bus`, and named buses across statements', ({ expect }) => {
+    const { diagram, problems } = read(`
+      node H  node A  node B  node C
+      edge H -> A, B "trunk" bus
+      edge A -> C "one" bus=into
+      edge B -> C "two" bus=into
+    `);
+    expect(problems).toEqual([]);
+    const edges = diagram?.edges ?? [];
+    expect(edges[0].bus).toBe(edges[1].bus);
+    expect(edges[0].label).toBeUndefined();
+    expect([...(diagram?.busLabels.values() ?? [])]).toEqual(['trunk']);
+    expect(edges[2].bus).toMatch(/\|in$/);
+    expect(edges[2].label).toBe('one');
+  });
+
+  test('soft sides, group shape and aspect', ({ expect }) => {
+    const { diagram, problems } = read(`
+      diagram aspect=16:9
+      group g "G" compact max-width=3 { node A }
+      node B
+      edge A:~left|top -> B:bottom
+    `);
+    expect(problems).toEqual([]);
+    expect(diagram?.aspect).toBeCloseTo(16 / 9);
+    expect(diagram?.groups[0]).toMatchObject({ id: 'g', compact: true, maxWidth: 3 });
+    expect(diagram?.edges[0].from).toMatchObject({ sides: ['left', 'top'], soft: true });
+    expect(diagram?.edges[0].to.soft).toBeUndefined();
+    expect(diagram?.hinted).toBe(true);
+  });
+
+  test('a fan-in bus gathers into its target', ({ expect }) => {
+    const { diagram, problems } = read('node A  node B  node C  node D\nedge A, B, C -> D "joins" bus');
+    expect(problems).toEqual([]);
+    const keys = new Set(diagram?.edges.map((edge) => edge.bus));
+    expect([...keys]).toHaveLength(1);
+    expect([...keys][0]).toMatch(/^D\|.*\|in$/);
+    expect([...(diagram?.busLabels.values() ?? [])]).toEqual(['joins']);
+  });
+
+  test('a bus the engine cannot honour is reported', ({ expect }) => {
+    expect(problemsOf('node A\nnode B\nedge A -> B bus')).toEqual(['warning: bus']);
+    expect(problemsOf('node A\nnode B\nedge A -> B bus=solo')).toEqual(['warning: bus=solo']);
+    expect(problemsOf('node A\nnode B\nnode C\nedge A -> B, C bus via 10,_')).toEqual(['warning: 10,_']);
+  });
+
+  test('every problem names its source', ({ expect }) => {
+    expect(problemsOf('node A\nedge A -> Missing')).toEqual(['error: Missing']);
+    expect(problemsOf('node A\nnode B sideways-of A')).toEqual(['error: sideways-of']);
+    expect(problemsOf('node A\nnode B\nedge A:middle -> B')).toEqual(['error: middle']);
+    expect(problemsOf('node A below Nobody')).toEqual(['error: below Nobody']);
+    expect(problemsOf('node A below A')).toEqual(['error: below A']);
+    expect(problemsOf('node A\nnode A')).toEqual(['error: A']);
+    expect(problemsOf('group g { group h { node A } }')).toEqual(['error: h']);
+    expect(problemsOf('node A @cell(1.5,2)')).toEqual(['error: cell(1.5,2)']);
+    expect(problemsOf('node A\nnode B\nedge A -> B via _,_')).toEqual(['error: _,_']);
+    expect(problemsOf('node A\nnode B\nnode C\nnode D\nedge A, B -> C, D bus')).toEqual(['error: bus']);
+    expect(problemsOf('node A colour=red')).toEqual(['error: colour=red']);
+    expect(problemsOf('diagram grid=big\nnode A')).toEqual(['error: grid=big']);
+    expect(problemsOf('diagram aspect=wide\nnode A')).toEqual(['error: aspect=wide']);
+    expect(problemsOf('group g max-width=1.5 { node A }')).toEqual(['error: max-width=1.5']);
+  });
+
+  test('contradictions are relaxed with a warning, and the diagram still lays out', ({ expect }) => {
+    // Two pins on one cell: the second pin is dropped.
+    expect(problemsOf('node A @cell(0,0)\nnode B @cell(0,0)')).toEqual(['warning: @cell(0,0)']);
+    // A relation the pins contradict.
+    expect(problemsOf('node A @cell(0,0)\nnode B @cell(0,1) right-of A')).toEqual(['warning: right-of A']);
+    // Relations that cannot all hold.
+    const cycle = parse('node A right-of B\nnode B right-of A');
+    expect(cycle.problems.map(({ severity }) => severity)).toEqual(['warning']);
+    expect(cycle.commands.length).toBeGreaterThan(0);
+  });
+
+  test('a scene statement claiming a laid-out id is flagged', ({ expect }) => {
+    expect(problemsOf('node A\nobject A @ 0,0 { rect box 0,0 10x10 }')[0]).toMatch(/^warning: object A/);
+  });
+
+  test('the new keywords are reserved, so the printer quotes them as ids', ({ expect }) => {
+    for (const word of ['diagram', 'group', 'node', 'edge', 'cell', 'via', 'bus', 'compact']) {
+      expect(formatId(word)).toBe(`"${word}"`);
+    }
+    // Relation words and sides stay usable as ids.
+    expect(formatId('left')).toBe('left');
+    expect(formatId('below')).toBe('below');
+  });
+
+  test('an inherited property name is not a relationship', ({ expect }) => {
+    for (const word of ['constructor', 'toString', '__proto__']) {
+      expect(messagesOf(`node A\nnode B\nedge A ${word} B`)).toMatch(/Unknown relationship/);
+    }
+  });
+
+  test("no node or group may take the connectors object's id", ({ expect }) => {
+    expect(messagesOf('node edges\nnode B')).toMatch(/"edges" names the diagram's connectors object/);
+    expect(messagesOf('group edges { node A }')).toMatch(/"edges" names the diagram's connectors object/);
+  });
+
+  test('a document of scene statements alone has no diagram', ({ expect }) => {
+    expect(read('object A @ 0,0 { rect box 0,0 10x10 }').diagram).toBeUndefined();
+  });
+});

package/src/dsl/vocabulary.ts

@@ -0,0 +1,150 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The words the DSL knows, shared by the parser, the printer, the linter and completion so they
+// cannot drift apart — the round trip holds only because one table decides both which attributes
+// an element accepts and the order they print in. Every literal set is read off `scene.ts` rather
+// than restated, so a schema change shows up here as a type error or a new value, never as a
+// silently stale list.
+//
+
+import * as Scene from '../scene.ts';
+import * as Semantic from '../semantic.ts';
+
+/** Element kinds as the DSL spells them; each is also the scene element's `kind`. */
+export const ELEMENT_KINDS = [
+  ...Scene.BoxKind.literals,
+  'circle',
+  'line',
+  'curve',
+  'arc',
+  'text',
+  'arrow',
+  'portal',
+] as const;
+export type ElementKind = (typeof ELEMENT_KINDS)[number];
+
+/** Statements that state intent and leave layout to the engine. */
+export const SEMANTIC_KEYWORDS = ['diagram', 'group', 'node', 'edge'] as const;
+
+/** Statement keywords. */
+export const STATEMENT_KEYWORDS = ['object', 'elements', 'move', 'remove', ...SEMANTIC_KEYWORDS] as const;
+
+/** Keywords inside semantic statements: `@cell(c,r)`, `via …`, `bus`, `compact`. */
+export const CLAUSE_KEYWORDS = ['cell', 'via', 'bus', 'compact'] as const;
+
+/**
+ * Words the grammar reserves, so the printer knows to quote an id that collides with one.
+ * `_` is reserved too: it is the unbound arrow end.
+ */
+export const RESERVED: ReadonlySet<string> = new Set<string>([
+  ...STATEMENT_KEYWORDS,
+  ...ELEMENT_KINDS,
+  ...CLAUSE_KEYWORDS,
+  '_',
+]);
+
+/** Attribute value shapes; `enum` carries the literals the schema allows, `size` is `WxH`, `ratio` is `W:H`. */
+export type AttrType =
+  | { type: 'number' }
+  | { type: 'string' }
+  | { type: 'boolean' }
+  | { type: 'size' }
+  | { type: 'ratio' }
+  | { type: 'enum'; values: readonly string[] };
+
+export type AttrSpec = AttrType & { name: string };
+
+const STYLE: readonly AttrSpec[] = [
+  { name: 'color', type: 'enum', values: Scene.Color.literals },
+  { name: 'fill', type: 'enum', values: Scene.Fill.literals },
+  { name: 'stroke', type: 'enum', values: Scene.Stroke.literals },
+  { name: 'weight', type: 'enum', values: Scene.Weight.literals },
+];
+
+const BOX_ATTRS: readonly AttrSpec[] = [
+  { name: 'rotation', type: 'number' },
+  { name: 'corners', type: 'enum', values: Scene.Corners.literals },
+  ...STYLE,
+];
+
+/**
+ * Attributes each element kind accepts, in the order they print. Geometry and the label are
+ * positional, so the schema's `x`/`y`/`w`/`h`/`points`/`text` do not appear here — except
+ * `text`'s wrap width, which the schema also calls `w`.
+ */
+export const ELEMENT_ATTRS: Record<ElementKind, readonly AttrSpec[]> = {
+  rect: BOX_ATTRS,
+  ellipse: BOX_ATTRS,
+  diamond: BOX_ATTRS,
+  triangle: BOX_ATTRS,
+  circle: STYLE,
+  line: [{ name: 'closed', type: 'boolean' }, ...STYLE],
+  curve: STYLE,
+  arc: STYLE,
+  text: [{ name: 'w', type: 'number' }, ...STYLE],
+  arrow: [
+    { name: 'head', type: 'enum', values: Scene.ArrowHead.literals },
+    { name: 'tail', type: 'enum', values: Scene.ArrowTail.literals },
+    { name: 'relation', type: 'enum', values: Scene.Relation.literals },
+    ...STYLE,
+  ],
+  portal: [{ name: 'ref', type: 'string' }, ...STYLE],
+};
+
+/** Object attributes other than `@ <origin>`, in the order they print. */
+export const OBJECT_ATTRS: readonly AttrSpec[] = [
+  { name: 'scale', type: 'number' },
+  { name: 'index', type: 'string' },
+  { name: 'ref', type: 'string' },
+];
+
+/** `diagram` attributes. */
+export const DIAGRAM_ATTRS: readonly AttrSpec[] = [
+  { name: 'flow', type: 'enum', values: Semantic.FLOWS },
+  { name: 'grid', type: 'size' },
+  { name: 'box', type: 'size' },
+  { name: 'aspect', type: 'ratio' },
+];
+
+/** `group` attributes. */
+export const GROUP_ATTRS: readonly AttrSpec[] = [
+  { name: 'gap', type: 'number' },
+  { name: 'max-width', type: 'number' },
+  { name: 'color', type: 'enum', values: Scene.Color.literals },
+];
+
+/** `node` attributes. */
+export const NODE_ATTRS: readonly AttrSpec[] = [
+  { name: 'ref', type: 'string' },
+  { name: 'shape', type: 'enum', values: Scene.BoxKind.literals },
+  { name: 'color', type: 'enum', values: Scene.Color.literals },
+  { name: 'fill', type: 'enum', values: Scene.Fill.literals },
+  { name: 'stroke', type: 'enum', values: Scene.Stroke.literals },
+];
+
+/** `edge` attributes. */
+export const EDGE_ATTRS: readonly AttrSpec[] = [
+  { name: 'head', type: 'enum', values: Scene.ArrowHead.literals },
+  { name: 'tail', type: 'enum', values: Scene.ArrowTail.literals },
+  { name: 'stroke', type: 'enum', values: Scene.Stroke.literals },
+  { name: 'color', type: 'enum', values: Scene.Color.literals },
+];
+
+/** Placement relations a `node` or `group` may state; `~` before one makes it a preference. */
+export const RELATION_WORDS: readonly string[] = Semantic.RELATION_KINDS;
+
+/** An id that needs no quoting: a bare word that is not reserved. */
+export const BARE_ID = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+/** A ref that needs no quoting: every segment is a bare word. */
+export const BARE_REF = /^[A-Za-z_][A-Za-z0-9_-]*(\/[A-Za-z_][A-Za-z0-9_-]*)?(#[A-Za-z_][A-Za-z0-9_-]*)?$/;
+
+/**
+ * A structurally valid ref — `[object/]element[#port]`, as `Scene.parseRef` reads it, whose ids may
+ * not contain `/` or `#`. Separate from {@link BARE_REF} because quoting exists to carry a ref
+ * whose ids cannot lex bare (`1st/box` from a numeric node id), which is well-formed all the same.
+ */
+export const REF_SHAPE = /^[^/#]+(\/[^/#]+)?(#[^/#]+)?$/;

package/src/dx-svg.test.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { FORMAT, embed, extract, isDxSvg } from './dx-svg.ts';
+
+const SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="0 0 10 10"><rect width="10" height="10"/></svg>';
+
+describe('dx-svg', () => {
+  test('a payload round-trips through the SVG, which still renders as before', ({ expect }) => {
+    const payload = {
+      format: FORMAT,
+      version: 1,
+      objects: [
+        { id: 'a', text: '<b> & </metadata> "quoted"' },
+        { id: 'b', ref: { '/': 'echo:/a' } },
+      ],
+    };
+    const svg = embed(SVG, payload);
+
+    expect(isDxSvg(svg)).toBe(true);
+    expect(extract(svg)).toEqual(payload);
+    expect(svg).toContain('<rect width="10" height="10"/>');
+    expect(svg).toContain(`dx:payload="${FORMAT}"`);
+    // Escaped as JSON, so the payload's text cannot close the element or need entity decoding.
+    expect(svg.match(/<\/metadata>/g)).toHaveLength(1);
+    // One object per line, so a changed drawing diffs by object.
+    expect(svg).toMatch(/\n\{"id":"a".*\},\n\{"id":"b"/);
+  });
+
+  test('a plain SVG has no payload, and a second embed is refused', ({ expect }) => {
+    expect(isDxSvg(SVG)).toBe(false);
+    expect(extract(SVG)).toBeUndefined();
+    expect(() => embed(embed(SVG, {}), {})).toThrow(/already/);
+  });
+
+  test('an unknown encoding is an error, not a missing payload', ({ expect }) => {
+    const svg = embed(SVG, { objects: [] }).replace('data-encoding="json"', 'data-encoding="deflate-raw+base64"');
+    expect(() => extract(svg)).toThrow(/Unsupported/);
+  });
+});

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]);
+};