sad-mcp 1.0.3 → 1.1.0

package/dist/bpmn/export-bpmn.d.ts

@@ -0,0 +1,8 @@
+import type { LaidOutModel } from "./types.js";
+export declare function buildBPMNXml(laid: LaidOutModel): string;
+export declare function safeFilename(m: {
+    title: {
+        he: string;
+        en?: string;
+    };
+}): string;

package/dist/bpmn/export-bpmn.js

@@ -0,0 +1,167 @@
+// Generates BPMN 2.0 XML (with DI section) server-side, using the
+// coordinates already computed by the layout pass. The VP export button
+// embedded in the HTML just triggers a download of this precomputed
+// string — no DOM walking, no getBBox() calls.
+//
+// Reference namespaces from OMG BPMN 2.0:
+//   bpmn   http://www.omg.org/spec/BPMN/20100524/MODEL
+//   bpmndi http://www.omg.org/spec/BPMN/20100524/DI
+//   dc     http://www.omg.org/spec/DD/20100524/DC
+//   di     http://www.omg.org/spec/DD/20100524/DI
+import { escapeXml } from "./svg.js";
+export function buildBPMNXml(laid) {
+    const m = laid.model;
+    const title = escapeXml(m.title.en || m.title.he || "process");
+    // Map pool id → process id (each pool gets its own process element)
+    const processIds = new Map();
+    m.pools.forEach((p, i) => processIds.set(p.id, `process_${i + 1}`));
+    const processLines = [];
+    const collabLines = [];
+    // Participants reference pool processes
+    for (const p of m.pools) {
+        const procId = processIds.get(p.id);
+        collabLines.push(`    <bpmn:participant id="${escapeXml(p.id)}" name="${escapeXml(p.name)}" processRef="${procId}"/>`);
+    }
+    for (const mf of m.messageFlows) {
+        const src = mf.fromElement ?? mf.fromPool;
+        const tgt = mf.toElement ?? mf.toPool;
+        const name = mf.label ? ` name="${escapeXml(mf.label)}"` : "";
+        collabLines.push(`    <bpmn:messageFlow id="${escapeXml(mf.id)}" sourceRef="${escapeXml(src)}" targetRef="${escapeXml(tgt)}"${name}/>`);
+    }
+    // One bpmn:process block per pool
+    const processBlocks = [];
+    for (const p of m.pools) {
+        const procId = processIds.get(p.id);
+        const poolElements = m.elements.filter((el) => {
+            if (el.kind === "task" || el.kind === "gateway" || el.kind === "event" || el.kind === "collapsedSubProcess") {
+                return el.pool === p.id;
+            }
+            return false;
+        });
+        const poolFlows = m.sequenceFlows.filter((f) => {
+            const src = m.elements.find((e) => e.id === f.from);
+            const tgt = m.elements.find((e) => e.id === f.to);
+            if (!src || !tgt)
+                return false;
+            const srcPool = src.pool;
+            const tgtPool = tgt.pool;
+            return srcPool === p.id && tgtPool === p.id;
+        });
+        // Lanes (if organization pool with lanes)
+        const laneSetLines = [];
+        if (p.lanes.length > 0) {
+            laneSetLines.push(`      <bpmn:laneSet id="${procId}_laneset">`);
+            for (const lane of p.lanes) {
+                const laneElements = poolElements.filter((e) => e.lane === lane.id);
+                laneSetLines.push(`        <bpmn:lane id="${escapeXml(lane.id)}" name="${escapeXml(lane.name)}">`);
+                for (const le of laneElements) {
+                    laneSetLines.push(`          <bpmn:flowNodeRef>${escapeXml(le.id)}</bpmn:flowNodeRef>`);
+                }
+                laneSetLines.push(`        </bpmn:lane>`);
+            }
+            laneSetLines.push(`      </bpmn:laneSet>`);
+        }
+        // Element lines
+        const elLines = [];
+        for (const el of poolElements) {
+            const id = escapeXml(el.id);
+            const name = escapeXml(el.name ?? "");
+            if (el.kind === "task") {
+                elLines.push(`      <bpmn:task id="${id}" name="${name}"/>`);
+            }
+            else if (el.kind === "collapsedSubProcess") {
+                elLines.push(`      <bpmn:subProcess id="${id}" name="${name}"/>`);
+            }
+            else if (el.kind === "gateway") {
+                const tag = el.gatewayType === "AND" ? "parallelGateway"
+                    : el.gatewayType === "OR" ? "inclusiveGateway"
+                        : "exclusiveGateway";
+                elLines.push(`      <bpmn:${tag} id="${id}" name="${name}"/>`);
+            }
+            else if (el.kind === "event") {
+                const tag = el.eventType === "start" ? "startEvent"
+                    : el.eventType === "end" ? "endEvent"
+                        : "intermediateCatchEvent";
+                elLines.push(`      <bpmn:${tag} id="${id}" name="${name}"/>`);
+            }
+        }
+        // Data stores and objects are declared at process level
+        for (const el of m.elements) {
+            if (el.kind === "dataStore") {
+                elLines.push(`      <bpmn:dataStoreReference id="${escapeXml(el.id)}" name="${escapeXml(el.name)}"/>`);
+            }
+            else if (el.kind === "dataObject") {
+                elLines.push(`      <bpmn:dataObjectReference id="${escapeXml(el.id)}" name="${escapeXml(el.name)}"/>`);
+            }
+        }
+        for (const f of poolFlows) {
+            const name = f.label ? ` name="${escapeXml(f.label)}"` : "";
+            elLines.push(`      <bpmn:sequenceFlow id="${escapeXml(f.id)}" sourceRef="${escapeXml(f.from)}" targetRef="${escapeXml(f.to)}"${name}/>`);
+        }
+        processBlocks.push(`  <bpmn:process id="${procId}" name="${escapeXml(p.name)}" isExecutable="false">
+${laneSetLines.join("\n")}
+${elLines.join("\n")}
+  </bpmn:process>`);
+    }
+    // DI section — harvest coords from layout
+    const diLines = [];
+    // Pool shapes
+    for (const p of laid.pools) {
+        diLines.push(`      <bpmndi:BPMNShape id="${escapeXml(p.poolId)}_di" bpmnElement="${escapeXml(p.poolId)}" isHorizontal="true">
+        <dc:Bounds x="${round(p.x)}" y="${round(p.y)}" width="${round(p.w)}" height="${round(p.h)}"/>
+      </bpmndi:BPMNShape>`);
+        for (const ln of p.lanes) {
+            if (!ln.laneId)
+                continue;
+            diLines.push(`      <bpmndi:BPMNShape id="${escapeXml(ln.laneId)}_di" bpmnElement="${escapeXml(ln.laneId)}" isHorizontal="true">
+        <dc:Bounds x="${round(ln.x)}" y="${round(ln.y)}" width="${round(ln.w)}" height="${round(ln.h)}"/>
+      </bpmndi:BPMNShape>`);
+        }
+    }
+    // Element shapes
+    for (const [id, pl] of laid.placements) {
+        diLines.push(`      <bpmndi:BPMNShape id="${escapeXml(id)}_di" bpmnElement="${escapeXml(id)}">
+        <dc:Bounds x="${round(pl.box.x)}" y="${round(pl.box.y)}" width="${round(pl.box.w)}" height="${round(pl.box.h)}"/>
+      </bpmndi:BPMNShape>`);
+    }
+    // Sequence flow edges
+    for (const r of laid.sequenceRoutes) {
+        const waypoints = r.points.map((p) => `        <di:waypoint x="${round(p.x)}" y="${round(p.y)}"/>`).join("\n");
+        diLines.push(`      <bpmndi:BPMNEdge id="${escapeXml(r.id)}_di" bpmnElement="${escapeXml(r.id)}">
+${waypoints}
+      </bpmndi:BPMNEdge>`);
+    }
+    for (const r of laid.messageRoutes) {
+        const waypoints = r.points.map((p) => `        <di:waypoint x="${round(p.x)}" y="${round(p.y)}"/>`).join("\n");
+        diLines.push(`      <bpmndi:BPMNEdge id="${escapeXml(r.id)}_di" bpmnElement="${escapeXml(r.id)}">
+${waypoints}
+      </bpmndi:BPMNEdge>`);
+    }
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+  xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
+  xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  id="Definitions_1" targetNamespace="http://bpmn.io/schema/bpmn">
+${processBlocks.join("\n")}
+  <bpmn:collaboration id="collab_1">
+${collabLines.join("\n")}
+  </bpmn:collaboration>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="collab_1">
+${diLines.join("\n")}
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>`;
+    return xml;
+}
+function round(n) { return Math.round(n); }
+// Returned for completeness — a caller may want the stable safe title
+export function safeFilename(m) {
+    const base = (m.title.en || m.title.he || "process")
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .replace(/\s+/g, "_")
+        .slice(0, 60);
+    return base || "process";
+}

package/dist/bpmn/index.d.ts

@@ -0,0 +1,18 @@
+import { layoutModel } from "./layout.js";
+import { routeAll } from "./routing.js";
+import { computeStats, renderHTML, type RenderStats } from "./template.js";
+import { parseAndValidate, validateModel, formatIssues } from "./validate.js";
+import type { DiagramModel, ValidationIssue } from "./types.js";
+import { safeFilename } from "./export-bpmn.js";
+export type RenderResult = {
+    ok: true;
+    html: string;
+    stats: RenderStats;
+    filenameBase: string;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+export declare function renderBPMN(rawJson: string | object): RenderResult;
+export { validateModel, parseAndValidate, formatIssues, layoutModel, routeAll, renderHTML, computeStats, safeFilename, };
+export type { DiagramModel, ValidationIssue };

package/dist/bpmn/index.js

@@ -0,0 +1,23 @@
+// Public entry point for the BPMN rendering pipeline.
+// Pipeline: raw JSON → validate → layout → route → render HTML.
+import { layoutModel } from "./layout.js";
+import { routeAll } from "./routing.js";
+import { computeStats, renderHTML } from "./template.js";
+import { parseAndValidate, validateModel, formatIssues } from "./validate.js";
+import { safeFilename } from "./export-bpmn.js";
+export function renderBPMN(rawJson) {
+    const vr = typeof rawJson === "string"
+        ? parseAndValidate(rawJson)
+        : validateModel(rawJson);
+    if (!vr.ok)
+        return { ok: false, issues: vr.issues };
+    const laid = routeAll(layoutModel(vr.model));
+    const html = renderHTML(laid);
+    return {
+        ok: true,
+        html,
+        stats: computeStats(laid),
+        filenameBase: safeFilename(vr.model),
+    };
+}
+export { validateModel, parseAndValidate, formatIssues, layoutModel, routeAll, renderHTML, computeStats, safeFilename, };

package/dist/bpmn/layout.d.ts

@@ -0,0 +1,22 @@
+import type { DiagramModel, LaidOutModel } from "./types.js";
+export declare const L: {
+    readonly TASK_W: 140;
+    readonly TASK_H: 64;
+    readonly GW: 48;
+    readonly EVT_R: 18;
+    readonly COL_W: 186;
+    readonly GAP_X: 46;
+    readonly GAP_Y: 20;
+    readonly POOL_HEADER_W: 30;
+    readonly LANE_HEADER_W: 24;
+    readonly POOL_VGAP: 16;
+    readonly LANE_MIN_H: 140;
+    readonly LANE_CORRIDOR_H: 56;
+    readonly EMPTY_POOL_H: 60;
+    readonly CANVAS_TOP: 72;
+    readonly CANVAS_LEFT_PAD: 20;
+    readonly CANVAS_RIGHT_PAD: 40;
+    readonly CANVAS_BOTTOM_PAD: 20;
+    readonly MIN_CANVAS_W: 1400;
+};
+export declare function layoutModel(m: DiagramModel): LaidOutModel;

package/dist/bpmn/layout.js

@@ -0,0 +1,424 @@
+// Layout engine for BPMN diagrams.
+// Input: a validated DiagramModel.
+// Output: a LaidOutModel with every element assigned an (x, y, w, h) box,
+// every pool/lane a Box, and a canvas size. Pure function, no I/O.
+//
+// Algorithm (banded left-to-right flow):
+//   1. Order pools vertically: external-empty initiators on top, then the
+//      organization pool, then remaining externals.
+//   2. For each non-empty pool, run Kahn's on sequenceFlows to assign each
+//      flow element a rank (column). Merge gateways naturally land at
+//      max(pred.rank) + 1 which "pulls them right" past the longest branch.
+//   3. Compute each lane's inner height from the worst-case column
+//      (how many elements in that lane stack in one column).
+//   4. Stack pools vertically; place each element at (rankCenterX, laneMidY)
+//      with intra-column vertical stacking centered on the lane.
+//   5. Place data stores / data objects in the corridor band at the bottom
+//      of whichever lane has the most tasks referencing them.
+//
+// All sizes in CSS pixels (same coordinate space as the final SVG).
+// ── Constants ──────────────────────────────────────────────────────────
+export const L = {
+    TASK_W: 140,
+    TASK_H: 64,
+    GW: 48, // gateway diamond bounding box
+    EVT_R: 18, // event radius
+    COL_W: 186, // column = TASK_W + GAP_X
+    GAP_X: 46,
+    GAP_Y: 20,
+    POOL_HEADER_W: 30, // vertical label bar on left of every pool
+    LANE_HEADER_W: 24, // vertical label bar on left of every lane
+    POOL_VGAP: 16,
+    LANE_MIN_H: 140,
+    LANE_CORRIDOR_H: 56, // bottom band for data stores/objects
+    EMPTY_POOL_H: 60,
+    CANVAS_TOP: 72, // room for header bar above diagram
+    CANVAS_LEFT_PAD: 20,
+    CANVAS_RIGHT_PAD: 40,
+    CANVAS_BOTTOM_PAD: 20,
+    MIN_CANVAS_W: 1400,
+};
+// Element dimensions used for placement / stacking
+function elementSize(el) {
+    switch (el.kind) {
+        case "task":
+        case "collapsedSubProcess":
+            return { w: L.TASK_W, h: L.TASK_H };
+        case "gateway":
+            return { w: L.GW, h: L.GW };
+        case "event":
+            return { w: L.EVT_R * 2, h: L.EVT_R * 2 };
+        case "dataObject":
+            return { w: 36, h: 44 };
+        case "dataStore":
+            return { w: 56, h: 44 };
+    }
+}
+function isFlowElement(el) {
+    return el.kind === "task"
+        || el.kind === "collapsedSubProcess"
+        || el.kind === "gateway"
+        || el.kind === "event";
+}
+function elementPool(el) {
+    if (!isFlowElement(el))
+        return null;
+    // flow elements always carry pool
+    return el.pool;
+}
+function elementLane(el) {
+    if (!isFlowElement(el))
+        return "";
+    const lane = el.lane;
+    return lane ?? "";
+}
+// ── Rank assignment (Kahn's) ───────────────────────────────────────────
+function rankPool(poolElements, flows, laneOf) {
+    const rank = new Map();
+    const elementIds = new Set(poolElements.map((e) => e.id));
+    // Build full adjacency list first (needed for back-edge detection)
+    const allOut = new Map();
+    for (const el of poolElements)
+        allOut.set(el.id, []);
+    for (const f of flows) {
+        if (!elementIds.has(f.from) || !elementIds.has(f.to))
+            continue;
+        allOut.get(f.from).push(f.to);
+    }
+    // DFS to identify back-edges (edges pointing to an ancestor in the DFS tree).
+    // Removing back-edges turns the cyclic graph into a DAG so Kahn's can rank all nodes.
+    const backEdges = new Set();
+    const visited = new Set();
+    const inStack = new Set();
+    const dfs = (id) => {
+        if (inStack.has(id) || visited.has(id))
+            return;
+        visited.add(id);
+        inStack.add(id);
+        for (const next of allOut.get(id) ?? []) {
+            if (inStack.has(next))
+                backEdges.add(`${id}→${next}`);
+            else
+                dfs(next);
+        }
+        inStack.delete(id);
+    };
+    for (const el of poolElements)
+        dfs(el.id);
+    // Rebuild adjacency without back-edges and run Kahn's topological ranking
+    const inDeg = new Map();
+    const outEdges = new Map();
+    for (const el of poolElements) {
+        inDeg.set(el.id, 0);
+        outEdges.set(el.id, []);
+    }
+    for (const f of flows) {
+        if (!elementIds.has(f.from) || !elementIds.has(f.to))
+            continue;
+        if (backEdges.has(`${f.from}→${f.to}`))
+            continue;
+        outEdges.get(f.from).push(f.to);
+        inDeg.set(f.to, (inDeg.get(f.to) ?? 0) + 1);
+    }
+    const queue = [];
+    for (const [id, deg] of inDeg) {
+        if (deg === 0) {
+            rank.set(id, 0);
+            queue.push(id);
+        }
+    }
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        const curRank = rank.get(cur);
+        for (const next of outEdges.get(cur) ?? []) {
+            // Cross-lane handoffs stay in the same column; same-lane flows advance one column.
+            const crossLane = laneOf ? laneOf.get(cur) !== laneOf.get(next) : false;
+            const cand = crossLane ? curRank : curRank + 1;
+            if (cand > (rank.get(next) ?? -1))
+                rank.set(next, cand);
+            const d = inDeg.get(next) - 1;
+            inDeg.set(next, d);
+            if (d === 0)
+                queue.push(next);
+        }
+    }
+    // Safety net: any still-unranked node (shouldn't happen after back-edge removal)
+    let maxRank = 0;
+    for (const r of rank.values())
+        if (r > maxRank)
+            maxRank = r;
+    for (const el of poolElements) {
+        if (!rank.has(el.id))
+            rank.set(el.id, maxRank + 1);
+    }
+    return rank;
+}
+// ── Main layout ────────────────────────────────────────────────────────
+export function layoutModel(m) {
+    const placements = new Map();
+    // 1. Pool ordering
+    const orderedPools = orderPools(m);
+    // 2. Rank flow elements per pool; figure out max rank across the diagram
+    const poolRanks = new Map();
+    for (const p of orderedPools) {
+        if (p.type === "external-empty")
+            continue;
+        const poolEls = m.elements.filter(isFlowElement).filter((e) => e.pool === p.id);
+        const poolFlows = m.sequenceFlows.filter((f) => {
+            const from = m.elements.find((e) => e.id === f.from);
+            const to = m.elements.find((e) => e.id === f.to);
+            if (!from || !to)
+                return false;
+            return elementPool(from) === p.id && elementPool(to) === p.id;
+        });
+        const laneOf = new Map(poolEls.map((e) => [e.id, elementLane(e)]));
+        poolRanks.set(p.id, rankPool(poolEls, poolFlows, laneOf));
+    }
+    // Global max rank — determines canvas width
+    let maxRank = 0;
+    for (const ranks of poolRanks.values()) {
+        for (const r of ranks.values())
+            if (r > maxRank)
+                maxRank = r;
+    }
+    const numColumns = maxRank + 1;
+    // 3. Compute each pool's height by stacking lanes
+    //    For each lane, compute inner height as max stack size per column * elementH + gaps.
+    const contentStartX = L.CANVAS_LEFT_PAD + L.POOL_HEADER_W;
+    // Reserve extra room inside the content for the lane header (organization pool)
+    const canvasW = Math.max(L.MIN_CANVAS_W, contentStartX + L.LANE_HEADER_W + numColumns * L.COL_W + L.CANVAS_RIGHT_PAD);
+    const poolBoxes = [];
+    let cursorY = L.CANVAS_TOP;
+    for (const pool of orderedPools) {
+        if (pool.type === "external-empty") {
+            const pbox = {
+                poolId: pool.id,
+                name: pool.name,
+                type: pool.type,
+                x: L.CANVAS_LEFT_PAD,
+                y: cursorY,
+                w: canvasW - L.CANVAS_LEFT_PAD - L.CANVAS_RIGHT_PAD,
+                h: L.EMPTY_POOL_H,
+                lanes: [],
+            };
+            poolBoxes.push(pbox);
+            cursorY += L.EMPTY_POOL_H + L.POOL_VGAP;
+            continue;
+        }
+        // Build lane list; synthesize one virtual lane for pools with no declared lanes
+        const declaredLanes = pool.lanes;
+        const lanes = declaredLanes.length > 0
+            ? declaredLanes.map((l) => ({ id: l.id, name: l.name }))
+            : [{ id: "", name: pool.name }];
+        const laneHasExplicitHeader = declaredLanes.length > 0;
+        // Compute lane heights
+        const ranks = poolRanks.get(pool.id);
+        const laneHeights = lanes.map((lane) => {
+            let perColMaxH = 0;
+            for (let col = 0; col <= maxRank; col++) {
+                const stack = m.elements.filter((e) => isFlowElement(e)
+                    && e.pool === pool.id
+                    && elementLane(e) === lane.id
+                    && ranks.get(e.id) === col);
+                if (stack.length === 0)
+                    continue;
+                // Use TASK_H as the stack unit (tasks are tallest)
+                const h = stack.length * L.TASK_H + (stack.length - 1) * L.GAP_Y;
+                if (h > perColMaxH)
+                    perColMaxH = h;
+            }
+            const inner = Math.max(L.LANE_MIN_H - L.LANE_CORRIDOR_H, perColMaxH + 20);
+            // Add corridor only if this lane actually holds data nodes (computed later);
+            // reserve corridor space by default for consistency.
+            return inner + L.LANE_CORRIDOR_H;
+        });
+        const poolH = laneHeights.reduce((a, b) => a + b, 0);
+        const pbox = {
+            poolId: pool.id,
+            name: pool.name,
+            type: pool.type,
+            x: L.CANVAS_LEFT_PAD,
+            y: cursorY,
+            w: canvasW - L.CANVAS_LEFT_PAD - L.CANVAS_RIGHT_PAD,
+            h: poolH,
+            lanes: [],
+        };
+        poolBoxes.push(pbox);
+        // Place lanes within pool
+        let laneY = cursorY;
+        for (let i = 0; i < lanes.length; i++) {
+            const lane = lanes[i];
+            const laneH = laneHeights[i];
+            const laneHeaderW = laneHasExplicitHeader ? L.LANE_HEADER_W : 0;
+            const laneBox = {
+                poolId: pool.id,
+                laneId: lane.id,
+                name: lane.name,
+                x: pbox.x + L.POOL_HEADER_W,
+                y: laneY,
+                w: pbox.w - L.POOL_HEADER_W,
+                h: laneH,
+            };
+            pbox.lanes.push(laneBox);
+            // Place elements in each column within this lane
+            for (let col = 0; col <= maxRank; col++) {
+                const stack = m.elements.filter((e) => isFlowElement(e)
+                    && e.pool === pool.id
+                    && elementLane(e) === lane.id
+                    && ranks.get(e.id) === col);
+                if (stack.length === 0)
+                    continue;
+                // Inner lane content band (above the corridor)
+                const innerTop = laneBox.y + 10;
+                const innerBottom = laneBox.y + laneBox.h - L.LANE_CORRIDOR_H - 10;
+                const innerMid = (innerTop + innerBottom) / 2;
+                const totalH = stack.length * L.TASK_H + (stack.length - 1) * L.GAP_Y;
+                let curY = innerMid - totalH / 2;
+                for (const el of stack) {
+                    const { w, h } = elementSize(el);
+                    const colCenterX = contentStartX + laneHeaderW + col * L.COL_W + L.TASK_W / 2;
+                    const centerY = curY + L.TASK_H / 2;
+                    const box = {
+                        x: colCenterX - w / 2,
+                        y: centerY - h / 2,
+                        w,
+                        h,
+                    };
+                    placements.set(el.id, {
+                        el,
+                        box,
+                        poolId: pool.id,
+                        laneId: lane.id,
+                        rank: col,
+                    });
+                    curY += L.TASK_H + L.GAP_Y;
+                }
+            }
+            laneY += laneH;
+        }
+        cursorY += poolH + L.POOL_VGAP;
+    }
+    // 4. Place data nodes (dataStore / dataObject) in corridors.
+    //    For each data node, compute the (pool, lane) that holds the most of
+    //    its associated flow elements, and drop the cylinder at the centroid
+    //    of those elements' X positions, in the corridor band.
+    for (const el of m.elements) {
+        if (el.kind !== "dataStore" && el.kind !== "dataObject")
+            continue;
+        const assocs = m.dataAssociations.filter((d) => d.dataId === el.id);
+        const targets = assocs
+            .map((d) => placements.get(d.elementId))
+            .filter((p) => !!p);
+        if (targets.length === 0) {
+            // Orphan — park at the canvas bottom-left corner
+            const { w, h } = elementSize(el);
+            placements.set(el.id, {
+                el,
+                box: { x: L.CANVAS_LEFT_PAD + 20, y: cursorY + 20, w, h },
+                poolId: "",
+                laneId: "",
+                rank: 0,
+            });
+            cursorY += h + 10;
+            continue;
+        }
+        // Pick the (pool, lane) with the most associated tasks
+        const counts = new Map();
+        for (const t of targets) {
+            const key = `${t.poolId}/${t.laneId}`;
+            const c = counts.get(key) ?? { count: 0, poolId: t.poolId, laneId: t.laneId };
+            c.count++;
+            counts.set(key, c);
+        }
+        let best = null;
+        for (const c of counts.values()) {
+            if (!best || c.count > best.count)
+                best = c;
+        }
+        if (!best) {
+            const { w, h } = elementSize(el);
+            placements.set(el.id, {
+                el,
+                box: { x: L.CANVAS_LEFT_PAD + 20, y: cursorY + 20, w, h },
+                poolId: "",
+                laneId: "",
+                rank: 0,
+            });
+            continue;
+        }
+        const bestPoolId = best.poolId;
+        const bestLaneId = best.laneId;
+        const pb = poolBoxes.find((p) => p.poolId === bestPoolId);
+        const lb = pb?.lanes.find((l) => l.laneId === bestLaneId);
+        if (!pb || !lb) {
+            const { w, h } = elementSize(el);
+            placements.set(el.id, {
+                el,
+                box: { x: L.CANVAS_LEFT_PAD + 20, y: cursorY + 20, w, h },
+                poolId: "",
+                laneId: "",
+                rank: 0,
+            });
+            continue;
+        }
+        const xsInLane = targets
+            .filter((t) => t.poolId === bestPoolId && t.laneId === bestLaneId)
+            .map((t) => t.box.x + t.box.w / 2);
+        const avgX = xsInLane.reduce((a, b) => a + b, 0) / xsInLane.length;
+        const { w, h } = elementSize(el);
+        const corridorY = lb.y + lb.h - L.LANE_CORRIDOR_H / 2 - h / 2;
+        placements.set(el.id, {
+            el,
+            box: { x: avgX - w / 2, y: corridorY, w, h },
+            poolId: bestPoolId,
+            laneId: bestLaneId,
+            rank: 0,
+        });
+    }
+    const canvasH = cursorY + L.CANVAS_BOTTOM_PAD;
+    return {
+        model: m,
+        canvas: { w: canvasW, h: canvasH },
+        pools: poolBoxes,
+        placements,
+        sequenceRoutes: [],
+        messageRoutes: [],
+        dataAssocRoutes: [],
+    };
+}
+// ── Pool ordering ──────────────────────────────────────────────────────
+//
+// Heuristic:
+//  - Identify which external pool initiates the process by sending a
+//    message to the organization pool's start event.
+//  - Put that pool first, then the organization pool(s), then the rest.
+//  - Preserve relative order within each group from the input array.
+function orderPools(m) {
+    const initiators = new Set();
+    const orgStartEvents = new Set();
+    for (const el of m.elements) {
+        if (el.kind === "event" && el.eventType === "start") {
+            const ownerId = el.pool;
+            const owner = m.pools.find((p) => p.id === ownerId);
+            if (owner && owner.type === "organization")
+                orgStartEvents.add(el.id);
+        }
+    }
+    for (const mf of m.messageFlows) {
+        if (mf.toElement && orgStartEvents.has(mf.toElement)) {
+            initiators.add(mf.fromPool);
+        }
+    }
+    const primary = [];
+    const org = [];
+    const supporting = [];
+    for (const p of m.pools) {
+        if (initiators.has(p.id))
+            primary.push(p);
+        else if (p.type === "organization")
+            org.push(p);
+        else
+            supporting.push(p);
+    }
+    return [...primary, ...org, ...supporting];
+}

package/dist/bpmn/routing.d.ts

@@ -0,0 +1,6 @@
+import type { DataAssociation, LaidOutModel, MessageFlow, RoutedFlow, SequenceFlow } from "./types.js";
+declare function routeSequenceFlow(flow: SequenceFlow, laid: LaidOutModel, siblingIndex: number, siblingCount: number): RoutedFlow | null;
+declare function routeMessageFlow(mf: MessageFlow, laid: LaidOutModel, trackOffset?: number): RoutedFlow | null;
+declare function routeDataAssoc(da: DataAssociation, laid: LaidOutModel): RoutedFlow | null;
+export declare function routeAll(laid: LaidOutModel): LaidOutModel;
+export { routeSequenceFlow, routeMessageFlow, routeDataAssoc };