@bpmnkit/core 0.0.22 → 0.0.24

package/dist/layout/index.d.ts

@@ -1,6 +1,11 @@
 export { layoutProcess, layoutFlowNodes } from "./layout-engine.js";
+export { buildBlockTree } from "./block-builder.js";
+export type { FlowBlock, GatewayBlock, NodeBlock, SequenceBlock } from "./block-builder.js";
+export { applyBlockLayout } from "./block-layout.js";
+export { routeEdgeAstar } from "./astar.js";
 export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLayout, parseReferenceLayout, } from "./bench.js";
 export type { BenchmarkResult, BoundingBox, ElementComparison, ElementPosition, FlowOrderViolation, } from "./bench.js";
+export { assignGridRows } from "./coordinates.js";
 export { assertNoOverlap } from "./overlap.js";
 export type { Bounds, LayoutEdge, LayoutNode, LayoutResult, Waypoint } from "./types.js";
 export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH, HORIZONTAL_SPACING, LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, LABEL_VERTICAL_OFFSET, SUBPROCESS_PADDING, VERTICAL_SPACING, } from "./types.js";

package/dist/layout/index.js

@@ -1,5 +1,9 @@
 export { layoutProcess, layoutFlowNodes } from "./layout-engine.js";
+export { buildBlockTree } from "./block-builder.js";
+export { applyBlockLayout } from "./block-layout.js";
+export { routeEdgeAstar } from "./astar.js";
 export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLayout, parseReferenceLayout, } from "./bench.js";
+export { assignGridRows } from "./coordinates.js";
 export { assertNoOverlap } from "./overlap.js";
 export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH, HORIZONTAL_SPACING, LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, LABEL_VERTICAL_OFFSET, SUBPROCESS_PADDING, VERTICAL_SPACING, } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/layout/layout-engine.d.ts

@@ -10,7 +10,8 @@ import type { LayoutResult } from "./types.js";
  * 4. Coordinate assignment — Fixed element sizes with spacing
  * 5. Sub-process layout — Recursive nested passes
  * 6. Edge routing — Orthogonal waypoints
