@bpmnkit/core 0.0.23 → 0.0.25

package/dist/bpmn/bpmn-builder.js

@@ -1,11 +1,13 @@
-import { layoutProcess } from "../layout/layout-engine.js";
 import { generateId } from "../types/id-generator.js";
+import { applyAutoLayout } from "./auto-layout.js";
 import { restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
 import { zeebeExtensionsToXmlElements } from "./zeebe-extensions.js";
+// Keep in sync with packages/core/package.json version
+const EXPORTER_VERSION = "0.0.23";
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-function buildEventDefinitions(opts, rootErrors, rootMessages) {
+function buildEventDefinitions(opts, rootErrors, rootMessages, rootSignals, rootEscalations) {
     const defs = [];
     if (opts.timerDuration || opts.timerDate || opts.timerCycle) {
         defs.push({
@@ -16,28 +18,63 @@ function buildEventDefinitions(opts, rootErrors, rootMessages) {
         });
     }
     if (opts.errorCode !== undefined || opts.errorRef !== undefined) {
-        let errorRef = opts.errorRef;
-        if (!errorRef && opts.errorCode !== undefined && rootErrors) {
-            const errorId = generateId("Error");
-            rootErrors.push({ id: errorId, name: opts.errorCode, errorCode: opts.errorCode });
-            errorRef = errorId;
+        const codeOrRef = opts.errorCode ?? opts.errorRef;
+        let errorRef;
+        if (codeOrRef !== undefined && rootErrors) {
+            let existing = rootErrors.find((e) => e.errorCode === codeOrRef || e.name === codeOrRef);
+            if (!existing) {
+                existing = { id: generateId("Error"), name: codeOrRef, errorCode: codeOrRef };
+                rootErrors.push(existing);
+            }
+            errorRef = existing.id;
+        }
+        else {
+            errorRef = codeOrRef;
         }
         defs.push({ type: "error", errorRef });
     }
     if (opts.messageName !== undefined) {
         let messageRef = opts.messageName;
         if (rootMessages) {
-            const messageId = generateId("Message");
-            rootMessages.push({ id: messageId, name: opts.messageName, unknownAttributes: {} });
-            messageRef = messageId;
+            let existing = rootMessages.find((m) => m.name === opts.messageName);
+            if (!existing) {
+                existing = { id: generateId("Message"), name: opts.messageName, unknownAttributes: {} };
+                rootMessages.push(existing);
+            }
+            messageRef = existing.id;
         }
         defs.push({ type: "message", messageRef });
     }
     if (opts.signalName !== undefined) {
-        defs.push({ type: "signal", signalRef: opts.signalName });
+        let signalRef = opts.signalName;
+        if (rootSignals) {
+            let existing = rootSignals.find((s) => s.name === opts.signalName);
+            if (!existing) {
+                existing = { id: generateId("Signal"), name: opts.signalName };
+                rootSignals.push(existing);
+            }
+            signalRef = existing.id;
+        }
+        defs.push({ type: "signal", signalRef });
     }
     if (opts.escalationCode !== undefined) {
-        defs.push({ type: "escalation", escalationRef: opts.escalationCode });
+        let escalationRef = opts.escalationCode;
+        if (rootEscalations) {
+            let existing = rootEscalations.find((e) => e.escalationCode === opts.escalationCode);
+            if (!existing) {
+                existing = {
+                    id: generateId("Escalation"),
+                    name: opts.escalationCode,
+                    escalationCode: opts.escalationCode,
+                };
+                rootEscalations.push(existing);
+            }
+            escalationRef = existing.id;
+        }
+        defs.push({ type: "escalation", escalationRef });
+    }
+    if (opts.compensation) {
+        defs.push({ type: "compensate", activityRef: opts.activityRef });
     }
     return defs;
 }
@@ -155,46 +192,6 @@ function buildAdHocLoopCharacteristics(lc) {
         ],
     };
 }
-/** Convert a layout engine result into a BPMN diagram interchange structure. */
-function layoutResultToDiagram(processId, layout) {
-    const shapes = layout.nodes.map((node) => {
-        const shape = {
-            id: `${node.id}_di`,
-            bpmnElement: node.id,
-            bounds: { ...node.bounds },
-            unknownAttributes: {},
-        };
-        if (node.isExpanded !== undefined) {
-            shape.isExpanded = node.isExpanded;
-        }
-        if (node.labelBounds) {
-            shape.label = { bounds: { ...node.labelBounds } };
-        }
-        return shape;
-    });
-    const edges = layout.edges.map((edge) => {
-        const diEdge = {
-            id: `${edge.id}_di`,
-            bpmnElement: edge.id,
-            waypoints: edge.waypoints.map((wp) => ({ ...wp })),
-            unknownAttributes: {},
-        };
-        if (edge.labelBounds) {
-            diEdge.label = { bounds: { ...edge.labelBounds } };
-        }
-        return diEdge;
-    });
-    const plane = {
-        id: `${processId}_di_plane`,
-        bpmnElement: processId,
-        shapes,
-        edges,
-    };
-    return {
-        id: `${processId}_di`,
-        plane,
-    };
-}
 function recomputeIncomingOutgoing(elements, flows) {
     for (const el of elements) {
         el.incoming = [];
@@ -236,6 +233,200 @@ function makeConditionExpression(expression) {
     };
 }
 // ---------------------------------------------------------------------------
+// Element factory functions — shared by all three builder classes
+// ---------------------------------------------------------------------------
+function makeServiceTaskEl(id, options) {
+    const unknownAttributes = {};
+    if (options.modelerTemplate)
+        unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
+    if (options.modelerTemplateVersion)
+        unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
+    if (options.modelerTemplateIcon)
+        unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
+    const el = makeFlowElement(id, "serviceTask", {
+        name: options.name,
+        extensionElements: buildServiceTaskExtensions(options),
+    });
+    el.unknownAttributes = unknownAttributes;
+    if (options.isForCompensation)
+        el.isForCompensation = true;
+    return el;
+}
+function makeScriptTaskEl(id, options) {
+    const el = makeFlowElement(id, "scriptTask", {
+        name: options.name,
+        extensionElements: zeebeExtensionsToXmlElements({
+            unknownElements: [
+                {
+                    name: "zeebe:script",
+                    attributes: { expression: options.expression, resultVariable: options.resultVariable },
+                    children: [],
+                },
+            ],
+        }),
+    });
+    if (options.isForCompensation)
+        el.isForCompensation = true;
+    return el;
+}
+function makeUserTaskEl(id, options) {
+    const ext = zeebeExtensionsToXmlElements({
+        ...(options?.zeebeUserTask ? { userTask: true } : {}),
+        ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
+    });
+    const el = makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
+    if (options?.isForCompensation)
+        el.isForCompensation = true;
+    return el;
+}
+function makeBusinessRuleTaskEl(id, options) {
+    const ext = [];
+    if (options?.taskType) {
+        ext.push(...zeebeExtensionsToXmlElements({ taskDefinition: { type: options.taskType } }));
+    }
+    if (options?.decisionId) {
+        ext.push(...zeebeExtensionsToXmlElements({
+            calledDecision: {
+                decisionId: options.decisionId,
+                resultVariable: options.resultVariable ?? "result",
+            },
+        }));
+    }
+    const el = makeFlowElement(id, "businessRuleTask", {
+        name: options?.name,
+        extensionElements: ext,
+    });
+    if (options?.isForCompensation)
+        el.isForCompensation = true;
+    return el;
+}
+function makeCallActivityEl(id, options) {
+    const attrs = { processId: options.processId };
+    if (options.propagateAllChildVariables !== undefined) {
+        attrs.propagateAllChildVariables = String(options.propagateAllChildVariables);
+    }
+    const el = makeFlowElement(id, "callActivity", {
+        name: options.name,
+        extensionElements: zeebeExtensionsToXmlElements({
+            unknownElements: [{ name: "zeebe:calledElement", attributes: attrs, children: [] }],
+        }),
+    });
+    if (options.isForCompensation)
+        el.isForCompensation = true;
+    return el;
+}
+function makeExclusiveGatewayEl(id, options) {
+    const el = makeFlowElement(id, "exclusiveGateway", options);
+    if (options?.defaultFlow && el.type === "exclusiveGateway") {
+        ;
+        el.default = options.defaultFlow;
+    }
+    return el;
+}
+function makeInclusiveGatewayEl(id, options) {
+    const el = makeFlowElement(id, "inclusiveGateway", options);
+    if (options?.defaultFlow && el.type === "inclusiveGateway") {
+        ;
+        el.default = options.defaultFlow;
+    }
+    return el;
+}
+// ---------------------------------------------------------------------------
+// Shared graph helpers — used by ProcessBuilder and SubProcessContentBuilder
+// ---------------------------------------------------------------------------
+function insertJoinGateways(elements, flows) {
+    const GATEWAY_TYPES = new Set([
+        "exclusiveGateway",
+        "parallelGateway",
+        "inclusiveGateway",
+        "eventBasedGateway",
+    ]);
+    const elementTypes = new Map();
+    for (const el of elements)
+        elementTypes.set(el.id, el.type);
+    const outCount = new Map();
+    for (const flow of flows) {
+        outCount.set(flow.sourceRef, (outCount.get(flow.sourceRef) ?? 0) + 1);
+    }
+    const splitGateways = new Set();
+    for (const [id, count] of outCount) {
+        const type = elementTypes.get(id);
+        if (type && GATEWAY_TYPES.has(type) && count >= 2)
+            splitGateways.add(id);
+    }
+    if (splitGateways.size === 0)
+        return;
+    const incoming = new Map();
+    for (const flow of flows) {
+        const arr = incoming.get(flow.targetRef);
+        if (arr)
+            arr.push(flow);
+        else
+            incoming.set(flow.targetRef, [flow]);
+    }
+    for (const [targetId, inFlows] of incoming) {
+        if (inFlows.length < 2)
+            continue;
+        const splitToFlows = new Map();
+        for (const flow of inFlows) {
+            const split = traceBackToSplit(flow.sourceRef, splitGateways, flows);
+            if (split) {
+                const arr = splitToFlows.get(split);
+                if (arr)
+                    arr.push(flow);
+                else
+                    splitToFlows.set(split, [flow]);
+            }
+        }
+        for (const [splitId, convergingFlows] of splitToFlows) {
+            if (convergingFlows.length < 2)
+                continue;
+            const gwType = elementTypes.get(splitId);
+            if (!gwType)
+                continue;
+            // eventBasedGateway is split-only; converge through an XOR join instead
+            const joinType = gwType === "eventBasedGateway" ? "exclusiveGateway" : gwType;
+            const targetType = elementTypes.get(targetId);
+            if (targetType === joinType)
+                continue;
+            const joinId = `${splitId}_join`;
+            if (elementTypes.has(joinId))
+                continue;
+            const joinElement = makeFlowElement(joinId, joinType, {});
+            elements.push(joinElement);
+            elementTypes.set(joinId, joinType);
+            for (const flow of convergingFlows)
+                flow.targetRef = joinId;
+            flows.push({
+                id: generateId("Flow"),
+                sourceRef: joinId,
+                targetRef: targetId,
+                extensionElements: [],
+                unknownAttributes: {},
+            });
+        }
+    }
+}
+function traceBackToSplit(nodeId, splitGateways, flows) {
+    const visited = new Set();
+    let current = nodeId;
+    while (current) {
+        if (visited.has(current))
+            return undefined;
+        visited.add(current);
+        if (splitGateways.has(current))
+            return current;
+        const inFlows = flows.filter((f) => f.targetRef === current);
+        if (inFlows.length !== 1)
+            return undefined;
+        const prev = inFlows[0];
+        if (!prev)
+            return undefined;
+        current = prev.sourceRef;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
 // Branch builder (used inside gateway branch callbacks)
 // ---------------------------------------------------------------------------
 /**
@@ -260,10 +451,23 @@ export class BranchBuilder {
     /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
     _connected = false;
     /** @internal */
-    constructor(gatewayId, branchName) {
+    _textAnnotations = [];
+    /** @internal */
+    _associations = [];
+    _annCounters = new Map();
+    rootErrors;
+    rootMessages;
+    rootSignals;
+    rootEscalations;
+    /** @internal */
+    constructor(gatewayId, branchName, rootErrors = [], rootMessages = [], rootSignals = [], rootEscalations = []) {
         this.gatewayId = gatewayId;
         this.branchName = branchName;
         this.lastNodeId = gatewayId;
+        this.rootErrors = rootErrors;
+        this.rootMessages = rootMessages;
+        this.rootSignals = rootSignals;
+        this.rootEscalations = rootEscalations;
     }
     /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
     condition(expression) {
@@ -327,129 +531,97 @@ export class BranchBuilder {
     get _lastNodeId() {
         return this.lastNodeId;
     }
+    // ---- Annotations ----
+    /** Attach a text annotation to the element at the current cursor position. */
+    textAnnotation(text) {
+        return this.annotate(this.lastNodeId, text);
+    }
+    /** Attach a text annotation to an element by explicit ID. */
+    annotate(elementId, text) {
+        const n = (this._annCounters.get(elementId) ?? 0) + 1;
+        this._annCounters.set(elementId, n);
+        const annId = `TextAnnotation_${elementId}_${n}`;
+        this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
+        this._associations.push({
+            id: `Association_${elementId}_${n}`,
+            sourceRef: elementId,
+            targetRef: annId,
+            associationDirection: "None",
+            unknownAttributes: {},
+        });
+        return this;
+    }
     // ---- Flow-node methods (mirror ProcessBuilder) ----
     serviceTask(id, options) {
-        const unknownAttributes = {};
-        if (options.modelerTemplate)
-            unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
-        if (options.modelerTemplateVersion)
-            unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
-        if (options.modelerTemplateIcon)
-            unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
-        const el = makeFlowElement(id, "serviceTask", {
-            name: options.name,
-            extensionElements: buildServiceTaskExtensions(options),
-        });
-        el.unknownAttributes = unknownAttributes;
-        return this.addElement(el);
+        return this.addElement(makeServiceTaskEl(id, options));
     }
     userTask(id, options) {
-        const ext = options?.formId
-            ? zeebeExtensionsToXmlElements({ formDefinition: { formId: options.formId } })
-            : [];
-        return this.addElement(makeFlowElement(id, "userTask", {
-            name: options?.name,
-            extensionElements: ext,
-        }));
+        return this.addElement(makeUserTaskEl(id, options));
     }
     scriptTask(id, options) {
-        return this.addElement(makeFlowElement(id, "scriptTask", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:script",
-                        attributes: {
-                            expression: options.expression,
-                            resultVariable: options.resultVariable,
-                        },
-                        children: [],
-                    },
-                ],
-            }),
-        }));
+        return this.addElement(makeScriptTaskEl(id, options));
     }
     sendTask(id, options) {
-        return this.addElement(makeFlowElement(id, "sendTask", options));
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     receiveTask(id, options) {
-        return this.addElement(makeFlowElement(id, "receiveTask", options));
+        const el = makeFlowElement(id, "receiveTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     businessRuleTask(id, options) {
-        const ext = options?.decisionId
-            ? zeebeExtensionsToXmlElements({
-                calledDecision: {
-                    decisionId: options.decisionId,
-                    resultVariable: options.resultVariable ?? "result",
-                },
-            })
-            : [];
-        return this.addElement(makeFlowElement(id, "businessRuleTask", {
-            name: options?.name,
-            extensionElements: ext,
-        }));
+        return this.addElement(makeBusinessRuleTaskEl(id, options));
     }
     callActivity(id, options) {
-        const attrs = { processId: options.processId };
-        if (options.propagateAllChildVariables !== undefined) {
-            attrs.propagateAllChildVariables = String(options.propagateAllChildVariables);
-        }
-        return this.addElement(makeFlowElement(id, "callActivity", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:calledElement",
-                        attributes: attrs,
-                        children: [],
-                    },
-                ],
-            }),
-        }));
+        return this.addElement(makeCallActivityEl(id, options));
+    }
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id, options) {
+        const el = makeFlowElement(id, "task", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
     }
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
-        if (el.type === "startEvent" &&
-            (options?.timerDuration || options?.timerCycle || options?.timerDate)) {
-            el.eventDefinitions = buildEventDefinitions(options);
+        if (el.type === "startEvent" && options) {
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
     endEvent(id, options) {
-        return this.addElement(makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options));
+        const el = makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options);
+        if (el.type === "endEvent" && options) {
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
+        }
+        return this.addElement(el);
     }
     intermediateThrowEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
         if (el.type === "intermediateThrowEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
         if (el.type === "intermediateCatchEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+            el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         return this.addElement(el);
     }
     exclusiveGateway(id, options) {
-        const el = makeFlowElement(id, "exclusiveGateway", options);
-        if (options?.defaultFlow && el.type === "exclusiveGateway") {
-            ;
-            el.default = options.defaultFlow;
-        }
-        return this.addElement(el);
+        return this.addElement(makeExclusiveGatewayEl(id, options));
     }
     parallelGateway(id, options) {
         return this.addElement(makeFlowElement(id, "parallelGateway", options));
     }
     inclusiveGateway(id, options) {
-        const el = makeFlowElement(id, "inclusiveGateway", options);
-        if (options?.defaultFlow && el.type === "inclusiveGateway") {
-            ;
-            el.default = options.defaultFlow;
-        }
-        return this.addElement(el);
+        return this.addElement(makeInclusiveGatewayEl(id, options));
     }
     eventBasedGateway(id, options) {
         return this.addElement(makeFlowElement(id, "eventBasedGateway", options));
@@ -464,99 +636,199 @@ export class SubProcessContentBuilder {
     _elements = [];
     /** @internal */
     _flows = [];
+    /** @internal */
+    _textAnnotations = [];
+    /** @internal */
+    _associations = [];
+    _annCounters = new Map();
     lastNodeId;
+    currentGatewayId;
+    openBranchEnds = [];
     addElement(element) {
+        if (this._elements.some((n) => n.id === element.id)) {
+            throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
+        }
         this._elements.push(element);
         if (this.lastNodeId) {
-            const flowId = generateId("Flow");
             this._flows.push({
-                id: flowId,
+                id: generateId("Flow"),
                 sourceRef: this.lastNodeId,
                 targetRef: element.id,
                 extensionElements: [],
                 unknownAttributes: {},
             });
         }
+        for (const branchEnd of this.openBranchEnds) {
+            this._flows.push({
+                id: generateId("Flow"),
+                sourceRef: branchEnd,
+                targetRef: element.id,
+                extensionElements: [],
+                unknownAttributes: {},
+            });
+        }
+        this.openBranchEnds = [];
         this.lastNodeId = element.id;
         return this;
     }
+    // ---- Events ----
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
         if (el.type === "startEvent" && options) {
             el.eventDefinitions = buildEventDefinitions(options);
+            if (options.isInterrupting === false)
+                el.isInterrupting = false;
         }
         return this.addElement(el);
     }
     endEvent(id, options) {
-        return this.addElement(makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options));
-    }
-    serviceTask(id, options) {
-        const unknownAttributes = {};
-        if (options.modelerTemplate)
-            unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
-        if (options.modelerTemplateVersion)
-            unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
-        if (options.modelerTemplateIcon)
-            unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
-        const el = makeFlowElement(id, "serviceTask", {
-            name: options.name,
-            extensionElements: buildServiceTaskExtensions(options),
-        });
-        el.unknownAttributes = unknownAttributes;
+        const el = makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options);
+        if (el.type === "endEvent" && options)
+            el.eventDefinitions = buildEventDefinitions(options);
         return this.addElement(el);
     }
-    userTask(id, options) {
-        return this.addElement(makeFlowElement(id, "userTask", { name: options?.name }));
-    }
-    scriptTask(id, options) {
-        return this.addElement(makeFlowElement(id, "scriptTask", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:script",
-                        attributes: {
-                            expression: options.expression,
-                            resultVariable: options.resultVariable,
-                        },
-                        children: [],
-                    },
-                ],
-            }),
-        }));
-    }
-    callActivity(id, options) {
-        const attrs = { processId: options.processId };
-        if (options.propagateAllChildVariables !== undefined) {
-            attrs.propagateAllChildVariables = String(options.propagateAllChildVariables);
-        }
-        return this.addElement(makeFlowElement(id, "callActivity", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:calledElement",
-                        attributes: attrs,
-                        children: [],
-                    },
-                ],
-            }),
-        }));
-    }
     intermediateThrowEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
