@bpmnkit/ascii 0.0.12 → 0.0.13

package/dist/edges.d.ts

@@ -1,4 +1,22 @@
 import type { AsciiGrid } from "./grid.js";
+/**
+ * Draw an edge using explicit source/target port sides.
+ *
+ * srcPort — which side the edge exits the source element:
+ *   "right"  → standard horizontal exit (srcCol = first col after right border, srcRow = midRow)
+ *   "top"    → exits the top of source   (srcCol = midCol, srcRow = midRow)
+ *   "bottom" → exits the bottom of source (srcCol = midCol, srcRow = midRow)
+ *
+ * dstPort — which side the edge enters the target element:
+ *   "left"   → standard horizontal entry (dstCol = left border col, dstRow = midRow)
+ *   "top"    → enters the top of target   (dstCol = midCol, dstRow = midRow)
+ *   "bottom" → enters the bottom of target (dstCol = midCol, dstRow = midRow)
+ *
+ * For top/bottom ports the element's middle row (midRow) is passed as srcRow/dstRow;
+ * this function offsets by ±2 to reach the actual visible exit/entry row (one row
+ * outside the 3-row element box).
+ */
+export declare function drawPortedEdge(grid: AsciiGrid, srcCol: number, srcRow: number, srcPort: "right" | "top" | "bottom", dstCol: number, dstRow: number, dstPort: "left" | "top" | "bottom", label?: string): void;
 /**
  * Draw an orthogonal sequence-flow edge from a source exit point to a target
  * entry point, with an optional short label floated above the edge mid-point.

package/dist/edges.js

@@ -1,4 +1,131 @@
 import { truncate } from "./util.js";
+/**
+ * Draw an edge using explicit source/target port sides.
+ *
+ * srcPort — which side the edge exits the source element:
+ *   "right"  → standard horizontal exit (srcCol = first col after right border, srcRow = midRow)
+ *   "top"    → exits the top of source   (srcCol = midCol, srcRow = midRow)
+ *   "bottom" → exits the bottom of source (srcCol = midCol, srcRow = midRow)
+ *
+ * dstPort — which side the edge enters the target element:
+ *   "left"   → standard horizontal entry (dstCol = left border col, dstRow = midRow)
+ *   "top"    → enters the top of target   (dstCol = midCol, dstRow = midRow)
+ *   "bottom" → enters the bottom of target (dstCol = midCol, dstRow = midRow)
+ *
+ * For top/bottom ports the element's middle row (midRow) is passed as srcRow/dstRow;
+ * this function offsets by ±2 to reach the actual visible exit/entry row (one row
+ * outside the 3-row element box).
+ */
+export function drawPortedEdge(grid, srcCol, srcRow, srcPort, dstCol, dstRow, dstPort, label) {
+    if (srcPort === "right" && dstPort === "left") {
+        drawEdge(grid, srcCol, srcRow, dstCol, dstRow, label);
+        return;
+    }
+    // top exit → left entry
+    if (srcPort === "top" && dstPort === "left") {
+        if (srcRow > dstRow) {
+            // Target is ABOVE: go up from gateway top to target row, corner, then right
+            grid.setLine(srcCol, dstRow, "┌");
+            for (let r = dstRow + 1; r < srcRow - 1; r++)
+                grid.setLine(srcCol, r, "│");
+            drawHorizontalSegment(grid, srcCol + 1, dstCol - 2, dstRow);
+            grid.set(dstCol - 1, dstRow, "►");
+            if (label) {
+                const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+                grid.write(mid, dstRow - 1, truncate(label, dstCol - srcCol));
+            }
+        }
+        else {
+            // Target is at same row or below: route ABOVE the diagram via routeRow=1,
+            // then descend to target row.  Path: up↑ at srcCol → right→ at routeRow → down↓ at dstCol-1 → ►
+            const routeRow = 1;
+            grid.setLine(srcCol, routeRow, "└"); // ↑ meets →
+            for (let r = routeRow + 1; r < srcRow - 1; r++)
+                grid.setLine(srcCol, r, "│");
+            drawHorizontalSegment(grid, srcCol + 1, dstCol - 2, routeRow);
+            grid.setLine(dstCol - 1, routeRow, "┐"); // ← meets ↓
+            for (let r = routeRow + 1; r < dstRow; r++)
+                grid.setLine(dstCol - 1, r, "│");
+            grid.set(dstCol - 1, dstRow, "►");
+            if (label) {
+                const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+                grid.write(mid, routeRow - 1, truncate(label, dstCol - srcCol));
+            }
+        }
+        return;
+    }
+    // bottom exit → left entry
+    if (srcPort === "bottom" && dstPort === "left") {
+        if (srcRow < dstRow) {
+            // Target is BELOW: go down from gateway bottom to target row, corner, then right
+            grid.setLine(srcCol, dstRow, "└");
+            for (let r = srcRow + 2; r < dstRow; r++)
+                grid.setLine(srcCol, r, "│");
+            drawHorizontalSegment(grid, srcCol + 1, dstCol - 2, dstRow);
+            grid.set(dstCol - 1, dstRow, "►");
+            if (label) {
+                const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+                grid.write(mid, dstRow - 1, truncate(label, dstCol - srcCol));
+            }
+        }
+        else {
+            // Target is at same row or above: route BELOW the diagram, then ascend to target row.
+            // Path: down↓ at srcCol → right→ at routeRow → up↑ at dstCol-1 → ►
+            const routeRow = grid.rows - 2;
+            grid.setLine(srcCol, routeRow, "┌"); // ↓ meets →
+            for (let r = srcRow + 2; r < routeRow; r++)
+                grid.setLine(srcCol, r, "│");
+            drawHorizontalSegment(grid, srcCol + 1, dstCol - 2, routeRow);
+            grid.setLine(dstCol - 1, routeRow, "┘"); // ← meets ↑
+            for (let r = dstRow + 1; r < routeRow; r++)
+                grid.setLine(dstCol - 1, r, "│");
+            grid.set(dstCol - 1, dstRow, "►");
+            if (label) {
+                const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+                grid.write(mid, routeRow + 1, truncate(label, dstCol - srcCol));
+            }
+        }
+        return;
+    }
+    // right exit → top entry: horizontal right to target center-col, then vertical DOWN to target top
+    if (srcPort === "right" && dstPort === "top") {
+        if (srcRow >= dstRow) {
+            drawEdge(grid, srcCol, srcRow, dstCol, dstRow, label);
+            return;
+        }
+        // Corner at (dstCol, srcRow): connecting left (← from src) and down (↓ to dst top)
+        drawHorizontalSegment(grid, srcCol, dstCol - 1, srcRow);
+        grid.setLine(dstCol, srcRow, "┐");
+        for (let r = srcRow + 1; r < dstRow - 2; r++)
+            grid.setLine(dstCol, r, "│");
+        grid.set(dstCol, dstRow - 2, "▼");
+        if (label) {
+            const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+            grid.write(mid, srcRow - 1, truncate(label, dstCol - srcCol));
+        }
+        return;
+    }
+    // right exit → bottom entry: horizontal right to target center-col, then vertical UP to target bottom
+    if (srcPort === "right" && dstPort === "bottom") {
+        if (srcRow <= dstRow) {
+            drawEdge(grid, srcCol, srcRow, dstCol, dstRow, label);
+            return;
+        }
+        // Corner at (dstCol, srcRow): connecting left (← from src) and up (↑ to dst bottom)
+        drawHorizontalSegment(grid, srcCol, dstCol - 1, srcRow);
+        grid.setLine(dstCol, srcRow, "┘");
+        for (let r = dstRow + 3; r < srcRow; r++)
+            grid.setLine(dstCol, r, "│");
+        grid.set(dstCol, dstRow + 2, "▲");
+        if (label) {
+            const mid = Math.floor((srcCol + dstCol) / 2) - Math.floor(label.length / 2);
+            grid.write(mid, srcRow - 1, truncate(label, dstCol - srcCol));
+        }
+        return;
+    }
+    // Fallback for any other combination
+    drawEdge(grid, srcCol, srcRow, dstCol, dstRow, label);
+}
 /**
  * Draw an orthogonal sequence-flow edge from a source exit point to a target
  * entry point, with an optional short label floated above the edge mid-point.

package/dist/grid.js

@@ -75,9 +75,9 @@ export function mergeBoxChars(existing, next) {
     if (existing === " " || existing === next)
         return next;
     // Arrows always win
-    if (next === "►" || next === "▼")
+    if (next === "►" || next === "▼" || next === "▲")
         return next;
-    if (existing === "►" || existing === "▼")
+    if (existing === "►" || existing === "▼" || existing === "▲")
         return existing;
     const eDirs = CHAR_DIRS[existing];
     const nDirs = CHAR_DIRS[next];

package/dist/render.js

@@ -1,7 +1,30 @@
-import { Bpmn, layoutFlowNodes } from "@bpmnkit/core";
-import { drawEdge } from "./edges.js";
+import { Bpmn, GRID_CELL_HEIGHT, layoutFlowNodes } from "@bpmnkit/core";
+import { drawPortedEdge } from "./edges.js";
 import { AsciiGrid } from "./grid.js";
-import { CELL_H, CELL_W, drawElement, entryCol, exitCol, midRow } from "./shapes.js";
+import { CELL_H, CELL_W, drawElement, entryCol, exitCol, midCol } from "./shapes.js";
+/**
+ * Convert a node's pixel bounds to its ASCII mid-row (the middle of its 3-row box).
+ *
+ * The layout engine centers each element vertically within a GRID_CELL_HEIGHT-pixel
+ * tall cell.  By recovering the cell's y-offset we get a stable ascii row index
+ * regardless of element type, and the centering applied by `centerLayersVertically`
+ * is preserved (e.g. a join node after 3 parallel branches appears in the middle).
+ */
+function nodeMidRow(node) {
+    // Recover the cell's top y (element is centred inside its cell)
+    const cellY = node.bounds.y + node.bounds.height / 2 - GRID_CELL_HEIGHT / 2;
+    // Scale from pixel rows to ASCII rows (CELL_H ascii rows per GRID_CELL_HEIGHT pixels)
+    const asciiCellRow = Math.round((cellY / GRID_CELL_HEIGHT) * CELL_H);
+    // midRow = cell top + vertical padding + 1 (same formula as the old elemRow+1)
+    return asciiCellRow + Math.floor((CELL_H - 3) / 2) + 1;
+}
+const GATEWAY_TYPES = new Set([
+    "exclusiveGateway",
+    "parallelGateway",
+    "inclusiveGateway",
+    "eventBasedGateway",
+    "complexGateway",
+]);
 /**
  * Render a BPMN XML string as a Unicode box-drawing ASCII diagram.
  *
@@ -15,33 +38,36 @@ export function renderBpmnAscii(xml, options) {
     if (!process)
         return "(empty)";
     // Use layoutFlowNodes directly to skip the overlap assertion — the ASCII renderer
-    // uses layer/position indices (not pixel coords) so pixel-level overlaps are harmless.
+    // re-scales pixel coords to character rows so pixel-level overlaps are harmless.
     const layout = layoutFlowNodes(process.flowElements, process.sequenceFlows);
     const { nodes, edges } = layout;
     if (nodes.length === 0)
         return "(empty)";
-    // Compute grid dimensions from the layout's layer/position extents
+    // Compute grid dimensions from the layout's layer extents and pixel bounds
     const maxLayer = Math.max(...nodes.map((n) => n.layer));
-    const maxPos = Math.max(...nodes.map((n) => n.position));
-    // +2 padding on each axis, +1 because layers/positions are 0-indexed
+    const maxMidRow = Math.max(...nodes.map(nodeMidRow));
     const gridCols = (maxLayer + 1) * CELL_W + 4;
-    const gridRows = (maxPos + 1) * CELL_H + 4;
+    // Element bottom is at maxMidRow+1; leave CELL_H rows of padding below.
+    const gridRows = maxMidRow + CELL_H + 1;
     const grid = new AsciiGrid(gridCols, gridRows);
     // Build an id → node map for O(1) edge-endpoint look-up
     const nodeById = new Map();
     for (const node of nodes)
         nodeById.set(node.id, node);
+    // Pre-compute port assignments for all edges
+    const ports = computeEdgePorts(edges, nodeById);
     // Draw edges first so that shapes render on top of any edge overlap
     for (const edge of edges) {
         const src = nodeById.get(edge.sourceRef);
         const dst = nodeById.get(edge.targetRef);
         if (!src || !dst)
             continue;
-        drawEdge(grid, exitCol(src.type, src.layer), midRow(src.position), entryCol(dst.type, dst.layer), midRow(dst.position));
+        const { srcPort, dstPort } = ports.get(edge.id) ?? { srcPort: "right", dstPort: "left" };
+        drawPortedEdge(grid, srcPort === "right" ? exitCol(src.type, src.layer) : midCol(src.type, src.layer), nodeMidRow(src), srcPort, dstPort === "left" ? entryCol(dst.type, dst.layer) : midCol(dst.type, dst.layer), nodeMidRow(dst), dstPort, edge.label);
     }
     // Draw element boxes on top
     for (const node of nodes) {
-        drawElement(grid, node.type, node.layer, node.position, node.label);
+        drawElement(grid, node.type, node.layer, nodeMidRow(node) - 1, node.label);
     }
     const diagram = grid.toString();
     // Optional title header
@@ -59,4 +85,90 @@ function resolveTitle(options, processName) {
         return options.title;
     return processName ?? undefined;
 }
+/**
+ * Assign source and target ports for every edge.
+ *
+ * Source ports for gateway outgoing edges:
+ *   N=1 → right
+ *   N=2 → top, bottom
+ *   N=3 → top, right (middle by target row), bottom
+ *   N=4 → top, top, bottom, bottom
+ *   N=5 → top, top, right, bottom, bottom  …and so on.
+ *
+ * Target ports are derived from the source port and relative positions:
+ *   srcPort=top/bottom  → dstPort=left  (edge routes vertical then horizontal)
+ *   srcPort=right, dst is gateway:
+ *     source above dst → dstPort=top
+ *     source below dst → dstPort=bottom
+ *     same row         → dstPort=left
+ *   all other targets  → dstPort=left
+ */
+function computeEdgePorts(edges, nodeById) {
+    // ── Step 1: assign source ports ──────────────────────────────────────────
+    const srcPorts = new Map();
+    // Collect forward gateway edges grouped by source
+    const bySource = new Map();
+    for (const edge of edges) {
+        const src = nodeById.get(edge.sourceRef);
+        const dst = nodeById.get(edge.targetRef);
+        // Back-edges (dst layer ≤ src layer) and non-gateway sources always exit right
+        if (!src || !dst || !GATEWAY_TYPES.has(src.type) || dst.layer <= src.layer) {
+            srcPorts.set(edge.id, "right");
+            continue;
+        }
+        const arr = bySource.get(edge.sourceRef) ?? [];
+        arr.push(edge);
+        bySource.set(edge.sourceRef, arr);
+    }
+    for (const [, outgoing] of bySource) {
+        const n = outgoing.length;
+        if (n === 1) {
+            // biome-ignore lint/style/noNonNullAssertion: length=1 guarantees element
+            srcPorts.set(outgoing[0].id, "right");
+            continue;
+        }
+        // Sort outgoing edges by their target's row position (ascending = topmost first)
+        const sorted = [...outgoing].sort((a, b) => {
+            const pa = nodeById.get(a.targetRef)?.position ?? 0;
+            const pb = nodeById.get(b.targetRef)?.position ?? 0;
+            return pa - pb;
+        });
+        for (let i = 0; i < sorted.length; i++) {
+            // biome-ignore lint/style/noNonNullAssertion: loop bounds guarantee element
+            const edge = sorted[i];
+            let port;
+            if (n % 2 === 1) {
+                // Odd: middle index → right, above → top, below → bottom
+                const mid = Math.floor(n / 2);
+                port = i < mid ? "top" : i === mid ? "right" : "bottom";
+            }
+            else {
+                // Even: upper half → top, lower half → bottom (no right port)
+                port = i < n / 2 ? "top" : "bottom";
+            }
+            srcPorts.set(edge.id, port);
+        }
+    }
+    // ── Step 2: assign target ports ──────────────────────────────────────────
+    const result = new Map();
+    for (const edge of edges) {
+        const srcPort = srcPorts.get(edge.id) ?? "right";
+        let dstPort = "left";
+        // Top/bottom source ports route vertical-then-horizontal → always left entry.
+        // Right source port into a gateway: entry side depends on relative row.
+        if (srcPort === "right") {
+            const src = nodeById.get(edge.sourceRef);
+            const dst = nodeById.get(edge.targetRef);
+            if (src && dst && GATEWAY_TYPES.has(dst.type)) {
+                if (src.position < dst.position)
+                    dstPort = "top";
+                else if (src.position > dst.position)
+                    dstPort = "bottom";
+                // else same row → left (default)
+            }
+        }
+        result.set(edge.id, { srcPort, dstPort });
+    }
+    return result;
+}
 //# sourceMappingURL=render.js.map

