@bpmnkit/core 0.0.23 → 0.0.24

package/dist/bpmn/bpmn-builder.js

@@ -1,7 +1,9 @@
-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
 // ---------------------------------------------------------------------------
@@ -155,46 +157,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 +198,181 @@ 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;
+    return el;
+}
+function makeScriptTaskEl(id, options) {
+    return makeFlowElement(id, "scriptTask", {
+        name: options.name,
+        extensionElements: zeebeExtensionsToXmlElements({
+            unknownElements: [
+                {
+                    name: "zeebe:script",
+                    attributes: { expression: options.expression, resultVariable: options.resultVariable },
+                    children: [],
+                },
+            ],
+        }),
+    });
+}
+function makeUserTaskEl(id, options) {
+    const ext = zeebeExtensionsToXmlElements({
+        ...(options?.zeebeUserTask ? { userTask: true } : {}),
+        ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
+    });
+    return makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
+}
+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",
+            },
+        }));
+    }
+    return makeFlowElement(id, "businessRuleTask", { name: options?.name, extensionElements: ext });
+}
+function makeCallActivityEl(id, options) {
+    const attrs = { processId: options.processId };
+    if (options.propagateAllChildVariables !== undefined) {
+        attrs.propagateAllChildVariables = String(options.propagateAllChildVariables);
+    }
+    return makeFlowElement(id, "callActivity", {
+        name: options.name,
+        extensionElements: zeebeExtensionsToXmlElements({
+            unknownElements: [{ name: "zeebe:calledElement", attributes: attrs, children: [] }],
+        }),
+    });
+}
+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;
+            const targetType = elementTypes.get(targetId);
+            if (targetType === gwType)
+                continue;
+            const joinId = `${splitId}_join`;
+            if (elementTypes.has(joinId))
+                continue;
+            const joinElement = makeFlowElement(joinId, gwType, {});
+            elements.push(joinElement);
+            elementTypes.set(joinId, gwType);
+            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,6 +397,11 @@ export class BranchBuilder {
     /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
     _connected = false;
     /** @internal */
+    _textAnnotations = [];
+    /** @internal */
+    _associations = [];
+    _annCounters = new Map();
+    /** @internal */
     constructor(gatewayId, branchName) {
         this.gatewayId = gatewayId;
         this.branchName = branchName;
@@ -327,47 +469,35 @@ 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));
@@ -376,36 +506,10 @@ export class BranchBuilder {
         return this.addElement(makeFlowElement(id, "receiveTask", options));
     }
     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));
     }
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
@@ -416,7 +520,11 @@ export class BranchBuilder {
         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);
+        }
+        return this.addElement(el);
     }
     intermediateThrowEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
@@ -433,23 +541,13 @@ export class BranchBuilder {
         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,98 +562,182 @@ 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) {
+        if (el.type === "startEvent" && options)
             el.eventDefinitions = buildEventDefinitions(options);
-        }
         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);
+        return this.addElement(el);
     }
-    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;
+    intermediateThrowEvent(id, options) {
+        const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
+        if (el.type === "intermediateThrowEvent" && options)
+            el.eventDefinitions = buildEventDefinitions(options);
         return this.addElement(el);
     }
-    userTask(id, options) {
-        return this.addElement(makeFlowElement(id, "userTask", { name: options?.name }));
+    intermediateCatchEvent(id, options) {
+        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "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(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));
+    }
+    userTask(id, options) {
+        return this.addElement(makeUserTaskEl(id, options));
+    }
+    businessRuleTask(id, options) {
+        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(makeCallActivityEl(id, options));
+    }
+    sendTask(id, options) {
+        return this.addElement(makeFlowElement(id, "sendTask", options));
+    }
+    receiveTask(id, options) {
+        return this.addElement(makeFlowElement(id, "receiveTask", options));
+    }
+    // ---- 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.addElement(makeFlowElement(id, "callActivity", {
-            name: options.name,
-            extensionElements: zeebeExtensionsToXmlElements({
-                unknownElements: [
-                    {
-                        name: "zeebe:calledElement",
-                        attributes: attrs,
-                        children: [],
-                    },
-                ],
-            }),
-        }));
+        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;
     }
-    intermediateThrowEvent(id, options) {
-        const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
-        if (el.type === "intermediateThrowEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+    // ---- Branching & flow control ----
+    branch(name, callback) {
+        if (!this.currentGatewayId) {
+            throw new Error("branch() must be called after a gateway element");
         }
-        return this.addElement(el);
+        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;
     }
-    intermediateCatchEvent(id, options) {
-        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
-        if (el.type === "intermediateCatchEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(options);
+    connectTo(targetId) {
+        if (this.lastNodeId) {
+            this._flows.push({
+                id: generateId("Flow"),
+                sourceRef: this.lastNodeId,
+                targetRef: targetId,
+                extensionElements: [],
+                unknownAttributes: {},
+            });
         }
-        return this.addElement(el);
+        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;
     }
 }
 // ---------------------------------------------------------------------------
@@ -571,10 +753,15 @@ export class ProcessBuilder {
     sequenceFlows = [];
     rootErrors = [];
     rootMessages = [];
+    _textAnnotations = [];
+    _associations = [];
+    _annCounters = new Map();
     lastNodeId;
     currentGatewayId;
     openBranchEnds = [];
     _autoLayout = false;
+    _executionPlatformVersion = "8.9.0";
+    _serviceTaskDefaults = {};
     constructor(processId) {
         this.processId = processId;
     }
@@ -583,6 +770,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;
@@ -639,10 +837,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.addFlowElement(element);
         return this;
     }
     /** Add an intermediate throw event (none, message, signal, escalation). */
@@ -686,22 +896,41 @@ export class ProcessBuilder {
         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;
+        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,32 +961,12 @@ 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). */
@@ -772,55 +981,18 @@ export class ProcessBuilder {
     }
     /** 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;
     }
     // ---- 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 +1004,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;
     }
@@ -880,6 +1047,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 +1104,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 +1156,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 +1172,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);
             }
@@ -1014,15 +1191,41 @@ export class ProcessBuilder {
     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") {
             element.flowElements = sub._elements;
             element.sequenceFlows = sub._flows;
+            element.textAnnotations = sub._textAnnotations;
+            element.associations = sub._associations;
         }
         this.addFlowElement(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 ----
     /**
      * Build the complete BPMN definitions model.
@@ -1030,8 +1233,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 +1260,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,7 +1280,7 @@ export class ProcessBuilder {
             },
             unknownAttributes: {
                 "modeler:executionPlatform": "Camunda Cloud",
-                "modeler:executionPlatformVersion": "8.6.0",
+                "modeler:executionPlatformVersion": this._executionPlatformVersion,
             },
             errors: this.rootErrors,
             escalations: [],
@@ -1076,121 +1288,36 @@ export class ProcessBuilder {
             signals: [],
             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();
-        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 (splitGateways.size === 0)
-            return;
-        // Build incoming flow map
-        const incoming = new Map();
+    validate() {
+        const elementIds = new Set(this.flowElements.map((el) => el.id));
         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]);
-                }
+            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.`);
             }
-            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}"`);
@@ -1221,4 +1348,63 @@ export class ProcessBuilder {
         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