-        if (el.type === "intermediateThrowEvent" && options) {
+        if (el.type === "intermediateThrowEvent" && options)
             el.eventDefinitions = buildEventDefinitions(options);
-        }
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
-        if (el.type === "intermediateCatchEvent" && options) {
+        if (el.type === "intermediateCatchEvent" && options)
             el.eventDefinitions = buildEventDefinitions(options);
-        }
         return this.addElement(el);
     }
+    // ---- Tasks ----
+    serviceTask(id, options) {
+        return this.addElement(makeServiceTaskEl(id, options));
+    }
+    scriptTask(id, options) {
+        return this.addElement(makeScriptTaskEl(id, options));
+    }
+    userTask(id, options) {
+        return this.addElement(makeUserTaskEl(id, options));
+    }
+    businessRuleTask(id, options) {
+        return this.addElement(makeBusinessRuleTaskEl(id, options));
+    }
+    callActivity(id, options) {
+        return this.addElement(makeCallActivityEl(id, options));
+    }
+    sendTask(id, options) {
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
+    }
+    receiveTask(id, options) {
+        const el = makeFlowElement(id, "receiveTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
+    }
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id, options) {
+        const el = makeFlowElement(id, "task", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        return this.addElement(el);
+    }
+    // ---- Gateways ----
+    exclusiveGateway(id, options) {
+        this.currentGatewayId = id;
+        return this.addElement(makeExclusiveGatewayEl(id, options));
+    }
+    parallelGateway(id, options) {
+        this.currentGatewayId = id;
+        return this.addElement(makeFlowElement(id, "parallelGateway", options));
+    }
+    inclusiveGateway(id, options) {
+        this.currentGatewayId = id;
+        return this.addElement(makeInclusiveGatewayEl(id, options));
+    }
+    eventBasedGateway(id, options) {
+        this.currentGatewayId = id;
+        return this.addElement(makeFlowElement(id, "eventBasedGateway", options));
+    }
+    // ---- Annotations ----
+    /** Attach a text annotation to the element at the current cursor position. */
+    textAnnotation(text) {
+        if (!this.lastNodeId) {
+            throw new Error("textAnnotation() must follow a flow element");
+        }
+        return this.annotate(this.lastNodeId, text);
+    }
+    /** Attach a text annotation to an element by explicit ID. */
+    annotate(elementId, text) {
+        const n = (this._annCounters.get(elementId) ?? 0) + 1;
+        this._annCounters.set(elementId, n);
+        const annId = `TextAnnotation_${elementId}_${n}`;
+        this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
+        this._associations.push({
+            id: `Association_${elementId}_${n}`,
+            sourceRef: elementId,
+            targetRef: annId,
+            associationDirection: "None",
+            unknownAttributes: {},
+        });
+        return this;
+    }
+    // ---- Branching & flow control ----
+    branch(name, callback) {
+        if (!this.currentGatewayId) {
+            throw new Error("branch() must be called after a gateway element");
+        }
+        const b = new BranchBuilder(this.currentGatewayId, name);
+        callback(b);
+        for (const el of b._elements) {
+            if (this._elements.some((n) => n.id === el.id)) {
+                throw new Error(`Duplicate element ID "${el.id}"`);
+            }
+            this._elements.push(el);
+        }
+        for (const fl of b._flows)
+            this._flows.push(fl);
+        for (const ann of b._textAnnotations)
+            this._textAnnotations.push(ann);
+        for (const assoc of b._associations)
+            this._associations.push(assoc);
+        if (b._defaultFlowId) {
+            const gw = this._elements.find((n) => n.id === this.currentGatewayId);
+            if (gw && (gw.type === "exclusiveGateway" || gw.type === "inclusiveGateway")) {
+                gw.default = b._defaultFlowId;
+            }
+        }
+        if (!b._connected && b._elements.length > 0) {
+            const lastEl = b._elements[b._elements.length - 1];
+            if (lastEl && lastEl.type !== "endEvent") {
+                this.openBranchEnds.push(b._lastNodeId);
+            }
+        }
+        this.lastNodeId = undefined;
+        return this;
+    }
+    connectTo(targetId) {
+        if (this.lastNodeId) {
+            this._flows.push({
+                id: generateId("Flow"),
+                sourceRef: this.lastNodeId,
+                targetRef: targetId,
+                extensionElements: [],
+                unknownAttributes: {},
+            });
+        }
+        this.lastNodeId = undefined;
+        return this;
+    }
+    element(elementId) {
+        if (!this._elements.some((n) => n.id === elementId)) {
+            throw new Error(`Element "${elementId}" not found in sub-process`);
+        }
+        this.lastNodeId = elementId;
+        this.currentGatewayId = undefined;
+        return this;
+    }
 }
 // ---------------------------------------------------------------------------
 // Process builder (top-level entry point)