package/dist/shapes.d.ts

@@ -20,6 +20,8 @@ export declare const CELL_H = 8;
 export declare function elemCol(type: string, layer: number): number;
 /** Top-left row of a task or event element within its cell (3 rows tall). */
 export declare function elemRow(position: number): number;
+/** Column of the horizontal center of an element (for top/bottom connections). */
+export declare function midCol(type: string, layer: number): number;
 /**
  * Column of the right exit connection point (first column AFTER the element's
  * right border — where an outgoing edge begins).
@@ -32,6 +34,10 @@ export declare function exitCol(type: string, layer: number): number;
 export declare function entryCol(type: string, layer: number): number;
 /** Row of the horizontal mid-point (used as the connection row for edges). */
 export declare function midRow(position: number): number;
-/** Draw any BPMN element onto the grid at its logical (layer, position). */
-export declare function drawElement(grid: AsciiGrid, type: string, layer: number, position: number, label: string | undefined): void;
+/**
+ * Draw any BPMN element onto the grid.
+ *
+ * @param row - The top row of the 3-row element box (pre-computed by the caller).
+ */
+export declare function drawElement(grid: AsciiGrid, type: string, layer: number, row: number, label: string | undefined): void;
 //# sourceMappingURL=shapes.d.ts.map

package/dist/shapes.js

