@bpmnkit/core 0.1.1 → 0.1.2

package/dist/bpmn/auto-layout.js

@@ -1,4 +1,7 @@
 import { associationWaypoints, packAnnotations } from "../layout/annotations.js";
+import { alignPools } from "../layout/collaboration/alignment.js";
+import { orderPools } from "../layout/collaboration/ordering.js";
+import { collapseCollinear } from "../layout/grid/grid-router.js";
 import { layoutProcess } from "../layout/layout-engine.js";
 const POOL_HEADER = 30;
 const LANE_HEADER = 30;
@@ -166,10 +169,30 @@ function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, al
             : annLocalBounds.has(assoc.targetRef)
                 ? assoc.targetRef
                 : undefined;
+        // An association does not have to involve a text annotation — a data
+        // object may be associated with an activity. Both ends are placed, so
+        // the same docking works.
+        if (!annId) {
+            const source = nodeById.get(assoc.sourceRef);
+            const target = nodeById.get(assoc.targetRef);
+            if (!source || !target)
+                continue;
+            const { pElem, pAnn } = associationWaypoints(source.bounds, target.bounds);
+            allEdges.push({
+                id: `${assoc.id}_di`,
+                bpmnElement: assoc.id,
+                waypoints: [
+                    { x: Math.round(pElem.x + dx), y: Math.round(pElem.y + dy) },
+                    { x: Math.round(pAnn.x + dx), y: Math.round(pAnn.y + dy) },
+                ],
+                unknownAttributes: {},
+            });
+            continue;
+        }
         const elId = annId === assoc.sourceRef ? assoc.targetRef : assoc.sourceRef;
-        const annB = annId ? annLocalBounds.get(annId) : undefined;
+        const annB = annLocalBounds.get(annId);
         const elNode = nodeById.get(elId);
-        if (!annB || !annId || !elNode)
+        if (!annB || !elNode)
             continue;
         const { pElem, pAnn } = associationWaypoints(elNode.bounds, annB);
         // Shift into diagram space and honour the original sourceRef→targetRef order.
@@ -188,6 +211,246 @@ function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, al
         });
     }
 }
