@bpmnkit/core 0.0.21 → 0.0.23

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.js

@@ -1,4 +1,6 @@
-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";
@@ -39,43 +41,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 +100,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/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

package/dist/layout/routing.js

@@ -5,11 +5,16 @@ const GATEWAY_TYPES = new Set([
     "inclusiveGateway",
     "eventBasedGateway",
 ]);
+/** Tolerance for treating two CY values as "same level" in port decisions. */
+const PORT_SAME_Y_TOLERANCE = 25;
 /**
  * Determine which side of the target a forward edge should connect to.
  * 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 function resolveTargetPort(source, target, joinGateways) {
     if (!GATEWAY_TYPES.has(target.type)) {
@@ -20,18 +25,23 @@ export function resolveTargetPort(source, target, joinGateways) {
         return "left";
     }
     // Join/closing gateways: connect based on relative position
+    if (source.gridRow !== undefined && target.gridRow !== undefined) {
+        if (source.gridRow === target.gridRow)
+            return "left";
+        return source.gridRow < target.gridRow ? "top" : "bottom";
+    }
+    // Fallback: pixel-Y comparison with tolerance
     const srcCy = source.bounds.y + source.bounds.height / 2;
     const tgtCy = target.bounds.y + target.bounds.height / 2;
-    if (Math.abs(srcCy - tgtCy) <= 1) {
+    if (Math.abs(srcCy - tgtCy) <= PORT_SAME_Y_TOLERANCE) {
         return "left";
     }
     return srcCy < tgtCy ? "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 function assignGatewayPorts(outgoingFlows, nodeMap) {
     const portMap = new Map();
@@ -44,39 +54,40 @@ export function assignGatewayPorts(outgoingFlows, nodeMap) {
             portMap.set(first.id, "right");
         return portMap;
     }
-    // Sort flows by target's center-y (ascending = topmost first)
-    const sorted = [...outgoingFlows].sort((a, b) => {
-        const targetA = nodeMap.get(a.targetRef);
-        const targetB = nodeMap.get(b.targetRef);
-        const yA = targetA ? targetA.bounds.y + targetA.bounds.height / 2 : 0;
-        const yB = targetB ? targetB.bounds.y + targetB.bounds.height / 2 : 0;
-        return yA - yB;
-    });
-    if (count % 2 === 1) {
-        const midIndex = Math.floor(count / 2);
-        for (let i = 0; i < sorted.length; i++) {
-            const flow = sorted[i];
-            if (!flow)
-                continue;
-            if (i < midIndex) {
-                portMap.set(flow.id, "top");
-            }
-            else if (i === midIndex) {
-                portMap.set(flow.id, "right");
-            }
-            else {
-                portMap.set(flow.id, "bottom");
-            }
+    const firstFlow = outgoingFlows[0];
+    if (!firstFlow)
+        return portMap;
+    const gateway = nodeMap.get(firstFlow.sourceRef);
+    if (!gateway)
+        return portMap;
+    const gatewayCY = gateway.bounds.y + gateway.bounds.height / 2;
+    const gatewayGridRow = gateway.gridRow;
+    for (const flow of outgoingFlows) {
+        const target = nodeMap.get(flow.targetRef);
+        if (!target)
+            continue;
+        let side;
+        if (gatewayGridRow !== undefined && target.gridRow !== undefined) {
+            // Exact integer row comparison — no tolerance needed
+            if (target.gridRow < gatewayGridRow)
+                side = "top";
+            else if (target.gridRow > gatewayGridRow)
+                side = "bottom";
+            else
+                side = "right";
         }
-    }
-    else {
-        const midIndex = count / 2;
-        for (let i = 0; i < sorted.length; i++) {
-            const flow = sorted[i];
-            if (!flow)
-                continue;
-            portMap.set(flow.id, i < midIndex ? "top" : "bottom");
+        else {
+            // Fallback: pixel-Y comparison with tolerance
+            const targetCY = target.bounds.y + target.bounds.height / 2;
+            const dy = targetCY - gatewayCY;
+            if (dy < -PORT_SAME_Y_TOLERANCE)
+                side = "top";
+            else if (dy > PORT_SAME_Y_TOLERANCE)
+                side = "bottom";
+            else
+                side = "right";
         }
+        portMap.set(flow.id, side);
     }
     return portMap;
 }
@@ -148,6 +159,8 @@ export function routeEdges(sequenceFlows, nodeMap, backEdges) {
             labelBounds: undefined,
         });
     }
+    // Resolve edges that cross through intermediate shapes
+    resolveEdgeCrossings(edges, nodeMap);
     // Collision-aware label placement
     placeEdgeLabels(edges, nodeMap);
     return edges;
@@ -187,39 +200,14 @@ function routeForwardEdge(source, target, joinGateways) {
         { x: targetLeft, y: targetCenterY },
     ];
 }
-/** Count the number of direction changes (bends) in a waypoint sequence. */
-function countBends(waypoints) {
-    let bends = 0;
-    for (let i = 1; i < waypoints.length - 1; i++) {
-        const prev = waypoints[i - 1];
-        const curr = waypoints[i];
-        const next = waypoints[i + 1];
-        if (!prev || !curr || !next)
-            continue;
-        const dx1 = curr.x - prev.x;
-        const dy1 = curr.y - prev.y;
-        const dx2 = next.x - curr.x;
-        const dy2 = next.y - curr.y;
-        // Direction changes when we go from horizontal to vertical or vice versa
-        if ((Math.abs(dx1) > 0.1 && Math.abs(dy2) > 0.1) ||
-            (Math.abs(dy1) > 0.1 && Math.abs(dx2) > 0.1)) {
-            bends++;
-        }
-    }
-    return bends;
-}
-/** Route a forward edge from a specific port side on the source node, choosing minimum bends. */
+/** Route a forward edge from a specific port side on the source node. */
 function routeFromPort(source, target, port, joinGateways) {
     if (port === "right") {
         return routeForwardEdge(source, target, joinGateways);
     }
-    // Generate candidate routes: assigned port route + right-port alternative
-    const portRoute = routeFromPortDirect(source, target, port, joinGateways);
-    const rightRoute = routeForwardEdge(source, target, joinGateways);
-    const portBends = countBends(portRoute);
-    const rightBends = countBends(rightRoute);
-    // Prefer the assigned port route unless right route has strictly fewer bends
-    return rightBends < portBends ? rightRoute : portRoute;
+    // top/bottom ports are assigned because the target is genuinely above/below —
+    // always honour the assigned side rather than falling back to right-exit.
+    return routeFromPortDirect(source, target, port, joinGateways);
 }
 /** Route directly from top/bottom port, preferring L-shaped path. */
 function routeFromPortDirect(source, target, port, joinGateways) {
@@ -260,6 +248,7 @@ function routeFromPortDirect(source, target, port, joinGateways) {
 }
 /**
  * Route a back-edge (loop) above or below all nodes, choosing the shorter path.
+ * Gateway targets are entered from the right (since back-edges come from the right).
  */
 function routeBackEdge(source, target, nodeMap) {
     let minY = Number.POSITIVE_INFINITY;
@@ -274,17 +263,20 @@ function routeBackEdge(source, target, nodeMap) {
     }
     const sourceRight = source.bounds.x + source.bounds.width;
     const sourceCenterY = source.bounds.y + source.bounds.height / 2;
-    const targetLeft = target.bounds.x;
     const targetCenterY = target.bounds.y + target.bounds.height / 2;
+    // Gateways: enter from right side; non-gateways: enter from left side
+    const enterRight = GATEWAY_TYPES.has(target.type);
+    const entryX = enterRight ? target.bounds.x + target.bounds.width : target.bounds.x;
+    const stemX = enterRight ? entryX + 20 : entryX - 20;
     // Route above
     const routeAboveY = minY - 30;
     const aboveRoute = [
         { x: sourceRight, y: sourceCenterY },
         { x: sourceRight + 20, y: sourceCenterY },
         { x: sourceRight + 20, y: routeAboveY },
-        { x: targetLeft - 20, y: routeAboveY },
-        { x: targetLeft - 20, y: targetCenterY },
-        { x: targetLeft, y: targetCenterY },
+        { x: stemX, y: routeAboveY },
+        { x: stemX, y: targetCenterY },
+        { x: entryX, y: targetCenterY },
     ];
     // Route below
     const routeBelowY = maxY + 30;
@@ -292,9 +284,9 @@ function routeBackEdge(source, target, nodeMap) {
         { x: sourceRight, y: sourceCenterY },
         { x: sourceRight + 20, y: sourceCenterY },
         { x: sourceRight + 20, y: routeBelowY },
-        { x: targetLeft - 20, y: routeBelowY },
-        { x: targetLeft - 20, y: targetCenterY },
-        { x: targetLeft, y: targetCenterY },
+        { x: stemX, y: routeBelowY },
+        { x: stemX, y: targetCenterY },
+        { x: entryX, y: targetCenterY },
     ];
     // Compare total path length and pick shorter
     const aboveLen = pathLength(aboveRoute);
@@ -312,6 +304,197 @@ function pathLength(waypoints) {
     }
     return len;
 }
+/**
+ * Post-process routed edges to avoid crossing through intermediate shapes.
+ * For each segment that passes through a shape, adds detour waypoints around it.
+ */
+export function resolveEdgeCrossings(edges, nodeMap) {
+    const margin = 20;
+    const allShapes = [];
+    for (const [id, node] of nodeMap) {
+        allShapes.push({
+            id,
+            x: node.bounds.x,
+            y: node.bounds.y,
+            right: node.bounds.x + node.bounds.width,
+            bottom: node.bounds.y + node.bounds.height,
+        });
+    }
+    for (const edge of edges) {
+        const obstacles = allShapes.filter((s) => s.id !== edge.sourceRef && s.id !== edge.targetRef);
+        // Pass 1: Detour around obstacles crossing segments
+        for (let pass = 0; pass < 5; pass++) {
+            const fixed = fixOneCrossing(edge.waypoints, obstacles, margin);
+            if (!fixed)
+                break;
+            edge.waypoints = collapseCollinear(fixed);
+        }
+        // Pass 2: Fix corner waypoints that ended up inside obstacles
+        edge.waypoints = fixCornersInsideObstacles(edge.waypoints, obstacles, margin);
+        edge.waypoints = collapseCollinear(edge.waypoints);
+    }
+}
+/**
+ * Find the first segment that crosses an obstacle and return a new waypoint
+ * array with a detour around it. Returns undefined if no crossing found.
+ */
+function fixOneCrossing(waypoints, obstacles, margin) {
+    for (let i = 0; i < waypoints.length - 1; i++) {
+        const p1 = waypoints[i];
+        const p2 = waypoints[i + 1];
+        const crossing = findCrossing(p1, p2, obstacles);
+        if (!crossing)
+            continue;
+        const detour = buildDetour(p1, p2, crossing, margin, obstacles);
+        if (!detour)
+            continue;
+        const result = [...waypoints.slice(0, i + 1), ...detour, ...waypoints.slice(i + 1)];
+        return result;
+    }
+    return undefined;
+}
+/** Find the first obstacle that a segment crosses through (not just touches). */
+function findCrossing(p1, p2, obstacles) {
+    const minX = Math.min(p1.x, p2.x);
+    const maxX = Math.max(p1.x, p2.x);
+    const minY = Math.min(p1.y, p2.y);
+    const maxY = Math.max(p1.y, p2.y);
+    const shrink = 3;
+    for (const obs of obstacles) {
+        if (maxX > obs.x + shrink &&
+            minX < obs.right - shrink &&
+            maxY > obs.y + shrink &&
+            minY < obs.bottom - shrink) {
+            return obs;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build detour waypoints to route around an obstacle.
+ * For vertical segments: detour horizontally (left or right).
+ * For horizontal segments: detour vertically (above or below).
+ */
+function buildDetour(p1, p2, obs, margin, allObs) {
+    const isVertical = Math.abs(p1.x - p2.x) < 1;
+    const isHorizontal = Math.abs(p1.y - p2.y) < 1;
+    if (isVertical) {
+        const x = p1.x;
+        const goingDown = p2.y > p1.y;
+        const beforeY = goingDown ? obs.y - margin : obs.bottom + margin;
+        const afterY = goingDown ? obs.bottom + margin : obs.y - margin;
+        // Try both sides; pick the one with fewer new crossings
+        const leftX = obs.x - margin;
+        const rightX = obs.right + margin;
+        const leftCross = countNewCrossings([
+            { x, y: beforeY },
+            { x: leftX, y: beforeY },
+            { x: leftX, y: afterY },
+            { x, y: afterY },
+        ], allObs);
+        const rightCross = countNewCrossings([
+            { x, y: beforeY },
+            { x: rightX, y: beforeY },
+            { x: rightX, y: afterY },
+            { x, y: afterY },
+        ], allObs);
+        const detourX = leftCross <= rightCross ? leftX : rightX;
+        return [
+            { x, y: beforeY },
+            { x: detourX, y: beforeY },
+            { x: detourX, y: afterY },
+            { x, y: afterY },
+        ];
+    }
+    if (isHorizontal) {
+        const y = p1.y;
+        const goingRight = p2.x > p1.x;
+        const beforeX = goingRight ? obs.x - margin : obs.right + margin;
+        const afterX = goingRight ? obs.right + margin : obs.x - margin;
+        const aboveY = obs.y - margin;
+        const belowY = obs.bottom + margin;
+        const aboveCross = countNewCrossings([
+            { x: beforeX, y },
+            { x: beforeX, y: aboveY },
+            { x: afterX, y: aboveY },
+            { x: afterX, y },
+        ], allObs);
+        const belowCross = countNewCrossings([
+            { x: beforeX, y },
+            { x: beforeX, y: belowY },
+            { x: afterX, y: belowY },
+            { x: afterX, y },
+        ], allObs);
+        const detourY = aboveCross <= belowCross ? aboveY : belowY;
+        return [
+            { x: beforeX, y },
+            { x: beforeX, y: detourY },
+            { x: afterX, y: detourY },
+            { x: afterX, y },
+        ];
+    }
+    // Diagonal segment — skip (shouldn't happen in orthogonal routing)
+    return undefined;
+}
+/** Count how many obstacles a set of consecutive segments would cross. */
+function countNewCrossings(points, obstacles) {
+    let count = 0;
+    for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i];
+        const b = points[i + 1];
+        if (findCrossing(a, b, obstacles))
+            count++;
+    }
+    return count;
+}
+/** Remove collinear intermediate waypoints (same X or same Y in a row). */
+function collapseCollinear(waypoints) {
+    if (waypoints.length <= 2)
+        return waypoints;
+    const result = [waypoints[0]];
+    for (let i = 1; i < waypoints.length - 1; i++) {
+        const prev = result[result.length - 1];
+        const curr = waypoints[i];
+        const next = waypoints[i + 1];
+        const sameX = Math.abs(prev.x - curr.x) < 0.5 && Math.abs(curr.x - next.x) < 0.5;
+        const sameY = Math.abs(prev.y - curr.y) < 0.5 && Math.abs(curr.y - next.y) < 0.5;
+        if (sameX || sameY)
+            continue;
+        result.push(curr);
+    }
+    result.push(waypoints[waypoints.length - 1]);
+    return result;
+}
+function isInsideRect(p, r) {
+    return p.x > r.x && p.x < r.right && p.y > r.y && p.y < r.bottom;
+}
+/**
+ * Fix corner waypoints that ended up inside obstacles after detours.
+ * Moves the corner below/above the obstacle while maintaining orthogonal routing.
+ */
+function fixCornersInsideObstacles(waypoints, obstacles, margin) {
+    const result = [...waypoints];
+    // Process backwards to maintain indices after splicing
+    for (let i = result.length - 2; i >= 1; i--) {
+        const wp = result[i];
+        const obs = obstacles.find((o) => isInsideRect(wp, o));
+        if (!obs)
+            continue;
+        const prev = result[i - 1];
+        const next = result[i + 1];
+        const isHorizToVert = Math.abs(prev.y - wp.y) < 1 && Math.abs(wp.x - next.x) < 1;
+        const isVertToHoriz = Math.abs(prev.x - wp.x) < 1 && Math.abs(wp.y - next.y) < 1;
+        if (isHorizToVert) {
+            const newY = next.y > wp.y ? obs.bottom + margin : obs.y - margin;
+            result.splice(i, 1, { x: prev.x, y: newY }, { x: wp.x, y: newY });
+        }
+        else if (isVertToHoriz) {
+            const newX = next.x > wp.x ? obs.right + margin : obs.x - margin;
+            result.splice(i, 1, { x: newX, y: prev.y }, { x: newX, y: wp.y });
+        }
+    }
+    return result;
+}
 /** Collision tolerance in pixels — small overlap allowed for rounding. */
 const LABEL_COLLISION_TOLERANCE = 2;
 /** Number of slide steps along a segment when searching for clear space. */

package/dist/layout/types.d.ts

@@ -38,6 +38,12 @@ export interface LayoutNode {
     layer: number;
     /** Position within the layer (row index). */
     position: number;
+    /**
+     * Grid row index assigned after all coordinate adjustments, just before routing.
+     * Nodes with the same gridRow are on the same horizontal row and connect left-to-right.
+     * Set by assignGridRows(); used by port-side decisions in routing.ts.
+     */
+    gridRow?: number;
     /** Label text for the node. */
     label?: string;
     /** Label bounds for overlap checking. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/core",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@bpmnkit/feel": "0.0.17"
+    "@bpmnkit/feel": "0.0.18"
   },
   "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
   "keywords": [
@@ -46,6 +46,7 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "check": "biome check .",
-    "test": "vitest run"
+    "test": "vitest run",
+    "format-bpmn": "node scripts/format-bpmn.mjs"
   }
 }