@@ -118,6 +118,10 @@ export function elemRow(position) {
     // Centre the 3-row element vertically within the cell
     return position * CELL_H + Math.floor((CELL_H - 3) / 2);
 }
+/** Column of the horizontal center of an element (for top/bottom connections). */
+export function midCol(type, layer) {
+    return elemCol(type, layer) + Math.floor(elemW(type) / 2);
+}
 /**
  * Column of the right exit connection point (first column AFTER the element's
  * right border — where an outgoing edge begins).
@@ -137,18 +141,22 @@ export function midRow(position) {
     return elemRow(position) + 1; // middle of the 3-row element
 }
 // ── Drawing ─────────────────────────────────────────────────────────────────
-/** Draw any BPMN element onto the grid at its logical (layer, position). */
-export function drawElement(grid, type, layer, position, label) {
+/**
+ * Draw any BPMN element onto the grid.
+ *
+ * @param row - The top row of the 3-row element box (pre-computed by the caller).
+ */
+export function drawElement(grid, type, layer, row, label) {
     const col = elemCol(type, layer);
     const name = label ?? "";
     if (isTaskLike(type)) {
-        drawTaskBox(grid, col, elemRow(position), name, type);
+        drawTaskBox(grid, col, row, name, type);
     }
     else if (isGateway(type)) {
-        drawGatewayBox(grid, col, elemRow(position), name, elementMarker(type));
+        drawGatewayBox(grid, col, row, name, elementMarker(type));
     }
     else {
-        drawCompactBox(grid, col, elemRow(position), name, elementMarker(type));
+        drawCompactBox(grid, col, row, name, elementMarker(type));
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/ascii",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@bpmnkit/core": "0.0.12"
+    "@bpmnkit/core": "0.0.13"
   },
   "description": "Render BPMN diagrams as Unicode box-drawing ASCII art — perfect for terminals and docs",
   "keywords": [