+const EMPTY_POOL_HEIGHT = 60;
+/** Sideways step when nudging a message flow out of a shape. */
+const MESSAGE_FLOW_STEP = 10;
+/** Stub a message flow leaves its element by before it may jog sideways. */
+const MESSAGE_FLOW_STEM = 20;
+/** Stagger between the stems of consecutive flows. */
+const MESSAGE_FLOW_STEM_STEP = 8;
+/** Step and reach of that sideways jog. */
+const MESSAGE_FLOW_JOG = 20;
+const MESSAGE_FLOW_MAX_JOG = 2400;
+const EMPTY_POOL_WIDTH = 300;
+/**
+ * Sub-processes the source diagram draws collapsed. A collapsed sub-process
+ * keeps its activity shape on the parent plane and carries its contents on a
+ * plane of its own, so the layout must not inline them.
+ *
+ * Either marker counts: an explicit `isExpanded="false"` on the shape, or the
+ * presence of a separate plane for that sub-process.
+ */
+function collapsedSubProcesses(defs) {
+    const containers = new Set();
+    const walk = (elements) => {
+        for (const el of elements) {
+            const sub = el;
+            if (sub.flowElements) {
+                containers.add(el.id);
+                walk(sub.flowElements);
+            }
+        }
+    };
+    for (const process of defs.processes)
+        walk(process.flowElements);
+    const collapsed = new Set();
+    for (const diagram of defs.diagrams) {
+        if (containers.has(diagram.plane.bpmnElement))
+            collapsed.add(diagram.plane.bpmnElement);
+        for (const shape of diagram.plane.shapes) {
+            if (shape.isExpanded === false && containers.has(shape.bpmnElement)) {
+                collapsed.add(shape.bpmnElement);
+            }
+        }
+    }
+    return collapsed;
+}
+/** One `BPMNDiagram` per collapsed sub-process, its contents laid out at the origin. */
+function childPlaneDiagrams(planes, defs, collapsed) {
+    const existing = new Map(defs.diagrams.map((d) => [d.plane.bpmnElement, d]));
+    const diagrams = [];
+    const emitted = new Set(planes.map((plane) => plane.elementId));
+    // A collapsed sub-process that holds nothing still owns its plane; dropping it
+    // would lose the drill-down target the source diagram declared.
+    for (const [elementId, diagram] of existing) {
+        if (!collapsed.has(elementId) || emitted.has(elementId))
+            continue;
+        diagrams.push({
+            id: diagram.id,
+            plane: { id: diagram.plane.id, bpmnElement: elementId, shapes: [], edges: [] },
+        });
+    }
+    for (const plane of planes) {
+        const { minX, minY } = contentBbox(plane.result.nodes);
+        if (!Number.isFinite(minX))
+            continue;
+        const dx = PADDING - minX;
+        const dy = PADDING - minY;
+        const previous = existing.get(plane.elementId);
+        diagrams.push({
+            id: previous?.id ?? `BPMNDiagram_${plane.elementId}`,
+            plane: {
+                id: previous?.plane.id ?? `BPMNPlane_${plane.elementId}`,
+                bpmnElement: plane.elementId,
+                shapes: plane.result.nodes.map((node) => nodeToShape(node, dx, dy)),
+                edges: plane.result.edges.map((edge) => edgeToShape(edge, dx, dy)),
+            },
+        });
+    }
+    return diagrams;
+}
+/** Vertical bands between pools — clear ground for a message flow to cross in. */
+function poolBands(shapes, participantIds) {
+    const pools = shapes
+        .filter((s) => participantIds.has(s.bpmnElement))
+        .map((s) => ({ top: s.bounds.y, bottom: s.bounds.y + s.bounds.height }))
+        .sort((a, b) => a.top - b.top);
+    const gaps = [];
+    for (let i = 0; i + 1 < pools.length; i++) {
+        const above = pools[i];
+        const below = pools[i + 1];
+        if (above && below && below.top > above.bottom) {
+            gaps.push({ top: above.bottom, bottom: below.top });
+        }
+    }
+    return gaps;
+}
+/** True when a vertical run at `x` between two heights would cross a shape. */
+function columnBlocked(x, fromY, toY, obstacles, own) {
+    const top = Math.min(fromY, toY);
+    const bottom = Math.max(fromY, toY);
+    return obstacles.some((o) => !own.includes(o) && o.x < x && x < o.x + o.width && o.y < bottom && top < o.y + o.height);
+}
+/**
+ * Shift a vertical run sideways until it misses every shape it would otherwise
+ * pass through. The run has to stay on the element it docks onto, so the search
+ * is bounded by that element's own width.
+ */
+function clearColumn(x, fromY, toY, obstacles, own, dock) {
+    if (!columnBlocked(x, fromY, toY, obstacles, own))
+        return x;
+    const limit = Math.floor(dock.width / 2);
+    for (let step = MESSAGE_FLOW_STEP; step <= limit; step += MESSAGE_FLOW_STEP) {
+        if (!columnBlocked(x + step, fromY, toY, obstacles, own))
+            return x + step;
+        if (!columnBlocked(x - step, fromY, toY, obstacles, own))
+            return x - step;
+    }
+    return x;
+}
+/**
+ * One vertical leg of a message flow, from its dock to the crossing band.
+ *
+ * A straight drop is used when the column is clear. Otherwise the leg leaves
+ * the element by a short stem and jogs sideways to a column that is clear for
+ * the rest of the descent — the same move a modeller makes by hand, and the
+ * only way past a shape sitting directly below the dock.
+ */
+function messageFlowLeg(dockX, fromY, toY, obstacles, own, dock, 
+/** Staggers the stem so two flows jogging side by side do not share a line. */
+stemOffset = 0) {
+    const straight = clearColumn(dockX, fromY, toY, obstacles, own, dock);
+    if (!columnBlocked(straight, fromY, toY, obstacles, own)) {
+        return {
+            points: [
+                { x: straight, y: fromY },
+                { x: straight, y: toY },
+            ],
+            blocked: false,
+        };
+    }
+    const down = toY > fromY;
+    const stem = MESSAGE_FLOW_STEM + stemOffset;
+    const stemY = down ? fromY + stem : fromY - stem;
+    const rowBlocked = (x) => obstacles.some((o) => !own.includes(o) &&
+        o.x < Math.max(dockX, x) &&
+        Math.min(dockX, x) < o.x + o.width &&
+        o.y < stemY &&
+        stemY < o.y + o.height);
+    for (let offset = MESSAGE_FLOW_JOG; offset <= MESSAGE_FLOW_MAX_JOG; offset += MESSAGE_FLOW_JOG) {
+        for (const candidate of [dockX + offset, dockX - offset]) {
+            if (rowBlocked(candidate))
+                continue;
+            if (columnBlocked(candidate, stemY, toY, obstacles, own))
+                continue;
+            return {
+                points: [
+                    { x: dockX, y: fromY },
+                    { x: dockX, y: stemY },
+                    { x: candidate, y: stemY },
+                    { x: candidate, y: toY },
+                ],
+                blocked: false,
+            };
+        }
+    }
+    return {
+        points: [
+            { x: straight, y: fromY },
+            { x: straight, y: toY },
+        ],
+        blocked: true,
+    };
+}
+/**
+ * Pick where a message flow crosses between pools and how each of its two legs
+ * gets there.
+ *
+ * Bands are tried nearest-first: the gaps between pools are clear ground, so a
+ * route that reaches one has nothing left to cross. Each leg is checked over
+ * its own stretch rather than the whole run, which is what lets a flow slip
+ * past shapes on the far side of the band.
+ */
+function messageFlowRoute(src, tgt, srcIsPool, tgtIsPool, gaps, obstacles, stemOffset, 
+/** Containers holding an endpoint: a route out of one has to cross it. */
+containers = []) {
+    const srcBelow = src.y + src.height / 2 > tgt.y + tgt.height / 2;
+    const sy = srcBelow ? src.y : src.y + src.height;
+    const ty = srcBelow ? tgt.y + tgt.height : tgt.y;
+    // The endpoints themselves, plus any expanded sub-process they sit inside:
+    // leaving an element means crossing the border of whatever contains it, so
+    // treating that border as an obstacle would leave the route no way out.
+    const own = [src, tgt, ...containers];
+    const midpoint = (sy + ty) / 2;
+    const low = Math.min(sy, ty);
+    const high = Math.max(sy, ty);
+    const build = (bandY) => {
+        const source = messageFlowLeg(Math.round(src.x + src.width / 2), sy, bandY, obstacles, own, src, stemOffset);
+        const target = messageFlowLeg(Math.round(tgt.x + tgt.width / 2), ty, bandY, obstacles, own, tgt, stemOffset);
+        // A pool has no position of its own to respect: dock it under whatever it
+        // is talking to, so the flow drops straight instead of fanning into the
+        // pool's centre along with every other flow.
+        if (tgtIsPool && !srcIsPool) {
+            const x = source.points[source.points.length - 1]?.x ?? 0;
+            return {
+                source: source.points,
+                target: [
+                    { x, y: ty },
+                    { x, y: bandY },
+                ],
+                blocked: source.blocked,
+            };
+        }
+        if (srcIsPool && !tgtIsPool) {
+            const x = target.points[target.points.length - 1]?.x ?? 0;
+            return {
+                source: [
+                    { x, y: sy },
+                    { x, y: bandY },
+                ],
+                target: target.points,
+                blocked: target.blocked,
+            };
+        }
+        return {
+            source: source.points,
+            target: target.points,
+            blocked: source.blocked || target.blocked,
+        };
+    };
+    const candidates = gaps
+        .map((gap, index) => ({ index, y: (gap.top + gap.bottom) / 2 }))
+        .filter((candidate) => candidate.y >= low && candidate.y <= high)
+        .sort((a, b) => Math.abs(a.y - midpoint) - Math.abs(b.y - midpoint));
+    for (const candidate of candidates) {
+        const route = build(candidate.y);
+        if (!route.blocked)
+            return { source: route.source, target: route.target, gap: candidate.index };
+    }
+    const fallback = candidates[0];
+    const route = build(fallback?.y ?? midpoint);
+    return { source: route.source, target: route.target, gap: fallback?.index ?? -1 };
+}
 /**
  * Apply auto-layout to all processes in a BpmnDefinitions, replacing the
  * diagram interchange (BPMNDi) with freshly computed positions.
@@ -195,7 +458,118 @@ function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, al
  * - Handles plain processes (no collaboration) and collaborations with pools.
  * - When pools have lanes, lane shapes are tiled vertically around the process content.
  */