- * 7. Overlap assertion — Post-condition validation
+ * 7. Boundary event repositioning — place events on host border
+ * 8. Overlap assertion — Post-condition validation
  */
 export declare function layoutProcess(process: BpmnProcess): LayoutResult;
 /**

package/dist/layout/layout-engine.js

@@ -1,10 +1,139 @@
-import { alignBaselinePath, alignBranchBaselines, alignSplitJoinPairs, assignCoordinates, distributeSplitBranches, ensureEarlyReturnOffBaseline, resolveLayerOverlaps, } from "./coordinates.js";
+import { buildBlockTree } from "./block-builder.js";
+import { applyBlockLayout } from "./block-layout.js";
+import { alignBaselinePath, alignBranchBaselines, alignSplitJoinPairs, assignCoordinates, assignGridRows, compactBranches, distributeSplitBranches, ensureEarlyReturnOffBaseline, resolveLayerOverlaps, snapToYRows, } from "./coordinates.js";
 import { minimizeCrossings } from "./crossing.js";
 import { buildGraph, detectBackEdges, reverseBackEdges } from "./graph.js";
 import { assignLayers, groupByLayer } from "./layers.js";
 import { assertNoOverlap } from "./overlap.js";
 import { routeEdges } from "./routing.js";
 import { layoutSubProcesses } from "./subprocess.js";
+const CHAIN_GAP = 30;
+const CHAIN_V_GAP = 20;
+/**
+ * Reposition boundary events to the bottom edge of their host task, then walk
+ * each boundary event's exclusive downstream chain and place those nodes
+ * horizontally to the right of the host task. Re-routes all affected edges.
+ */
+function repositionBoundaryEvents(flowElements, result) {
+    const boundaryMap = new Map();
+    for (const el of flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        const list = boundaryMap.get(el.attachedToRef) ?? [];
+        list.push(el.id);
+        boundaryMap.set(el.attachedToRef, list);
+    }
+    if (boundaryMap.size === 0)
+        return;
+    const nodeById = new Map(result.nodes.map((n) => [n.id, n]));
+    const succIds = new Map();
+    const predIds = new Map();
+    for (const edge of result.edges) {
+        const se = succIds.get(edge.sourceRef) ?? [];
+        se.push(edge.targetRef);
+        succIds.set(edge.sourceRef, se);
+        const ps = predIds.get(edge.targetRef) ?? new Set();
+        ps.add(edge.sourceRef);
+        predIds.set(edge.targetRef, ps);
+    }
+    for (const [hostId, beIds] of boundaryMap) {
+        const hostNode = nodeById.get(hostId);
+        if (!hostNode)
+            continue;
+        for (let i = 0; i < beIds.length; i++) {
+            const beId = beIds[i];
+            if (!beId)
+                continue;
+            const beNode = nodeById.get(beId);
+            if (!beNode)
+                continue;
+            const bW = beNode.bounds.width;
+            const bH = beNode.bounds.height;
+            // Place boundary event on the bottom edge of the host task, stacking leftward
+            const rightEdge = hostNode.bounds.x + hostNode.bounds.width;
+            beNode.bounds.x = Math.round(rightEdge - bW / 2 - i * (bW + 4));
+            beNode.bounds.y = Math.round(hostNode.bounds.y + hostNode.bounds.height - bH / 2);
+            if (beNode.labelBounds) {
+                beNode.labelBounds.x = beNode.bounds.x + Math.round(bW / 2 - beNode.labelBounds.width / 2);
+                beNode.labelBounds.y = beNode.bounds.y + bH + 4;
+            }
+            // Collect nodes exclusively reachable from this boundary event (BFS)
+            const chainSet = new Set([beId]);
+            const chainOrder = [];
+            const queue = [...(succIds.get(beId) ?? [])];
+            while (queue.length > 0) {
+                const id = queue.shift();
+                if (!id || chainSet.has(id))
+                    continue;
+                const preds = predIds.get(id) ?? new Set();
+                if ([...preds].every((p) => chainSet.has(p))) {
+                    chainSet.add(id);
+                    chainOrder.push(id);
+                    queue.push(...(succIds.get(id) ?? []));
+                }
+            }
+            // Each boundary event's chain gets its own vertical lane
+            let maxChainH = 0;
+            for (const id of chainOrder) {
+                const n = nodeById.get(id);
+                if (n)
+                    maxChainH = Math.max(maxChainH, n.bounds.height);
+            }
+            const laneOffset = i * (maxChainH + CHAIN_V_GAP + 10);
+            const chainCenterY = Math.round(beNode.bounds.y + bH + CHAIN_V_GAP + maxChainH / 2 + laneOffset);
+            const chainStartX = Math.max(Math.round(beNode.bounds.x + bW / 2) + CHAIN_GAP, hostNode.bounds.x + hostNode.bounds.width + CHAIN_GAP);
+            let curX = chainStartX;
+            for (const id of chainOrder) {
+                const n = nodeById.get(id);
+                if (!n)
+                    continue;
+                n.bounds.x = curX;
+                n.bounds.y = chainCenterY - Math.round(n.bounds.height / 2);
+                if (n.labelBounds) {
+                    // Center label on node, but clamp so it never extends left of the node —
+                    // wide event labels would otherwise overlap the preceding chain element.
+                    const labelX = n.bounds.x + Math.round(n.bounds.width / 2 - n.labelBounds.width / 2);
+                    n.labelBounds.x = Math.max(labelX, n.bounds.x);
+                    n.labelBounds.y = n.bounds.y + n.bounds.height + 4;
+                }
+                // Advance past the node AND its label so the next element doesn't overlap.
+                const nodeRight = n.bounds.x + n.bounds.width;
+                const labelRight = n.labelBounds ? n.labelBounds.x + n.labelBounds.width : 0;
+                curX = Math.max(nodeRight, labelRight) + CHAIN_GAP;
+            }
+            // Re-route edges touching the boundary event or its chain
+            for (const edge of result.edges) {
+                if (!chainSet.has(edge.sourceRef))
+                    continue;
+                const src = nodeById.get(edge.sourceRef);
+                const tgt = nodeById.get(edge.targetRef);
+                if (!src || !tgt)
+                    continue;
+                if (edge.sourceRef === beId) {
+                    const srcX = Math.round(src.bounds.x + bW / 2);
+                    const srcY = Math.round(src.bounds.y + bH);
+                    const tgtX = Math.round(tgt.bounds.x);
+                    const tgtY = Math.round(tgt.bounds.y + tgt.bounds.height / 2);
+                    edge.waypoints = [
+                        { x: srcX, y: srcY },
+                        { x: srcX, y: tgtY },
+                        { x: tgtX, y: tgtY },
+                    ];
+                }
+                else {
+                    const srcX = Math.round(src.bounds.x + src.bounds.width);
+                    const srcY = Math.round(src.bounds.y + src.bounds.height / 2);
+                    const tgtX = Math.round(tgt.bounds.x);
+                    const tgtY = Math.round(tgt.bounds.y + tgt.bounds.height / 2);
+                    edge.waypoints = [
+                        { x: srcX, y: srcY },
+                        { x: tgtX, y: tgtY },
+                    ];
+                }
+            }
+        }
+    }
+}
 /**
  * Auto-layout a BPMN process using the Sugiyama/layered algorithm.
  *
@@ -15,10 +144,12 @@ import { layoutSubProcesses } from "./subprocess.js";
  * 4. Coordinate assignment — Fixed element sizes with spacing
  * 5. Sub-process layout — Recursive nested passes
  * 6. Edge routing — Orthogonal waypoints
- * 7. Overlap assertion — Post-condition validation
+ * 7. Boundary event repositioning — place events on host border
+ * 8. Overlap assertion — Post-condition validation
  */
 export function layoutProcess(process) {
     const result = layoutFlowNodes(process.flowElements, process.sequenceFlows);
+    repositionBoundaryEvents(process.flowElements, result);
     assertNoOverlap(result);
     return result;
 }