@@ -571,10 +843,18 @@ export class ProcessBuilder {
     sequenceFlows = [];
     rootErrors = [];
     rootMessages = [];
+    rootSignals = [];
+    rootEscalations = [];
+    _textAnnotations = [];
+    _associations = [];
+    _annCounters = new Map();
     lastNodeId;
     currentGatewayId;
     openBranchEnds = [];
     _autoLayout = false;
+    _executionPlatformVersion = "8.9.0";
+    _serviceTaskDefaults = {};
+    _savedMainFlowId = undefined;
     constructor(processId) {
         this.processId = processId;
     }
@@ -583,6 +863,17 @@ export class ProcessBuilder {
         this._autoLayout = true;
         return this;
     }
+    /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
+    executionPlatformVersion(version) {
+        this._executionPlatformVersion = version;
+        return this;
+    }
+    /** Set process-wide defaults applied to subsequently added elements. */
+    defaults(options) {
+        if (options.serviceTask)
+            this._serviceTaskDefaults = { ...this._serviceTaskDefaults, ...options.serviceTask };
+        return this;
+    }
     /** Set the display name for this process. */
     name(name) {
         this.processName = name;
@@ -613,7 +904,9 @@ export class ProcessBuilder {
             extensionElements: extElements,
         });
         if (element.type === "startEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
+            if (options.isInterrupting === false)
+                element.isInterrupting = false;
         }
         if (options?.modelerTemplate) {
             element.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
@@ -639,10 +932,22 @@ export class ProcessBuilder {
         this.currentGatewayId = undefined;
         return this.startEvent(id, options);
     }
+    /**
+     * Alias for `addStartEvent()` — begins a new disconnected parallel path.
+     *
+     * Use this for readability when modeling processes with multiple independent paths.
+     */
+    disconnectedStartEvent(id, options) {
+        return this.addStartEvent(id, options);
+    }
     /** Add an end event. */
     endEvent(id, options) {
         const nodeId = id ?? generateId("EndEvent");
-        this.addFlowElement(makeFlowElement(nodeId, "endEvent", options));
+        const element = makeFlowElement(nodeId, "endEvent", options);
+        if (element.type === "endEvent" && options) {
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
+        }
+        this.addFlowElement(element);
         return this;
     }
     /** Add an intermediate throw event (none, message, signal, escalation). */
@@ -650,7 +955,7 @@ export class ProcessBuilder {
         const nodeId = id ?? generateId("IntermediateThrowEvent");
         const element = makeFlowElement(nodeId, "intermediateThrowEvent", options);
         if (element.type === "intermediateThrowEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         this.addFlowElement(element);
         return this;
@@ -660,7 +965,7 @@ export class ProcessBuilder {
         const nodeId = id ?? generateId("IntermediateCatchEvent");
         const element = makeFlowElement(nodeId, "intermediateCatchEvent", options);
         if (element.type === "intermediateCatchEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         this.addFlowElement(element);
         return this;
@@ -676,32 +981,57 @@ export class ProcessBuilder {
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
-            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         // Boundary events never auto-connect — temporarily clear lastNodeId
         const prevLast = this.lastNodeId;
         this.lastNodeId = undefined;
         this.addFlowElement(element);
+        // For compensation boundary events, save the main-flow cursor AFTER addFlowElement
+        // so subsequent normal elements don't accidentally clear it before it's consumed.
+        if (options.compensation) {
+            this._savedMainFlowId = prevLast;
+        }
         // Don't restore prevLast — the builder now chains from the boundary event
         void prevLast;
         return this;
     }
+    /**
+     * Attach a boundary event to the preceding task and build its outgoing path,
+     * then restore the builder cursor to the preceding task so the main flow continues.
+     *
+     * @param id - ID for the boundary event element.
+     * @param options - Boundary event options (without `attachedTo` — inferred from cursor).
+     * @param handler - Callback that chains elements from the boundary event.
+     */
+    withBoundary(id, options, handler) {
+        const attachedTo = this.lastNodeId;
+        if (!attachedTo) {
+            throw new Error("withBoundary() must follow a task element. Current builder position has no active element.");
+        }
+        const savedLast = this.lastNodeId;
+        const savedGateway = this.currentGatewayId;
+        const savedOpenEnds = [...this.openBranchEnds];
+        this.openBranchEnds = [];
+        // boundaryEvent() sets lastNodeId to the boundary event id
+        this.boundaryEvent(id, { ...options, attachedTo });
+        // Build the error/timeout path chaining from the boundary event
+        handler(this);
+        // Restore cursor to the original task so the main flow continues
+        this.lastNodeId = savedLast;
+        this.currentGatewayId = savedGateway;
+        this.openBranchEnds = savedOpenEnds;
+        this._savedMainFlowId = undefined;
+        return this;
+    }
     // ---- Tasks ----
     /** Add a service task with Zeebe task definition and optional IO mappings. */
     serviceTask(id, options) {
-        const unknownAttributes = {};
-        if (options.modelerTemplate)
-            unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
-        if (options.modelerTemplateVersion)
-            unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
-        if (options.modelerTemplateIcon)
-            unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
-        const el = makeFlowElement(id, "serviceTask", {
-            name: options.name,
-            extensionElements: buildServiceTaskExtensions(options),
-        });
-        el.unknownAttributes = unknownAttributes;
-        this.addFlowElement(el);
+        const merged = {
+            ...options,
+            retries: options.retries ?? this._serviceTaskDefaults.retries,
+        };
+        this.addFlowElement(makeServiceTaskEl(id, merged));
         return this;
     }
     /** Add a REST connector task — syntactic sugar over `serviceTask()`. */
@@ -732,95 +1062,52 @@ export class ProcessBuilder {
     }
     /** Add a script task with a FEEL expression. */
     scriptTask(id, options) {
-        this.addFlowElement(makeFlowElement(id, "scriptTask", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:script",
-                        attributes: {
-                            expression: options.expression,
-                            resultVariable: options.resultVariable,
-                        },
-                        children: [],
-                    },
-                ],
-            }),
-        }));
+        this.addFlowElement(makeScriptTaskEl(id, options));
         return this;
     }
     /** Add a user task with optional form reference. */
     userTask(id, options) {
-        const extensionElements = options?.formId
-            ? zeebeExtensionsToXmlElements({ formDefinition: { formId: options.formId } })
-            : [];
-        this.addFlowElement(makeFlowElement(id, "userTask", {
-            name: options?.name,
-            extensionElements,
-        }));
+        this.addFlowElement(makeUserTaskEl(id, options));
         return this;
     }
     /** Add a send task (aspirational). */
     sendTask(id, options) {
-        this.addFlowElement(makeFlowElement(id, "sendTask", options));
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        this.addFlowElement(el);
         return this;
     }
     /** Add a receive task (aspirational). */
     receiveTask(id, options) {
-        this.addFlowElement(makeFlowElement(id, "receiveTask", options));
+        const el = makeFlowElement(id, "receiveTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        this.addFlowElement(el);
         return this;
     }
     /** Add a business rule task. */
     businessRuleTask(id, options) {
-        const ext = [];
-        if (options?.taskType) {
-            ext.push(...zeebeExtensionsToXmlElements({ taskDefinition: { type: options.taskType } }));
-        }
-        if (options?.decisionId) {
-            ext.push(...zeebeExtensionsToXmlElements({
-                calledDecision: {
-                    decisionId: options.decisionId,
-                    resultVariable: options.resultVariable ?? "result",
-                },
-            }));
-        }
-        this.addFlowElement(makeFlowElement(id, "businessRuleTask", {
-            name: options?.name,
-            extensionElements: ext,
-        }));
+        this.addFlowElement(makeBusinessRuleTaskEl(id, options));
         return this;
     }
     /** Add a call activity referencing another process. */
     callActivity(id, options) {
-        const attrs = {
-            processId: options.processId,
-        };
-        if (options.propagateAllChildVariables !== undefined) {
-            attrs.propagateAllChildVariables = String(options.propagateAllChildVariables);
-        }
-        this.addFlowElement(makeFlowElement(id, "callActivity", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:calledElement",
-                        attributes: attrs,
-                        children: [],
-                    },
-                ],
-            }),
-        }));
+        this.addFlowElement(makeCallActivityEl(id, options));
+        return this;
+    }
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id, options) {
+        const el = makeFlowElement(id, "task", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        this.addFlowElement(el);
         return this;
     }
     // ---- Gateways ----
     /** Add an exclusive gateway (XOR split/join). */
     exclusiveGateway(id, options) {
-        const element = makeFlowElement(id, "exclusiveGateway", options);
-        if (options?.defaultFlow && element.type === "exclusiveGateway") {
-            ;
-            element.default = options.defaultFlow;
-        }
-        this.addFlowElement(element);
+        this.addFlowElement(makeExclusiveGatewayEl(id, options));
         this.currentGatewayId = id;
         return this;
     }
@@ -832,12 +1119,7 @@ export class ProcessBuilder {
     }
     /** Add an inclusive gateway (OR split/join). Aspirational. */
     inclusiveGateway(id, options) {
-        const element = makeFlowElement(id, "inclusiveGateway", options);
-        if (options?.defaultFlow && element.type === "inclusiveGateway") {
-            ;
-            element.default = options.defaultFlow;
-        }
-        this.addFlowElement(element);
+        this.addFlowElement(makeInclusiveGatewayEl(id, options));
         this.currentGatewayId = id;
         return this;
     }
@@ -869,7 +1151,7 @@ export class ProcessBuilder {
         if (!this.currentGatewayId) {
             throw new Error("branch() must be called after a gateway element");
         }
-        const b = new BranchBuilder(this.currentGatewayId, name);
+        const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         callback(b);
         for (const el of b._elements) {
             if (this.flowElements.some((n) => n.id === el.id)) {
@@ -880,6 +1162,10 @@ export class ProcessBuilder {
         for (const fl of b._flows) {
             this.sequenceFlows.push(fl);
         }
+        for (const ann of b._textAnnotations)
+            this._textAnnotations.push(ann);
+        for (const assoc of b._associations)
+            this._associations.push(assoc);
         // If the branch is the default flow, set the gateway's default
         if (b._defaultFlowId) {
             const gateway = this.flowElements.find((n) => n.id === this.currentGatewayId);
@@ -933,6 +1219,7 @@ export class ProcessBuilder {
     adHocSubProcess(id, content, options) {
         const sub = new SubProcessContentBuilder();
         content(sub);
+        insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
         const zeebeExt = {};
         if (options?.taskDefinition) {
@@ -984,6 +1271,8 @@ export class ProcessBuilder {
         if (element.type === "adHocSubProcess") {
             element.flowElements = sub._elements;
             element.sequenceFlows = sub._flows;
+            element.textAnnotations = sub._textAnnotations;
+            element.associations = sub._associations;
             if (options?.loopCharacteristics) {
                 element.loopCharacteristics = buildAdHocLoopCharacteristics(options.loopCharacteristics);
             }
@@ -998,11 +1287,14 @@ export class ProcessBuilder {
     subProcess(id, content, options) {
         const sub = new SubProcessContentBuilder();
         content(sub);
+        insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
         const element = makeFlowElement(id, "subProcess", options);
         if (element.type === "subProcess") {
             element.flowElements = sub._elements;
             element.sequenceFlows = sub._flows;
+            element.textAnnotations = sub._textAnnotations;
+            element.associations = sub._associations;
             if (options?.multiInstance) {
                 element.loopCharacteristics = buildMultiInstance(options.multiInstance);
             }
@@ -1010,17 +1302,52 @@ export class ProcessBuilder {
         this.addFlowElement(element);
         return this;
     }
-    /** Add an event sub-process (aspirational). */
+    /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
     eventSubProcess(id, content, options) {
         const sub = new SubProcessContentBuilder();
         content(sub);
+        insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const element = makeFlowElement(id, "eventSubProcess", options);
-        if (element.type === "eventSubProcess") {
+        const element = makeFlowElement(id, "subProcess", options);
+        if (element.type === "subProcess") {
+            element.triggeredByEvent = true;
             element.flowElements = sub._elements;
             element.sequenceFlows = sub._flows;
+            element.textAnnotations = sub._textAnnotations;
+            element.associations = sub._associations;
         }
-        this.addFlowElement(element);
+        // Event sub-processes have no incoming/outgoing sequence flows and must not
+        // advance the flow cursor — the surrounding process wires around them.
+        // openBranchEnds is intentionally NOT drained here; the next normal
+        // addFlowElement call will drain it and connect branch ends to that element.
+        if (this.flowElements.some((n) => n.id === element.id)) {
+            throw new Error(`Duplicate element ID "${element.id}" in process "${this.processId}"`);
+        }
+        this._savedMainFlowId = undefined;
+        this.flowElements.push(element);
+        return this;
+    }
+    // ---- Annotations ----
+    /** Attach a text annotation to the element at the current cursor position. */
+    textAnnotation(text) {
+        if (!this.lastNodeId) {
+            throw new Error("textAnnotation() must follow a flow element");
+        }
+        return this.annotate(this.lastNodeId, text);
+    }
+    /** Attach a text annotation to any flow element by explicit ID. */
+    annotate(elementId, text) {
+        const n = (this._annCounters.get(elementId) ?? 0) + 1;
+        this._annCounters.set(elementId, n);
+        const annId = `TextAnnotation_${elementId}_${n}`;
+        this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
+        this._associations.push({
+            id: `Association_${elementId}_${n}`,
+            sourceRef: elementId,
+            targetRef: annId,
+            associationDirection: "None",
+            unknownAttributes: {},
+        });
         return this;
     }
     // ---- Build ----
@@ -1030,8 +1357,17 @@ export class ProcessBuilder {
      * Resolves all forward-referenced `incoming` / `outgoing` arrays and wraps
      * the process in a {@link BpmnDefinitions} ready for XML serialization.
      */
-    build() {
-        this.insertJoinGateways();
+    build(options) {
+        const beforeCount = this.flowElements.length;
+        insertJoinGateways(this.flowElements, this.sequenceFlows);
+        if (options?.strict && this.flowElements.length > beforeCount) {
+            const inserted = this.flowElements
+                .slice(beforeCount)
+                .map((e) => e.id)
+                .join(", ");
+            throw new Error(`auto-join gateways were inserted: ${inserted}. Use explicit .connectTo(joinId) to make gateway topology explicit, or remove { strict: true }.`);
+        }
+        this.validate();
         recomputeIncomingOutgoing(this.flowElements, this.sequenceFlows);
         const extensionElements = [];
         if (this._versionTag) {
@@ -1048,15 +1384,15 @@ export class ProcessBuilder {
             extensionElements,
             flowElements: this.flowElements,
             sequenceFlows: this.sequenceFlows,
-            textAnnotations: [],
-            associations: [],
+            textAnnotations: this._textAnnotations,
+            associations: this._associations,
             unknownAttributes: {},
         };
-        return {
+        const defs = {
             id: "Definitions_1",
             targetNamespace: "http://bpmn.io/schema/bpmn",
             exporter: "@bpmnkit/core",
-            exporterVersion: "0.0.1",
+            exporterVersion: EXPORTER_VERSION,
             namespaces: {
                 bpmn: "http://www.omg.org/spec/BPMN/20100524/MODEL",
                 bpmndi: "http://www.omg.org/spec/BPMN/20100524/DI",
@@ -1068,134 +1404,67 @@ export class ProcessBuilder {
             },
             unknownAttributes: {
                 "modeler:executionPlatform": "Camunda Cloud",
-                "modeler:executionPlatformVersion": "8.6.0",
+                "modeler:executionPlatformVersion": this._executionPlatformVersion,
             },
             errors: this.rootErrors,
-            escalations: [],
+            escalations: this.rootEscalations,
             messages: this.rootMessages,
-            signals: [],
+            signals: this.rootSignals,
             collaborations: [],
             processes: [process],
-            diagrams: this._autoLayout ? [this.buildDiagram(process)] : [],
+            // Seed diagram stub so applyAutoLayout preserves process-specific IDs.
+            diagrams: this._autoLayout
+                ? [
+                    {
+                        id: `${this.processId}_di`,
+                        plane: {
+                            id: `${this.processId}_di_plane`,
+                            bpmnElement: this.processId,
+                            shapes: [],
+                            edges: [],
+                        },
+                    },
+                ]
+                : [],
         };
+        return this._autoLayout ? applyAutoLayout(defs) : defs;
     }
-    buildDiagram(process) {
-        const layoutResult = layoutProcess(process);
-        return layoutResultToDiagram(this.processId, layoutResult);
-    }
-    // ---- Internal ----
-    /**
-     * Insert matching join gateways where split-gateway branches converge
-     * on a non-gateway target. BPMN best practice: every split has a join.
-     */
-    insertJoinGateways() {
-        const GATEWAY_TYPES = new Set([
-            "exclusiveGateway",
-            "parallelGateway",
-            "inclusiveGateway",
-            "eventBasedGateway",
-        ]);
-        const elementTypes = new Map();
-        for (const el of this.flowElements) {
-            elementTypes.set(el.id, el.type);
-        }
-        // Find split gateways (2+ outgoing flows)
-        const outCount = new Map();
+    validate() {
+        const elementIds = new Set(this.flowElements.map((el) => el.id));
         for (const flow of this.sequenceFlows) {
-            outCount.set(flow.sourceRef, (outCount.get(flow.sourceRef) ?? 0) + 1);
-        }
-        const splitGateways = new Set();
-        for (const [id, count] of outCount) {
-            const type = elementTypes.get(id);
-            if (type && GATEWAY_TYPES.has(type) && count >= 2) {
-                splitGateways.add(id);
+            if (!elementIds.has(flow.targetRef)) {
+                throw new Error(`Sequence flow "${flow.id}" in process "${this.processId}" references unknown ` +
+                    `element "${flow.targetRef}". Check connectTo() calls — target must exist.`);
             }
-        }
-        if (splitGateways.size === 0)
-            return;
-        // Build incoming flow map
-        const incoming = new Map();
-        for (const flow of this.sequenceFlows) {
-            const arr = incoming.get(flow.targetRef);
-            if (arr)
-                arr.push(flow);
-            else
-                incoming.set(flow.targetRef, [flow]);
-        }
-        // For each target with 2+ incoming flows, check if they trace back
-        // to the same split gateway → insert a join gateway if needed
-        for (const [targetId, inFlows] of incoming) {
-            if (inFlows.length < 2)
-                continue;
-            // Group incoming flows by originating split gateway
-            const splitToFlows = new Map();
-            for (const flow of inFlows) {
-                const split = this.traceBackToSplit(flow.sourceRef, splitGateways);
-                if (split) {
-                    const arr = splitToFlows.get(split);
-                    if (arr)
-                        arr.push(flow);
-                    else
-                        splitToFlows.set(split, [flow]);
-                }
-            }
-            for (const [splitId, convergingFlows] of splitToFlows) {
-                if (convergingFlows.length < 2)
-                    continue;
-                const gwType = elementTypes.get(splitId);
-                if (!gwType)
-                    continue;
-                // Don't insert if target is already a matching gateway type
-                const targetType = elementTypes.get(targetId);
-                if (targetType === gwType)
-                    continue;
-                const joinId = `${splitId}_join`;
-                if (elementTypes.has(joinId))
-                    continue;
-                const joinElement = makeFlowElement(joinId, gwType, {});
-                this.flowElements.push(joinElement);
-                elementTypes.set(joinId, gwType);
-                // Re-route converging flows to the join gateway
-                for (const flow of convergingFlows) {
-                    flow.targetRef = joinId;
-                }
-                // Add flow from join to original target
-                this.sequenceFlows.push({
-                    id: generateId("Flow"),
-                    sourceRef: joinId,
-                    targetRef: targetId,
-                    extensionElements: [],
-                    unknownAttributes: {},
-                });
+            if (!elementIds.has(flow.sourceRef)) {
+                throw new Error(`Sequence flow "${flow.id}" in process "${this.processId}" references unknown ` +
+                    `source element "${flow.sourceRef}".`);
             }
         }
     }
-    /** Trace backward from a node to find which split gateway it belongs to. */
-    traceBackToSplit(nodeId, splitGateways) {
-        const visited = new Set();
-        let current = nodeId;
-        while (current) {
-            if (visited.has(current))
-                return undefined;
-            visited.add(current);
-            if (splitGateways.has(current))
-                return current;
-            // Follow single incoming flow backward
-            const inFlows = this.sequenceFlows.filter((f) => f.targetRef === current);
-            if (inFlows.length !== 1)
-                return undefined;
-            const prev = inFlows[0];
-            if (!prev)
-                return undefined;
-            current = prev.sourceRef;
-        }
-        return undefined;
-    }
     addFlowElement(element) {
         if (this.flowElements.some((n) => n.id === element.id)) {
             throw new Error(`Duplicate element ID "${element.id}" in process "${this.processId}"`);
         }
         this.flowElements.push(element);
+        // Compensation handlers are outside the normal token flow: link via association
+        // from the preceding compensation boundary event, then restore the main-flow cursor.
+        if (element.isForCompensation) {
+            if (this.lastNodeId) {
+                this._associations.push({
+                    id: generateId("Association"),
+                    sourceRef: this.lastNodeId,
+                    targetRef: element.id,
+                    associationDirection: "One",
+                    unknownAttributes: {},
+                });
+            }
+            // Restore main-flow cursor (saved by boundaryEvent() when compensation: true)
+            this.lastNodeId = this._savedMainFlowId;
+            this._savedMainFlowId = undefined;
+            // Do NOT connect open branch ends — handler is outside normal flow
+            return;
+        }
         if (this.lastNodeId) {
             const flowId = generateId("Flow");
             this.sequenceFlows.push({
@@ -1218,7 +1487,69 @@ export class ProcessBuilder {
             });
         }
         this.openBranchEnds = [];
+        // Clear any saved compensation cursor — a normal element advancing the cursor
+        // means the compensation boundary/handler pattern has been interrupted.
+        this._savedMainFlowId = undefined;
         this.lastNodeId = element.id;
     }
 }
+// ---------------------------------------------------------------------------
+// Diagram builder — multi-process support
+// ---------------------------------------------------------------------------
+/**
+ * Builder for a complete BPMN definitions document containing one or more processes.
+ * Use `Bpmn.createDiagram(id?)` to obtain an instance.
+ */
+export class DiagramBuilder {
+    _id;
+    _processes = [];
+    _errors = [];
+    _messages = [];
+    _executionPlatformVersion = "8.9.0";
+    constructor(id) {
+        this._id = id;
+    }
+    /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
+    executionPlatformVersion(version) {
+        this._executionPlatformVersion = version;
+        return this;
+    }
+    process(id, callback) {
+        const builder = new ProcessBuilder(id);
+        callback(builder);
+        const defs = builder.build();
+        this._processes.push(...defs.processes);
+        this._errors.push(...defs.errors);
+        this._messages.push(...defs.messages);
+        return this;
+    }
+    build() {
+        return {
+            id: this._id,
+            targetNamespace: "http://bpmn.io/schema/bpmn",
+            exporter: "@bpmnkit/core",
+            exporterVersion: EXPORTER_VERSION,
+            namespaces: {
+                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",
+                zeebe: "http://camunda.org/schema/zeebe/1.0",
+                modeler: "http://camunda.org/schema/modeler/1.0",
+                xsi: "http://www.w3.org/2001/XMLSchema-instance",
+            },
+            unknownAttributes: {
+                "modeler:executionPlatform": "Camunda Cloud",
+                "modeler:executionPlatformVersion": this._executionPlatformVersion,
+            },
+            errors: this._errors,
+            escalations: [],
+            messages: this._messages,
+            signals: [],
+            collaborations: [],
+            processes: this._processes,
+            diagrams: [],
+        };
+    }
+}
 //# sourceMappingURL=bpmn-builder.js.map