@itsthecsguy/linework 0.1.2 → 0.1.3

package/README.md

@@ -102,6 +102,29 @@ Linework lays it out with ELK and draws it with draw.io's own renderer. It draws
 
 To change a diagram, the agent runs `linework show` to get the spec back, hand edits included, edits it and rebuilds. The rebuild merges into your layout. Your boxes stay where you put them, new ones go next to their neighbours, and only the edges that need it get rerouted (with draw.io's libavoid router).
 
+## Examples
+
+These are first builds of the specs in [`examples/`](examples), with no hand edits. Each one is a `.drawio.svg`, so the image you see here is also the file you'd open in draw.io. Click one to see its spec.
+
+<table>
+<tr>
+<td width="50%" valign="top">Architecture, with AWS icons<br><br><a href="examples/serverless-aws.yaml"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/gallery/serverless-aws-dark.drawio.svg"><img alt="Architecture diagram: an uploader posts to an API Gateway, a Lambda presigns an S3 upload, and S3 events queue resize jobs for a second Lambda." src="docs/gallery/serverless-aws-light.drawio.svg" width="100%"></picture></a></td>
+<td width="50%" valign="top">Flow<br><br><a href="examples/refund-flow.yaml"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/gallery/refund-flow-dark.drawio.svg"><img alt="Flowchart of a refund: look up the order, check the 30-day window and the amount, then auto-approve, queue for review or deny, and email the customer." src="docs/gallery/refund-flow-light.drawio.svg" width="100%"></picture></a></td>
+</tr>
+</table>
+
+State
+
+<a href="examples/job-state.yaml"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/gallery/job-state-dark.drawio.svg"><img alt="State diagram of a background job: queued, running, paused, waiting to retry, succeeded, failed and cancelled, with the transitions between them." src="docs/gallery/job-state-light.drawio.svg"></picture></a>
+
+Sequence
+
+<a href="examples/pay-sequence.yaml"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/gallery/pay-sequence-dark.drawio.svg"><img alt="Sequence diagram of a card payment: the web app posts to the checkout API, which writes the order and creates a Stripe PaymentIntent, with an alt frame for success and decline." src="docs/gallery/pay-sequence-light.drawio.svg"></picture></a>
+
+ER
+
+<a href="examples/shop-er.yaml"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/gallery/shop-er-dark.drawio.svg"><img alt="Entity relationship diagram of a shop: customers, addresses, orders, order items, products, inventory and payments, with keys and crow's-foot cardinality." src="docs/gallery/shop-er-light.drawio.svg"></picture></a>
+
 ## Styles
 
 Set `theme:` in the spec.
@@ -115,6 +138,21 @@ Set `theme:` in the spec.
 | `blueprint` | technical deep dives. Blue ink on pale drafting paper, monospace. |
 | `c4` | C4-model diagrams, in quiet blues and grays |
 
+The same spec in each style:
+
+<table>
+<tr>
+<td width="33%" align="center" valign="top"><code>clean</code><br><br><img alt="A web app, checkout API and orders database in the clean style" src="docs/gallery/style-clean.drawio.svg"></td>
+<td width="33%" align="center" valign="top"><code>soft</code><br><br><img alt="A web app, checkout API and orders database in the soft style" src="docs/gallery/style-soft.drawio.svg"></td>
+<td width="33%" align="center" valign="top"><code>dark</code><br><br><img alt="A web app, checkout API and orders database in the dark style" src="docs/gallery/style-dark.drawio.svg"></td>
+</tr>
+<tr>
+<td width="33%" align="center" valign="top"><code>sketch</code><br><br><img alt="A web app, checkout API and orders database in the sketch style" src="docs/gallery/style-sketch.drawio.svg"></td>
+<td width="33%" align="center" valign="top"><code>blueprint</code><br><br><img alt="A web app, checkout API and orders database in the blueprint style" src="docs/gallery/style-blueprint.drawio.svg"></td>
+<td width="33%" align="center" valign="top"><code>c4</code><br><br><img alt="A web app, checkout API and orders database in the c4 style" src="docs/gallery/style-c4.drawio.svg"></td>
+</tr>
+</table>
+
 Color is for meaning. Nodes stay neutral by default, and errors and successes are red and green in every style. Mark the part the doc is about with `highlight: true` on a node or `==>` on an edge, and it's drawn in the style's accent color. Use `color: red` (or blue, violet, pink, orange, amber, green, teal, gray) for categories.
 
 Linework sizes every box from the real width of its text in the font it renders with, wrapping long labels instead of widening boxes. Each SVG carries a subset of that font (about 10 to 15KB), so text fits the same way on GitHub, in a browser or in a doc. `check` flags labels that overflow, overlap a box, another label, another edge or a group border, and `build` moves edge labels until they're clear.

package/dist/drawio/theme.js

@@ -76,10 +76,10 @@ function lightPaint(sw, neutral, text, muted, accent) {
     return (color, highlight) => {
         if (highlight) {
             const s = sw[color === 'neutral' || color === 'ink' ? accent : color];
-            return { fill: s.solid, stroke: s.solid, text: '#FFFFFF', sub: 'rgba(255,255,255,0.78)', strokeWidth: 1 };
+            return { fill: s.solid, stroke: s.solid, text: '#FFFFFF', sub: 'rgba(255,255,255,0.9)', strokeWidth: 1 };
         }
         if (color === 'ink')
-            return { fill: text, stroke: text, text: '#FFFFFF', sub: muted, strokeWidth: 1 };
+            return { fill: text, stroke: text, text: '#FFFFFF', sub: 'rgba(255,255,255,0.72)', strokeWidth: 1 };
         if (color === 'neutral')
             return { ...neutral, text, sub: muted, strokeWidth: 1 };
         const s = sw[color];
@@ -92,16 +92,16 @@ const CLEAN = {
     canvas: '#FFFFFF',
     text: '#17171C',
     muted: '#6B6B76',
-    edge: '#A0A0AB',
+    edge: '#868691',
     edgeText: '#52525C',
     edgeWidth: 1.25,
     accent: 'blue',
     kindColors: false,
     radius: 10,
-    group: { fill: '#F5F5F7', nested: '#EBEBEF', stroke: 'none', dashed: false, text: '#6B6B76' },
+    group: { fill: '#F5F5F7', nested: '#EBEBEF', stroke: 'none', dashed: false, text: '#61616C' },
     note: { fill: '#FFF4CC', stroke: 'none', text: '#5C4300' },
     well: '#F3F3F5',
-    paint: lightPaint(LIGHT_SW, { fill: '#FFFFFF', stroke: '#DADAE0' }, '#17171C', '#6B6B76', 'blue'),
+    paint: lightPaint(LIGHT_SW, { fill: '#FFFFFF', stroke: '#C4C4CC' }, '#17171C', '#6B6B76', 'blue'),
     edgePaint: (color, hl) => {
         const s = LIGHT_SW[color ?? 'blue'];
         if (hl)
@@ -115,12 +115,12 @@ const SOFT = {
     name: 'soft',
     kindColors: true,
     radius: 12,
-    group: { fill: '#F7F7F9', nested: '#EFEFF3', stroke: 'none', dashed: false, text: '#6B6B76' },
+    group: { fill: '#F7F7F9', nested: '#EFEFF3', stroke: 'none', dashed: false, text: '#61616C' },
     paint: (color, hl) => {
         if (hl || color === 'ink')
             return CLEAN.paint(color, hl);
         const c = color === 'neutral' ? 'gray' : color;
-        return { fill: SOFT_TINT[c], stroke: 'none', text: c === 'gray' ? '#17171C' : LIGHT_SW[c].ink, sub: c === 'gray' ? '#6B6B76' : LIGHT_SW[c].ink + 'B3', strokeWidth: 1 };
+        return { fill: SOFT_TINT[c], stroke: 'none', text: c === 'gray' ? '#17171C' : LIGHT_SW[c].ink, sub: c === 'gray' ? '#6B6B76' : LIGHT_SW[c].ink + 'E0', strokeWidth: 1 };
     },
 };
 const DARK = {
@@ -141,7 +141,7 @@ const DARK = {
     paint: (color, hl) => {
         if (hl) {
             const s = DARK_SW[color === 'neutral' || color === 'ink' ? 'blue' : color];
-            return { fill: s.solid, stroke: s.solid, text: '#FFFFFF', sub: 'rgba(255,255,255,0.78)', strokeWidth: 1 };
+            return { fill: s.solid, stroke: s.solid, text: '#FFFFFF', sub: 'rgba(255,255,255,0.9)', strokeWidth: 1 };
         }
         if (color === 'ink')
             return { fill: '#E6EDF3', stroke: '#E6EDF3', text: '#0D1117', sub: '#59636E', strokeWidth: 1 };
@@ -212,7 +212,7 @@ const BLUEPRINT = {
     accent: 'blue',
     kindColors: false,
     radius: 4,
-    group: { fill: 'none', stroke: '#9DB0D0', dashed: true, text: '#5A6F92' },
+    group: { fill: 'none', stroke: '#7489AF', dashed: true, text: '#5A6F92' },
     note: { fill: '#EAF0FA', stroke: '#9DB0D0', text: BP_INK },
     well: '#EAF0FA',
     paint: (color, hl) => {
@@ -236,7 +236,7 @@ const BLUEPRINT = {
 // Other diagram types use `clean`.
 const C4_KIND = {
     person: { fill: '#1E3466', stroke: '#1E3466', text: '#FFFFFF', type: 'Person' },
-    external: { fill: '#6B7383', stroke: '#6B7383', text: '#FFFFFF', type: 'External system' },
+    external: { fill: '#626A7A', stroke: '#626A7A', text: '#FFFFFF', type: 'External system' },
 };
 const C4_CONTAINER = { fill: '#456A9E', stroke: '#456A9E', text: '#FFFFFF', type: 'Container' };
 const C4 = { ...CLEAN, name: 'c4', group: { fill: 'none', stroke: '#444444', dashed: true, text: '#444444' }, edge: '#707070', edgeText: '#444444' };
@@ -250,7 +250,7 @@ export function paintFor(type, kind, theme, look = {}) {
     const t = palette(theme);
     if (theme === 'c4' && type === 'architecture' && !look.highlight && !look.color) {
         const c = C4_KIND[kind] ?? C4_CONTAINER;
-        return { fill: c.fill, stroke: c.stroke, text: c.text, sub: 'rgba(255,255,255,0.8)', strokeWidth: 1 };
+        return { fill: c.fill, stroke: c.stroke, text: c.text, sub: 'rgba(255,255,255,0.92)', strokeWidth: 1 };
     }
     const k = kindDef(type, kind);
     // A highlight is the style's accent unless the spec names a color.
@@ -274,7 +274,9 @@ export function nodeStyle(type, kind, theme = 'clean', look = {}) {
     const r = t.radius;
     switch (k.shape) {
         case 'cylinder':
-            return `shape=cylinder3;boundedLbl=1;backgroundOutline=1;size=7;${base}`;
+            // With an outline the lid is drawn, and the text centres on the face below
+            // it. Without one (soft) the lid is invisible: centre on the whole shape.
+            return `shape=cylinder3;boundedLbl=${stroke === 'none' ? 0 : 1};backgroundOutline=1;size=${CYL_SIZE};${base}`;
         case 'pill':
             return `rounded=1;arcSize=50;${base}`;
         case 'diamond':
@@ -298,6 +300,17 @@ export function nodeStyle(type, kind, theme = 'clean', look = {}) {
             return `rounded=1;absoluteArcSize=1;arcSize=${r * 2};${base}`;
     }
 }
+/** Depth of a cylinder's lid and base curve. */
+export const CYL_SIZE = 7;
+/**
+ * Vertical centre of a node's text, from the top of its box. draw.io bounds a
+ * cylinder's label between its lid (2 x size) and 0.3 x size above the base.
+ */
+export function textMiddle(style, h) {
+    if (!/shape=cylinder3/.test(style) || !/boundedLbl=1/.test(style))
+        return h / 2;
+    return (2 * CYL_SIZE + h - 0.3 * CYL_SIZE) / 2;
+}
 /** Horizontal text padding inside a node, each side. */
 export const PAD_X = 16;
 /** Vertical text padding inside a node, each side. */
@@ -309,6 +322,8 @@ export function fieldStyle(theme = 'clean') {
     return ('text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;spacingLeft=0;spacingRight=0;overflow=fill;' +
         `rotatable=0;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;whiteSpace=wrap;${fontPart(t, t.type.size.field, t.text)}`);
 }
+/** Left inset of a group's title. */
+export const GROUP_INSET = 14;
 export function groupStyle(theme = 'clean', look = {}, depth = 0) {
     const t = palette(theme);
     let { fill, stroke, text } = t.group;
@@ -324,7 +339,7 @@ export function groupStyle(theme = 'clean', look = {}, depth = 0) {
     return (`rounded=1;absoluteArcSize=1;arcSize=${t.radius * 2 + 4};html=1;whiteSpace=wrap;container=1;collapsible=0;` +
         `fillColor=${fill};strokeColor=${stroke};strokeWidth=${look.highlight ? 1.5 : 1};` +
         (t.group.dashed ? dashes(t) : '') +
-        'verticalAlign=top;align=left;spacingLeft=14;spacingTop=9;' +
+        `verticalAlign=top;align=left;spacingLeft=${GROUP_INSET};spacingTop=9;` +
         `${fontPart(t, t.type.size.group, text)}fontStyle=1;${t.extra}`);
 }
 /** Group title HTML: sentence case, except blueprint's drafting capitals. */
@@ -358,8 +373,10 @@ export function lifelineStyle(kind, theme = 'clean', headH = 48, look = {}) {
     const t = palette(theme);
     const c = paintFor('sequence', kind, theme, look);
     const k = kindDef('sequence', kind);
-    const stroke = c.stroke === 'none' ? (k.dashed ? '#A1A1AA' : c.fill) : c.stroke;
-    // The lifeline's dashed stem uses the stroke colour: keep it quiet even when the head is loud.
+    // The dashed stem takes the stroke color, so a highlighted head keeps the plain
+    // participant line: the accent stays on the head and the highlighted messages.
+    const quiet = t.paint('neutral', false).stroke;
+    const stroke = look.highlight ? (quiet === 'none' ? t.edge : quiet) : c.stroke === 'none' ? (k.dashed ? '#A1A1AA' : c.fill) : c.stroke;
     return (`shape=umlLifeline;perimeter=lifelinePerimeter;container=1;collapsible=0;recursiveResize=0;outlineConnect=0;size=${headH};` +
         `html=1;whiteSpace=wrap;rounded=1;absoluteArcSize=1;arcSize=${t.radius * 2};fillColor=${c.fill};strokeColor=${stroke};strokeWidth=${Math.min(1.5, c.strokeWidth)};` +
         `spacingLeft=${PAD_X - 4};spacingRight=${PAD_X - 4};` +
@@ -384,12 +401,17 @@ export function messageStyle(style, theme = 'clean', self = false, look = {}) {
         (self ? 'edgeStyle=orthogonalEdgeStyle;rounded=1;align=left;spacingLeft=6;verticalAlign=middle;' : '') +
         `${fontPart(t, t.type.size.edge, p.text)}${look.highlight ? 'fontStyle=1;' : ''}labelBackgroundColor=${t.canvas};labelPadding=1 5;${t.extra}`);
 }
+/** Padding of a sequence frame's operator tab, and its inset from the frame's corner. */
+export const FRAME_TAB_X = 9, FRAME_TAB_Y = 3, FRAME_TAB_INSET = 4;
 export function frameStyle(theme = 'clean') {
     const t = palette(theme);
-    const line = t.name === 'dark' ? '#3D444D' : t.name === 'clean' || t.name === 'soft' || t.name === 'c4' ? '#DADAE0' : t.muted;
-    // The operator (alt, loop, opt) sits in the corner as a small label, not a UML tab.
-    return (`rounded=1;absoluteArcSize=1;arcSize=${t.radius * 2};whiteSpace=wrap;html=1;container=0;verticalAlign=top;align=left;spacing=0;spacingLeft=10;spacingTop=4;` +
-        `fillColor=none;strokeColor=${line};strokeWidth=1;${fontPart(t, t.type.size.group, t.muted)}fontStyle=1;${t.extra}`);
+    // The operator (alt, loop, opt) sits in a small tab in the frame's corner: UML's
+    // pentagon, drawn as a chip, inset the same from both sides so its square corner
+    // stays inside the frame's rounded one. draw.io draws an HTML label's background
+    // 1px left of and 3.5px below where its spacing puts it; the +1 and -3.5 cancel that.
+    return (`rounded=1;absoluteArcSize=1;arcSize=${t.radius * 2};whiteSpace=wrap;html=1;container=0;verticalAlign=top;align=left;spacing=0;spacingLeft=${FRAME_TAB_X + FRAME_TAB_INSET + 1};spacingTop=${FRAME_TAB_Y + FRAME_TAB_INSET - 3.5};` +
+        `labelBackgroundColor=${t.well};labelPadding=${FRAME_TAB_Y} ${FRAME_TAB_X};` +
+        `fillColor=none;strokeColor=${t.edge};strokeWidth=1;${fontPart(t, t.type.size.group, t.text)}fontStyle=1;${t.extra}`);
 }
 export function guardStyle(theme = 'clean') {
     const t = palette(theme);
@@ -397,7 +419,7 @@ export function guardStyle(theme = 'clean') {
 }
 export function separatorStyle(theme = 'clean') {
     const t = palette(theme);
-    return `endArrow=none;dashed=1;dashPattern=4 4;html=1;strokeColor=${t.name === 'dark' ? '#3D444D' : t.name === 'clean' || t.name === 'soft' || t.name === 'c4' ? '#DADAE0' : t.muted};`;
+    return `endArrow=none;dashed=1;dashPattern=4 4;html=1;strokeColor=${t.edge};`;
 }
 export function noteStyle(theme = 'clean') {
     const t = palette(theme);

package/dist/drawio/write.js

@@ -1,7 +1,7 @@
 import { kindDef } from '../spec/model.js';
 import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
 import { ICON_PAD, ICON_SIZE, resolveIcon } from './icons.js';
-import { ER_HEAD, ER_ROW, edgeStyle, erEdgeStyle, fieldLabel, fieldStyle, groupLabel, groupStyle, nodeLabel, nodeStyle, paintFor, palette } from './theme.js';
+import { CYL_SIZE, ER_HEAD, ER_ROW, edgeStyle, erEdgeStyle, fieldLabel, fieldStyle, groupLabel, groupStyle, nodeLabel, nodeStyle, paintFor, palette, textMiddle, typeface } from './theme.js';
 export { ER_HEAD, ER_ROW };
 export const FORMAT_VERSION = '1';
 export const xmlEsc = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\n/g, '&#10;');
@@ -72,7 +72,8 @@ export function nodeChildren(d, n, box) {
                 parent: n.id,
                 attrs: { label: '', aiviz_type: 'icon' },
                 style: r.style,
-                box: { x: (ICON_PAD - ICON_SIZE) / 2 + 2, y: Math.round((box.h - ICON_SIZE) / 2), w: ICON_SIZE, h: ICON_SIZE },
+                // Level with the text, which on a cylinder sits below the lid.
+                box: { x: (ICON_PAD - ICON_SIZE) / 2 + 2, y: Math.round(textMiddle(styleFor(d, n), box.h) - ICON_SIZE / 2), w: ICON_SIZE, h: ICON_SIZE },
             });
     }
     return out;
@@ -115,12 +116,38 @@ export const groupStyleFor = (d, g) => groupStyle(d.theme, g, groupDepth(d, g));
 export function groupAttrs(g, theme = 'clean') {
     return { label: groupLabel(g.label, theme), aiviz_type: 'group', aiviz_label: g.label, ...lookAttrs(g) };
 }
+/**
+ * Layout sizes a decision's diamond from its text wrapped narrow (see nodeSizes),
+ * but draw.io wraps at the diamond's full width, so a long question runs out over
+ * the slanted sides. Inset the label to the width layout measured.
+ */
+function diamondInset(d, n, box) {
+    if (kindDef(d.type, n.kind).shape !== 'diamond')
+        return '';
+    const text = (box.w - 40) / 1.5;
+    const side = Math.max(0, Math.floor((box.w - text - 10) / 2));
+    return `spacingLeft=${side};spacingRight=${side};`;
+}
+/**
+ * Where a vertical edge at `x` meets a cylinder's curved top or base, as a
+ * fraction of its height. Off centre the curve sits inside the bounding box, and
+ * an arrow stopped at the box would float short of it.
+ */
+function rimY(p, b) {
+    const top = Math.abs(p.y - b.y) < 0.5, base = Math.abs(p.y - (b.y + b.h)) < 0.5;
+    if (!top && !base)
+        return undefined;
+    const u = Math.min(1, Math.abs(p.x - (b.x + b.w / 2)) / (b.w / 2));
+    const dip = CYL_SIZE * (1 - Math.sqrt(1 - u * u));
+    return top ? dip / b.h : (b.h - dip) / b.h;
+}
 /** Exit/entry constraints so draw.io leaves and enters nodes where ELK did. */
-export function portStyle(points, s, t) {
+export function portStyle(points, s, t, cyl = {}) {
     const start = points[0], end = points[points.length - 1];
     const c01 = (v) => Math.min(1, Math.max(0, Math.round(v * 1000) / 1000));
-    return (`exitX=${c01((start.x - s.x) / s.w)};exitY=${c01((start.y - s.y) / s.h)};exitDx=0;exitDy=0;` +
-        `entryX=${c01((end.x - t.x) / t.w)};entryY=${c01((end.y - t.y) / t.h)};entryDx=0;entryDy=0;`);
+    const sr = cyl.from ? rimY(start, s) : undefined, tr = cyl.to ? rimY(end, t) : undefined;
+    return (`exitX=${c01((start.x - s.x) / s.w)};exitY=${c01(sr ?? (start.y - s.y) / s.h)};exitDx=0;exitDy=0;${sr !== undefined ? 'exitPerimeter=0;' : ''}` +
+        `entryX=${c01((end.x - t.x) / t.w)};entryY=${c01(tr ?? (end.y - t.y) / t.h)};entryDx=0;entryDy=0;${tr !== undefined ? 'entryPerimeter=0;' : ''}`);
 }
 export function sceneFromLayout(d, l) {
     const parentOf = new Map();
@@ -139,43 +166,140 @@ export function sceneFromLayout(d, l) {
     const vertices = [];
     for (const g of d.groups) {
         const box = rel(g.id);
-        vertices.push({ id: g.id, parent: g.parent ?? '1', attrs: { ...groupAttrs(g, d.theme), aiviz_auto: autoAttr(box) }, style: groupStyleFor(d, g), box });
+        const inset = l.titleInset?.get(g.id);
+        vertices.push({ id: g.id, parent: g.parent ?? '1', attrs: { ...groupAttrs(g, d.theme), aiviz_auto: autoAttr(box) }, style: groupStyleFor(d, g) + (inset ? `spacingLeft=${inset};` : ''), box });
     }
     for (const n of d.nodes) {
         const box = rel(n.id);
-        vertices.push({ id: n.id, parent: n.parent ?? '1', attrs: { ...nodeAttrs(d, n), aiviz_auto: autoAttr(box) }, style: styleFor(d, n), box });
+        vertices.push({ id: n.id, parent: n.parent ?? '1', attrs: { ...nodeAttrs(d, n), aiviz_auto: autoAttr(box) }, style: styleFor(d, n) + diamondInset(d, n, box), box });
         vertices.push(...nodeChildren(d, n, box));
     }
+    const isCyl = (id) => { const n = d.nodes.find((x) => x.id === id); return !!n && kindDef(d.type, n.kind).shape === 'cylinder'; };
     const edges = d.edges.map((e) => {
         const le = l.edges.get(e.id);
+        const cyl = { from: isCyl(e.from), to: isCyl(e.to) };
         const base = { id: edgeCellId(e.id), parent: '1', attrs: edgeAttrs(e), style: edgeStyleFor(d, e, labelBg(d, l, le?.label)), source: e.from, target: e.to };
         if (!le)
             return base;
+        if (e.from === e.to && le.label && e.label && le.points.length === 4) {
+            // A self-loop: the label sits beside the loop's outer run, not on it.
+            const [, a, b] = le.points;
+            const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+            return {
+                ...base,
+                style: base.style + portStyle(le.points, abs(e.from), abs(e.to), cyl),
+                points: le.points.slice(1, -1),
+                labelX: 0.001,
+                labelOffset: { x: le.label.x + le.label.w / 2 - mid.x, y: le.label.y + le.label.h / 2 - mid.y },
+            };
+        }
         return {
             ...base,
-            style: base.style + portStyle(le.points, abs(e.from), abs(e.to)),
+            style: base.style + portStyle(le.points, abs(e.from), abs(e.to), cyl),
             points: le.points.slice(1, -1),
-            labelX: le.label && e.label ? (labelSpot(le.points, le.label) ?? labelFraction(le.points, { x: le.label.x + le.label.w / 2, y: le.label.y + le.label.h / 2 })) : undefined,
+            labelX: le.label && e.label ? (labelSpot(le.points, le.label, l.direction) ?? labelFraction(le.points, { x: le.label.x + le.label.w / 2, y: le.label.y + le.label.h / 2 })) : undefined,
         };
     });
+    alignLabels(d, l, edges);
     return { name: d.title ?? 'Diagram', background: palette(d.theme).canvas, meta: diagramMeta(d), vertices, edges, raw: [] };
 }
+/** The point at a draw.io label fraction (-1..1) along a route, and the run it sits on. */
+function spotAt(pts, frac) {
+    const lens = pts.slice(1).map((b, i) => Math.hypot(b.x - pts[i].x, b.y - pts[i].y));
+    let at = ((frac + 1) / 2) * lens.reduce((x, y) => x + y, 0);
+    for (let i = 0; i < lens.length; i++) {
+        const a = pts[i], b = pts[i + 1], len = lens[i];
+        if (at <= len + 1e-6 || i === lens.length - 1) {
+            const t = len ? Math.min(1, at / len) : 0;
+            return { p: { x: a.x + t * (b.x - a.x), y: a.y + t * (b.y - a.y) }, a, b };
+        }
+        at -= len;
+    }
+    return undefined;
+}
+/**
+ * Labels on neighbouring parallel runs (two edges dropping side by side) sit at
+ * whatever height each run's midpoint gives, often a few px apart. Put them on
+ * one line when each can move there and stay on its own run.
+ */
+function alignLabels(d, l, edges) {
+    const h = Math.ceil(typeface(d.theme).size.edge * 1.2) + 4;
+    const spots = edges.flatMap((se) => {
+        const e = d.edges.find((x) => edgeCellId(x.id) === se.id);
+        const le = e && l.edges.get(e.id);
+        if (!le || se.labelX === undefined || se.labelOffset || !e.label)
+            return [];
+        const s = spotAt(le.points, se.labelX);
+        if (!s)
+            return [];
+        const vertical = Math.abs(s.a.x - s.b.x) < 0.5;
+        if (!vertical && Math.abs(s.a.y - s.b.y) >= 0.5)
+            return [];
+        return [{ se, pts: le.points, ...s, vertical }];
+    });
+    for (const vertical of [true, false]) {
+        const along = (p) => (vertical ? p.y : p.x), across = (p) => (vertical ? p.x : p.y);
+        const group = spots.filter((s) => s.vertical === vertical).sort((a, b) => along(a.p) - along(b.p));
+        for (let i = 0; i < group.length;) {
+            let j = i + 1;
+            while (j < group.length && along(group[j].p) - along(group[i].p) <= 8)
+                j++;
+            const set = group.slice(i, j);
+            i = j;
+            if (set.length < 2)
+                continue;
+            // Side by side on different runs, not one run's labels stacked.
+            const xs = set.map((s) => across(s.p));
+            if (Math.max(...xs) - Math.min(...xs) < 20)
+                continue;
+            const target = Math.round(set.reduce((m, s) => m + along(s.p), 0) / set.length);
+            const fits = set.every((s) => {
+                const lo = Math.min(along(s.a), along(s.b)) + h / 2 + 4, hi = Math.max(along(s.a), along(s.b)) - h / 2 - 4;
+                return target >= lo && target <= hi;
+            });
+            if (!fits)
+                continue;
+            for (const s of set) {
+                const c = vertical ? { x: s.p.x, y: target } : { x: target, y: s.p.y };
+                s.se.labelX = labelFraction(s.pts, c);
+            }
+        }
+    }
+}
 const attrString = (attrs) => Object.entries(attrs)
     .filter(([k]) => k !== 'id')
     .map(([k, v]) => ` ${k}="${xmlEsc(v)}"`)
     .join('');
 export function serialize(scene) {
-    // Parents before children.
     const parentOf = new Map(scene.vertices.map((v) => [v.id, v.parent]));
-    const depth = (id) => {
-        const p = parentOf.get(id);
-        return p && p !== '1' ? 1 + depth(p) : 0;
-    };
-    // Containers first (outermost first), then everything else in its original order,
-    // which show() reads back and ELK uses as a placement hint.
-    const isParent = new Set(scene.vertices.map((v) => v.parent));
-    const containers = scene.vertices.filter((v) => isParent.has(v.id) || v.attrs.aiviz_type === 'group').sort((a, b) => depth(a.id) - depth(b.id));
-    const vertices = [...containers, ...scene.vertices.filter((v) => !containers.includes(v))];
+    // Every cell after its parent, otherwise in the scene's order, which is spec
+    // order: show() reads it back and ELK uses it as a placement hint. Groups go
+    // first so nodes can sit in them; a node's own children (icon, table rows)
+    // already follow it.
+    const groups = scene.vertices.filter((v) => v.attrs.aiviz_type === 'group');
+    const rest = scene.vertices.filter((v) => v.attrs.aiviz_type !== 'group');
+    const placed = new Set(['1']);
+    const vertices = [];
+    for (const list of [groups, rest]) {
+        let todo = [...list];
+        while (todo.length) {
+            const left = [];
+            for (const v of todo) {
+                if (placed.has(v.parent) || !parentOf.has(v.parent)) {
+                    vertices.push(v);
+                    placed.add(v.id);
+                }
+                else
+                    left.push(v);
+            }
+            // A cycle or a dangling parent: write the rest as they are rather than drop them.
+            if (left.length === todo.length) {
+                vertices.push(...left);
+                break;
+            }
+            todo = left;
+        }
+    }
     const cells = [];
     for (const v of vertices) {
         const b = v.box;
@@ -188,6 +312,7 @@ export function serialize(scene) {
         const geom = e.geomRaw ??
             `<mxGeometry ${e.labelX ? `x="${e.labelX.toFixed(3)}" ` : ''}relative="1" as="geometry">` +
                 (e.points?.length ? `<Array as="points">${e.points.map((p) => `<mxPoint x="${r(p.x)}" y="${r(p.y)}"/>`).join('')}</Array>` : '') +
+                (e.labelOffset ? `<mxPoint x="${r(e.labelOffset.x)}" y="${r(e.labelOffset.y)}" as="offset"/>` : '') +
                 `</mxGeometry>`;
         cells.push(`<object id="${xmlEsc(e.id)}"${attrString({ label: '', ...e.attrs })}>` +
             `<mxCell style="${xmlEsc(e.style)}" edge="1" parent="${xmlEsc(e.parent)}"` +
@@ -209,16 +334,21 @@ export function toMxfile(d, l) {
  * source node, which reads as a caption of that node. Returns draw.io's -1..1
  * fraction, or undefined when no run is long enough.
  */
-function labelSpot(pts, label) {
+function labelSpot(pts, label, dir) {
     let total = 0;
     let best;
+    // Runs along the flow belong to one edge; runs across it are often shared
+    // corridors where several edges' labels would stack up. Prefer the former.
+    const flowVertical = dir === 'TB' || dir === 'BT';
     for (let i = 0; i < pts.length - 1; i++) {
         const a = pts[i], b = pts[i + 1];
         const len = Math.hypot(b.x - a.x, b.y - a.y);
         const vertical = Math.abs(b.x - a.x) < Math.abs(b.y - a.y);
         const room = len - (vertical ? label.h : label.w) - 20;
-        if (room >= 0 && (!best || room > best.room))
-            best = { room, at: total + len / 2 };
+        const along = dir ? vertical === flowVertical : true;
+        const better = !best || (along && !best.along) || (along === best.along && room > best.room);
+        if (room >= 0 && better)
+            best = { room, at: total + len / 2, along };
         total += len;
     }
     return best && total ? (best.at / total) * 2 - 1 : undefined;