@@ -39,43 +170,46 @@ export function layoutFlowNodes(flowNodes, sequenceFlows) {
     const graph = buildGraph(flowNodes, sequenceFlows);
     const backEdges = detectBackEdges(graph, sequenceFlows);
     const dag = backEdges.length > 0 ? reverseBackEdges(graph, backEdges) : graph;
-    // Phase 2: Layer assignment
-    const layers = assignLayers(dag);
-    // Phase 3: Group by layer and minimize crossings
-    const layerGroups = groupByLayer(layers);
-    const orderedLayers = minimizeCrossings(layerGroups, dag);
-    // Phase 4: Coordinate assignment
-    const layoutNodes = assignCoordinates(orderedLayers, nodeIndex);
-    // Phase 4b: Align linear sequences to a common y-baseline
-    alignBranchBaselines(layoutNodes, dag);
-    // Phase 4c: Align split/join gateway pairs to same y-coordinate
-    alignSplitJoinPairs(layoutNodes, dag, backEdges);
-    // Phase 4d: Align all baseline-path nodes to the same center-Y
-    alignBaselinePath(layoutNodes, dag, backEdges);
-    // Phase 4e: Ensure early-return branches are never on the baseline
-    ensureEarlyReturnOffBaseline(layoutNodes, dag, backEdges);
-    // Phase 4f: Distribute split gateway branches symmetrically
-    distributeSplitBranches(layoutNodes, dag, backEdges);
-    // Phase 4g: Resolve any layer overlaps from redistribution
-    resolveLayerOverlaps(layoutNodes);
-    // Phase 4h: Re-align baseline after overlap resolution (overlap resolution may push
-    // baseline nodes off-center when they share a layer with branch nodes)
-    alignBaselinePath(layoutNodes, dag, backEdges);
-    // Phase 4i: Final overlap resolution — baseline re-alignment may pull a node back into
-    // an overlap that resolveLayerOverlaps already fixed; one more pass eliminates these.
-    resolveLayerOverlaps(layoutNodes);
+    // Phase 2: Try block-based layout (primary path for structured processes)
+    // Block layout only works well for processes without back-edges (loops).
+    let layoutNodes;
+    const blockTree = backEdges.length === 0 ? buildBlockTree(dag, nodeIndex) : null;
+    const usedBlockLayout = blockTree !== null;
+    if (blockTree) {
+        layoutNodes = applyBlockLayout(blockTree, nodeIndex);
+    }
+    else {
+        layoutNodes = sugiyamaLayout(dag, nodeIndex, backEdges);
+    }
     // Phase 5: Sub-process layout — expand containers and lay out children
     const childResults = layoutSubProcesses(layoutNodes, nodeIndex);
-    // After subprocess expansion, push nodes that now overlap with expanded containers
+    // After subprocess expansion, push nodes that now overlap with expanded containers.
+    // For block layout, assign unique layer indices first so resolveLayerOverlaps works
+    // correctly (block layout nodes all start at layer=0).
+    if (usedBlockLayout && childResults.length > 0) {
+        // Assign each block-layout node a unique layer so overlap resolution doesn't
+        // collapse them all into the same bucket and push them vertically apart.
+        for (let idx = 0; idx < layoutNodes.length; idx++) {
+            const n = layoutNodes[idx];
+            if (n)
+                n.layer = idx;
+        }
+    }
     resolveSubProcessOverlaps(layoutNodes);
     // Phase 5b: Resolve Y-direction overlaps caused by subprocess expansion.
     // Expanded subprocesses grow in-place and can overlap same-layer siblings.
-    resolveLayerOverlaps(layoutNodes);
+    // For block layout without subprocesses, skip this — overlaps are impossible by construction.
+    if (!usedBlockLayout || childResults.length > 0) {
+        resolveLayerOverlaps(layoutNodes);
+    }
     // Phase 5c: Sync child positions to their subprocess containers.
     // resolveLayerOverlaps (including its Y-normalization pass) may have shifted
     // subprocess containers after their children were already translated to
     // absolute coordinates — children must follow.
     syncSubProcessChildren(childResults, layoutNodes);
+    // Assign grid-row indices based on final center-Y positions (eliminates pixel-tolerance
+    // guessing in port-side decisions).
+    assignGridRows(layoutNodes);
     // Phase 6: Edge routing (uses original back-edges for routing, not reversed)
     const nodeMap = new Map();
     for (const node of layoutNodes) {
@@ -95,6 +229,52 @@ export function layoutFlowNodes(flowNodes, sequenceFlows) {
     }
     return { nodes: allNodes, edges: allEdges };
 }
+/**
+ * Run the Sugiyama layered layout pipeline.
+ * Used as fallback for unstructured or loop-containing processes.
+ */
+function sugiyamaLayout(dag, nodeIndex, backEdges) {
+    // Phase 2: Layer assignment
+    const layers = assignLayers(dag);
+    // Phase 3: Group by layer and minimize crossings
+    const layerGroups = groupByLayer(layers);
+    const orderedLayers = minimizeCrossings(layerGroups, dag);
+    // Phase 4: Coordinate assignment
+    const layoutNodes = assignCoordinates(orderedLayers, nodeIndex);
+    // Phase 4b: Align linear sequences to a common y-baseline
+    alignBranchBaselines(layoutNodes, dag);
+    // Phase 4c: Align split/join gateway pairs to same y-coordinate
+    alignSplitJoinPairs(layoutNodes, dag, backEdges);
+    // Phase 4d: Align all baseline-path nodes to the same center-Y
+    alignBaselinePath(layoutNodes, dag, backEdges);
+    // Phase 4e: Ensure early-return branches are never on the baseline
+    ensureEarlyReturnOffBaseline(layoutNodes, dag, backEdges);
+    // Re-align linear chains that may have been disrupted by position swaps
+    alignBranchBaselines(layoutNodes, dag);
+    // Phase 4f: Distribute split gateway branches symmetrically
+    distributeSplitBranches(layoutNodes, dag, backEdges);
+    // Re-align split/join pairs that may have been separated during branch distribution
+    alignSplitJoinPairs(layoutNodes, dag, backEdges);
+    // Re-align branch spines after distribution moved chains and alignSplitJoinPairs
+    // adjusted join gateways (continuation nodes after joins must follow)
+    alignBranchBaselines(layoutNodes, dag);
+    // Phase 4g: Resolve any layer overlaps from redistribution
+    resolveLayerOverlaps(layoutNodes);
+    // Phase 4h: Re-align baseline after overlap resolution (overlap resolution may push
+    // baseline nodes off-center when they share a layer with branch nodes)
+    alignBaselinePath(layoutNodes, dag, backEdges);
+    // Phase 4i: Final overlap resolution — baseline re-alignment may pull a node back into
+    // an overlap that resolveLayerOverlaps already fixed; one more pass eliminates these.
+    resolveLayerOverlaps(layoutNodes);
+    // Phase 4j: Branch compaction — pull branch subtrees toward baseline
+    compactBranches(layoutNodes, dag, backEdges);
+    resolveLayerOverlaps(layoutNodes);
+    alignBaselinePath(layoutNodes, dag, backEdges);
+    // Phase 4k: Row snapping — merge close Y rows for matrix-like alignment
+    snapToYRows(layoutNodes);
+    resolveLayerOverlaps(layoutNodes);
+    return layoutNodes;
+}
 /**
  * After subprocess expansion, cascade-shift all subsequent layers
  * so that inter-layer spacing is preserved.

package/dist/layout/overlap.js

@@ -8,6 +8,9 @@
 export function assertNoOverlap(result) {
     const allBounds = [];
     for (const node of result.nodes) {
+        // Boundary events intentionally overlap their host activity — skip them.
+        if (node.type === "boundaryEvent")
+            continue;
         allBounds.push({ id: node.id, kind: "element", bounds: node.bounds });
         if (node.labelBounds) {
             allBounds.push({ id: `${node.id}-label`, kind: "label", bounds: node.labelBounds });

package/dist/layout/routing.d.ts

@@ -8,13 +8,15 @@ export type PortSide = "right" | "top" | "bottom";
  * Non-gateway targets always receive edges from the left side.
  * Split gateways (starting): incoming always from the left.
  * Join gateways (closing): incoming based on relative position (top/bottom/left).
+ *
+ * Uses gridRow (integer row index) when available for exact comparison;
+ * falls back to pixel-Y with PORT_SAME_Y_TOLERANCE for nodes without gridRow.
  */
 export declare function resolveTargetPort(source: LayoutNode, target: LayoutNode, joinGateways: ReadonlySet<string>): "left" | "top" | "bottom";
 /**
  * Assign source ports for outgoing edges of a gateway.
- * - Single output: right port.
- * - Odd count: middle (by target y) → right, upper half → top, lower half → bottom.
- * - Even count: upper half → top, lower half → bottom, no right port.
+ * Uses absolute direction: target above → top, below → bottom, same level → right.
+ * Single output always exits from the right port.
  */
 export declare function assignGatewayPorts(outgoingFlows: BpmnSequenceFlow[], nodeMap: Map<string, LayoutNode>): Map<string, PortSide>;
 /**
@@ -23,4 +25,9 @@ export declare function assignGatewayPorts(outgoingFlows: BpmnSequenceFlow[], no
  * Gateway sources use port-based routing (top/right/bottom).
  */
 export declare function routeEdges(sequenceFlows: BpmnSequenceFlow[], nodeMap: Map<string, LayoutNode>, backEdges: BackEdge[]): LayoutEdge[];
+/**
+ * Post-process routed edges to avoid crossing through intermediate shapes.
+ * For each segment that passes through a shape, adds detour waypoints around it.
+ */
+export declare function resolveEdgeCrossings(edges: LayoutEdge[], nodeMap: Map<string, LayoutNode>): void;
 //# sourceMappingURL=routing.d.ts.map