-export function applyAutoLayout(defs) {
+/** Every element id in a collaboration mapped to the index of the pool holding it. */
+function poolOwners(defs, collab) {
+    const owners = new Map();
+    const processById = new Map(defs.processes.map((p) => [p.id, p]));
+    for (let index = 0; index < collab.participants.length; index++) {
+        const participant = collab.participants[index];
+        if (!participant)
+            continue;
+        owners.set(participant.id, index);
+        const process = participant.processRef ? processById.get(participant.processRef) : undefined;
+        if (!process)
+            continue;
+        const walk = (elements) => {
+            for (const element of elements) {
+                owners.set(element.id, index);
+                const container = element;
+                if (container.flowElements?.length)
+                    walk(container.flowElements);
+            }
+        };
+        walk(process.flowElements);
+    }
+    return owners;
+}
+/** Message flows collapsed into weighted pool-to-pool relationships. */
+function poolLinks(collab, owners) {
+    const weights = new Map();
+    for (const flow of collab.messageFlows) {
+        const from = owners.get(flow.sourceRef);
+        const to = owners.get(flow.targetRef);
+        if (from === undefined || to === undefined || from === to)
+            continue;
+        const key = from < to ? `${from}:${to}` : `${to}:${from}`;
+        const existing = weights.get(key);
+        if (existing)
+            existing.weight++;
+        else
+            weights.set(key, { from, to, weight: 1 });
+    }
+    return [...weights.values()];
+}
+/** Width of a laid-out process, ignoring where in space it happens to sit. */
+function contentWidth(layout) {
+    if (layout.nodes.length === 0)
+        return 0;
+    const { minX, maxX } = contentBbox(layout.nodes);
+    return maxX - minX;
+}
+/**
+ * Message flows expressed as the x centres of the two elements they connect,
+ * measured inside each pool's own content so alignment can shift pools freely.
+ */
+function messageLinks(collab, pools, layouts) {
+    if (!collab)
+        return [];
+    const centres = new Map();
+    for (let index = 0; index < pools.length; index++) {
+        const layout = layouts[index];
+        const pool = pools[index];
+        if (!layout || !pool?.participantId || layout.nodes.length === 0)
+            continue;
+        const { minX } = contentBbox(layout.nodes);
+        const hasLanes = (pool.process?.laneSet?.lanes.length ?? 0) > 0;
+        const elemX = POOL_HEADER + (hasLanes ? LANE_HEADER : 0) + PADDING;
+        for (const node of layout.nodes) {
+            centres.set(node.id, {
+                pool: index,
+                x: elemX + node.bounds.x + node.bounds.width / 2 - minX,
+            });
+        }
+    }
+    const links = [];
+    for (const flow of collab.messageFlows) {
+        const from = centres.get(flow.sourceRef);
+        const to = centres.get(flow.targetRef);
+        if (!from || !to || from.pool === to.pool)
+            continue;
+        links.push({ fromPool: from.pool, toPool: to.pool, fromX: from.x, toX: to.x });
+    }
+    return links;
+}
+/**
+ * Every element inside a collaboration mapped to the element that would contain
+ * it on a plane: its sub-process, or the participant of its process. Following
+ * the chain finds the nearest ancestor a collapsed scope leaves visible.
+ */
+function ancestorIndex(defs, collab) {
+    const parents = new Map();
+    const processById = new Map(defs.processes.map((p) => [p.id, p]));
+    for (const participant of collab.participants) {
+        const process = participant.processRef ? processById.get(participant.processRef) : undefined;
+        if (!process)
+            continue;
+        const walk = (elements, parent) => {
+            for (const element of elements) {
+                parents.set(element.id, parent);
+                const container = element;
+                if (container.flowElements?.length)
+                    walk(container.flowElements, element.id);
+            }
+        };
+        walk(process.flowElements, participant.id);
+    }
+    return parents;
+}
+/**
+ * Replace every diagram-interchange position in `defs` with a computed layout.
+ *
+ * @param engine - Which process layout algorithm to run. Defaults to `semantic`;
+ *   `grid` runs the older cell-grid walk and is used to compare the two.
+ */
+export function applyAutoLayout(defs, engine = "semantic") {
     if (defs.processes.length === 0)
         return defs;
     const collab = defs.collaborations[0];
@@ -209,39 +583,128 @@ export function applyAutoLayout(defs) {
     }
     const allShapes = [];
     const allEdges = [];
+    const childPlanes = [];
+    const collapsed = collapsedSubProcesses(defs);
     let poolY = 0;
-    for (const process of defs.processes) {
-        const participantId = processToParticipant.get(process.id);
-        const lanes = process.laneSet?.lanes ?? [];
+    // Walk the pools in declaration order so a black-box participant keeps its
+    // place in the stack; processes no participant references follow.
+    const processById = new Map(defs.processes.map((p) => [p.id, p]));
+    const pools = [];
+    if (collab) {
+        const participantPools = collab.participants.map((participant) => ({
+            participantId: participant.id,
+            process: participant.processRef ? processById.get(participant.processRef) : undefined,
+        }));
+        // Pools that exchange messages read better next to each other, so the
+        // stack follows the message flows rather than the declaration order.
+        const order = orderPools(participantPools.length, poolLinks(collab, poolOwners(defs, collab)));
+        for (const index of order) {
+            const pool = participantPools[index];
+            if (pool)
+                pools.push(pool);
+        }
+        for (const process of defs.processes) {
+            if (!processToParticipant.has(process.id))
+                pools.push({ process });
+        }
+    }
+    else {
+        for (const process of defs.processes)
+            pools.push({ process });
+    }
+    // Lay every pool out first: alignment needs to see all of them before any
+    // geometry is committed.
+    const layouts = pools.map((pool) => pool.process ? layoutProcess(pool.process, engine, collapsed) : { nodes: [], edges: [] });
+    const alignment = alignPools(pools.length, layouts.map((layout) => contentWidth(layout)), messageLinks(collab, pools, layouts));
+    /** Pools with nothing to draw; widened to match the others once all are placed. */
+    const blackBoxPools = [];
+    /** Root processes that are not the primary one, each on a plane of its own. */
+    const rootPlanes = [];
+    const primaryProcessId = defs.processes[0]?.id;
+    for (let poolIndex = 0; poolIndex < pools.length; poolIndex++) {
+        const pool = pools[poolIndex];
+        if (!pool)
+            continue;
+        const { participantId, process } = pool;
+        const lanes = process?.laneSet?.lanes ?? [];
         const hasLanes = lanes.length > 0;
-        const result = layoutProcess(process);
-        if (result.nodes.length === 0)
+        const result = layouts[poolIndex] ?? { nodes: [], edges: [] };
+        const alignDx = alignment[poolIndex] ?? 0;
+        // A participant with no process, or one whose process has no flow nodes,
+        // is a black box: it still needs a pool of its own to dock message flows
+        // onto, and to stay visible at all.
+        if (result.nodes.length === 0) {
+            // A process can be nothing but annotations; they still belong on the plane.
+            if (!participantId && process && process.textAnnotations.length > 0) {
+                const annOnly = packAnnotations(process, []);
+                const bbox = contentBbox([], annOnly.values());
+                addAnnotationShapes(process, [], annOnly, allShapes, allEdges, PADDING - bbox.minX, PADDING - bbox.minY);
+                continue;
+            }
+            if (participantId) {
+                const shape = {
+                    id: `${participantId}_di`,
+                    bpmnElement: participantId,
+                    isHorizontal: true,
+                    bounds: { x: 0, y: poolY, width: EMPTY_POOL_WIDTH, height: EMPTY_POOL_HEIGHT },
+                    unknownAttributes: {},
+                };
+                allShapes.push(shape);
+                blackBoxPools.push(shape);
+                poolY += EMPTY_POOL_HEIGHT + POOL_GAP;
+            }
             continue;
+        }
+        childPlanes.push(...(result.planes ?? []));
+        // The engine reports lane bands when it placed nodes by lane membership;
+        // they replace the proportional tiling below.
+        const engineLanes = result.lanes;
         // Pre-compute annotation positions in layout space so they're included in the bbox
-        const annBounds = packAnnotations(process, result.nodes);
+        const annBounds = process ? packAnnotations(process, result.nodes) : new Map();
         const { minX, minY, maxX, maxY } = contentBbox(result.nodes, annBounds.values());
         const contentW = maxX - minX;
         const contentH = maxY - minY;
+        // Engine lane bands already stack the content vertically, so the pool
+        // aligns to the band space rather than to the content bounding box —
+        // otherwise the shapes drift out of the lanes drawn around them.
+        const laneBands = participantId && hasLanes ? engineLanes : undefined;
+        const bandTop = laneBands?.[0]?.bounds.y ?? 0;
+        const bandHeight = laneBands ? laneBands.reduce((sum, lane) => sum + lane.bounds.height, 0) : 0;
         let dx;
         let dy;
         if (participantId) {
             const elemX = POOL_HEADER + (hasLanes ? LANE_HEADER : 0) + PADDING;
-            const elemY = poolY + PADDING;
-            dx = elemX - minX;
-            dy = elemY - minY;
+            dx = elemX - minX + alignDx;
+            dy = laneBands ? poolY - bandTop : poolY + PADDING - minY;
         }
         else {
             dx = PADDING - minX;
             dy = PADDING - minY;
         }
+        // Only the primary process shares the root plane; any other root process
+        // owns one, instead of being stacked on top of the first at the origin.
+        if (!participantId && process && process.id !== primaryProcessId) {
+            const shapes = [];
+            const edges = [];
+            for (const node of result.nodes)
+                shapes.push(nodeToShape(node, dx, dy));
+            for (const edge of result.edges)
+                edges.push(edgeToShape(edge, dx, dy));
+            addAnnotationShapes(process, result.nodes, annBounds, shapes, edges, dx, dy);
+            rootPlanes.push({ elementId: process.id, shapes, edges });
+            continue;
+        }
         for (const node of result.nodes)
             allShapes.push(nodeToShape(node, dx, dy));
         for (const edge of result.edges)
             allEdges.push(edgeToShape(edge, dx, dy));
-        addAnnotationShapes(process, result.nodes, annBounds, allShapes, allEdges, dx, dy);
+        if (process) {
+            addAnnotationShapes(process, result.nodes, annBounds, allShapes, allEdges, dx, dy);
+        }
         if (participantId) {
-            const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING;
-            const innerH = contentH + 2 * PADDING;
+            const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING + alignDx;
+            // Lanes must tile the pool exactly, so the pool takes their height.
+            const innerH = laneBands ? bandHeight : contentH + 2 * PADDING;
             const poolW = POOL_HEADER + innerW;
             allShapes.push({
                 id: `${participantId}_di`,
@@ -251,37 +714,117 @@ export function applyAutoLayout(defs) {
                 unknownAttributes: {},
             });
             if (hasLanes) {
-                const laneShapes = buildLaneShapes(lanes, result.nodes, dx, dy, poolY, POOL_HEADER, innerW, innerH);
+                const laneShapes = laneBands
+                    ? laneBands.map((lane) => ({
+                        id: `${lane.id}_di`,
+                        bpmnElement: lane.id,
+                        isHorizontal: true,
+                        bounds: {
+                            x: Math.round(POOL_HEADER),
+                            y: Math.round(lane.bounds.y + dy),
+                            width: Math.round(innerW),
+                            height: Math.round(lane.bounds.height),
+                        },
+                        unknownAttributes: {},
+                    }))
+                    : buildLaneShapes(lanes, result.nodes, dx, dy, poolY, POOL_HEADER, innerW, innerH);
                 allShapes.push(...laneShapes);
             }
             poolY += innerH + POOL_GAP;
         }
     }
+    // Give the black boxes the width of the widest pool that has content, so the
+    // stack reads as one diagram rather than a ragged column.
+    if (blackBoxPools.length > 0) {
+        const participantIds = new Set(collab?.participants.map((p) => p.id) ?? []);
+        const widest = allShapes
+            .filter((s) => participantIds.has(s.bpmnElement) && !blackBoxPools.includes(s))
+            .reduce((max, s) => Math.max(max, s.bounds.width), EMPTY_POOL_WIDTH);
+        for (const shape of blackBoxPools)
+            shape.bounds.width = widest;
+    }
     if (collab && collab.messageFlows.length > 0) {
         const shapeByElement = new Map(allShapes.map((s) => [s.bpmnElement, s.bounds]));
+        // An endpoint inside a collapsed sub-process has no shape on this plane;
+        // the message docks on the nearest ancestor that does.
+        const visibleAncestors = ancestorIndex(defs, collab);
+        const resolve = (id) => {
+            let current = id;
+            while (current !== undefined && !shapeByElement.has(current)) {
+                current = visibleAncestors.get(current);
+            }
+            return current ?? id;
+        };
+        const participantIds = new Set(collab.participants.map((p) => p.id));
+        const laneIds = new Set(defs.processes.flatMap((p) => (p.laneSet?.lanes ?? []).map((lane) => lane.id)));
+        // Pools and lanes are containers; message flows cross them by design. It is
+        // the elements inside that a route has to miss.
+        const obstacles = allShapes
+            .filter((s) => !participantIds.has(s.bpmnElement) && !laneIds.has(s.bpmnElement))
+            .map((s) => s.bounds);
+        const poolGaps = poolBands(allShapes, participantIds);
+        const runs = [];
+        /** Bounds of every expanded scope an element sits inside. */
+        const containersOf = (id) => {
+            const out = [];
+            let parent = visibleAncestors.get(id);
+            while (parent !== undefined) {
+                const bounds = shapeByElement.get(parent);
+                if (bounds)
+                    out.push(bounds);
+                parent = visibleAncestors.get(parent);
+            }
+            return out;
+        };
+        let stemOffset = 0;
         for (const mf of collab.messageFlows) {
-            const src = shapeByElement.get(mf.sourceRef);
-            const tgt = shapeByElement.get(mf.targetRef);
+            const sourceRef = resolve(mf.sourceRef);
+            const targetRef = resolve(mf.targetRef);
+            const src = shapeByElement.get(sourceRef);
+            const tgt = shapeByElement.get(targetRef);
             if (!src || !tgt)
                 continue;
-            const srcBelow = src.y + src.height / 2 > tgt.y + tgt.height / 2;
-            const sx = Math.round(src.x + src.width / 2);
-            const tx = Math.round(tgt.x + tgt.width / 2);
-            const sy = srcBelow ? src.y : src.y + src.height;
-            const ty = srcBelow ? tgt.y + tgt.height : tgt.y;
-            const midY = Math.round((sy + ty) / 2);
-            const waypoints = sx === tx
-                ? [
-                    { x: sx, y: sy },
-                    { x: tx, y: ty },
-                ]
-                : [
-                    { x: sx, y: sy },
-                    { x: sx, y: midY },
-                    { x: tx, y: midY },
-                    { x: tx, y: ty },
-                ];
-            allEdges.push({ id: `${mf.id}_di`, bpmnElement: mf.id, waypoints, unknownAttributes: {} });
+            const run = {
+                id: mf.id,
+                ...messageFlowRoute(src, tgt, participantIds.has(sourceRef), participantIds.has(targetRef), poolGaps, obstacles, stemOffset, [...containersOf(sourceRef), ...containersOf(targetRef)]),
+            };
+            runs.push(run);
+            stemOffset = (stemOffset + MESSAGE_FLOW_STEM_STEP) % (MESSAGE_FLOW_STEM_STEP * 4);
+        }
+        // Flows sharing a gap get their own line inside it, so parallel runs do not
+        // pile onto one row and cross every other flow's riser.
+        const perGap = new Map();
+        for (const run of runs) {
+            const list = perGap.get(run.gap);
+            if (list)
+                list.push(run);
+            else
+                perGap.set(run.gap, [run]);
+        }
+        const endX = (points) => points[points.length - 1]?.x ?? 0;
+        for (const [index, list] of perGap) {
+            const gap = poolGaps[index];
+            if (!gap)
+                continue;
+            list.sort((a, b) => Math.min(endX(a.source), endX(a.target)) - Math.min(endX(b.source), endX(b.target)));
+            for (let i = 0; i < list.length; i++) {
+                const run = list[i];
+                if (!run)
+                    continue;
+                // The gap is clear ground, so moving the crossing inside it cannot
+                // introduce a collision.
+                const y = Math.round(gap.top + ((i + 1) * (gap.bottom - gap.top)) / (list.length + 1));
+                const last = run.source[run.source.length - 1];
+                const lastTarget = run.target[run.target.length - 1];
+                if (last)
+                    last.y = y;
+                if (lastTarget)
+                    lastTarget.y = y;
+            }
+        }
+        for (const run of runs) {
+            const waypoints = collapseCollinear([...run.source, ...[...run.target].reverse()]);
+            allEdges.push({ id: `${run.id}_di`, bpmnElement: run.id, waypoints, unknownAttributes: {} });
         }
     }
     const planeBpmnElement = collab?.id ?? defs.processes[0]?.id ?? "plane";
@@ -298,6 +841,19 @@ export function applyAutoLayout(defs) {
                     edges: allEdges,
                 },
             },
+            ...rootPlanes.map((plane) => {
+                const previous = defs.diagrams.find((d) => d.plane.bpmnElement === plane.elementId);
+                return {
+                    id: previous?.id ?? `BPMNDiagram_${plane.elementId}`,
+                    plane: {
+                        id: previous?.plane.id ?? `BPMNPlane_${plane.elementId}`,
+                        bpmnElement: plane.elementId,
+                        shapes: plane.shapes,
+                        edges: plane.edges,
+                    },
+                };
+            }),
+            ...childPlaneDiagrams(childPlanes, defs, collapsed),
         ],
     };
 }