@bpmnkit/core 0.0.24 → 0.0.26

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

@@ -1,8 +1,14 @@
-import type { BpmnAssociation, BpmnDefinitions, BpmnFlowElement, BpmnSequenceFlow, BpmnTextAnnotation } from "./bpmn-model.js";
+import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
 import type { RestConnectorConfig } from "./rest-connector.js";
 /** Options shared by all element methods. */
 export interface ElementOptions {
     name?: string;
+    isForCompensation?: boolean;
+}
+/** Options for send/receive task elements. */
+export interface MessageTaskOptions extends ElementOptions {
+    /** Message name — generates or reuses a root <bpmn:message> and sets messageRef. */
+    messageName?: string;
 }
 /** Options for creating a start event. */
 export interface StartEventOptions extends ElementOptions {
@@ -25,6 +31,11 @@ export interface StartEventOptions extends ElementOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /**
+     * Non-interrupting flag — only meaningful for start events inside event sub-processes.
+     * Pass `false` to emit `isInterrupting="false"`. Omit for the default interrupting behavior.
+     */
+    isInterrupting?: boolean;
 }
 /** Options for creating a service task. */
 export interface ServiceTaskOptions {
@@ -53,6 +64,8 @@ export interface ServiceTaskOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a script task. */
 export interface ScriptTaskOptions {
@@ -62,6 +75,8 @@ export interface ScriptTaskOptions {
     expression: string;
     /** Variable name to store the result. */
     resultVariable: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a user task. */
 export interface UserTaskOptions {
@@ -71,6 +86,8 @@ export interface UserTaskOptions {
     formId?: string;
     /** Emit <zeebe:userTask /> to mark as a Camunda 8 native user task. */
     zeebeUserTask?: boolean;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a call activity. */
 export interface CallActivityOptions {
@@ -80,6 +97,8 @@ export interface CallActivityOptions {
     processId: string;
     /** Whether to propagate all child variables. */
     propagateAllChildVariables?: boolean;
+    /** Mark this activity as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a business rule task. */
 export interface BusinessRuleTaskOptions {
@@ -91,6 +110,8 @@ export interface BusinessRuleTaskOptions {
     decisionId?: string;
     /** Variable to store the result. */
     resultVariable?: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for gateway elements. */
 export interface GatewayOptions extends ElementOptions {
@@ -118,12 +139,16 @@ export interface IntermediateThrowEventOptions extends ElementOptions {
     signalName?: string;
     /** Escalation code — creates an escalation throw event (aspirational). */
     escalationCode?: string;
+    /** Emit a compensateEventDefinition. */
+    compensation?: boolean;
+    /** Activity to compensate (activityRef attribute on compensateEventDefinition). */
+    activityRef?: string;
 }
 /** Options for an end event. */
 export interface EndEventOptions extends ElementOptions {
     /** Error code — creates an error end event. */
     errorCode?: string;
-    /** Error reference ID. */
+    /** Error code — creates an error end event. Alias for errorCode. */
     errorRef?: string;
     /** Message name — creates a message end event. */
     messageName?: string;
@@ -140,7 +165,7 @@ export interface BoundaryEventOptions extends ElementOptions {
     cancelActivity?: boolean;
     /** Error code — creates an error boundary event. */
     errorCode?: string;
-    /** Error reference ID. */
+    /** Error code — creates an error boundary event. Alias for errorCode. */
     errorRef?: string;
     /** Timer duration — creates a timer boundary event (aspirational). */
     timerDuration?: string;
@@ -152,6 +177,8 @@ export interface BoundaryEventOptions extends ElementOptions {
     messageName?: string;
     /** Signal name — creates a signal boundary event (aspirational). */
     signalName?: string;
+    /** Creates a compensation boundary event. */
+    compensation?: boolean;
 }
 /** Multi-instance loop configuration. */
 export interface MultiInstanceOptions {
@@ -230,9 +257,17 @@ export declare class BranchBuilder {
     readonly _textAnnotations: BpmnTextAnnotation[];
     /** @internal */
     readonly _associations: BpmnAssociation[];
+    /** @internal – ID of the last gateway added in this branch (for nested branch() support). */
+    private currentGatewayId;
+    /** @internal – Open ends of nested branches waiting to auto-connect to the next element. */
+    private openBranchEnds;
     private readonly _annCounters;
+    private readonly rootErrors;
+    private readonly rootMessages;
+    private readonly rootSignals;
+    private readonly rootEscalations;
     /** @internal */
-    constructor(gatewayId: string, branchName: string);
+    constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[]);
     /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
     condition(expression: string): this;
     /** Mark this branch as the gateway's default (no-condition) flow. */
@@ -243,8 +278,10 @@ export declare class BranchBuilder {
      * Supports forward references (element created later) and backward references (loops).
      */
     connectTo(targetId: string): this;
-    /** @internal – ID of the last element added (or the gateway if branch is empty) */
-    get _lastNodeId(): string;
+    /** @internal – ID of the last element added (or undefined if branches are open). */
+    get _lastNodeId(): string | undefined;
+    /** @internal – Open ends of nested branches that have not yet been connected. */
+    get _openBranchEnds(): string[];
     /** Attach a text annotation to the element at the current cursor position. */
     textAnnotation(text: string): this;
     /** Attach a text annotation to an element by explicit ID. */
@@ -252,10 +289,12 @@ export declare class BranchBuilder {
     serviceTask(id: string, options: ServiceTaskOptions): this;
     userTask(id: string, options?: UserTaskOptions): this;
     scriptTask(id: string, options: ScriptTaskOptions): this;
-    sendTask(id: string, options?: ElementOptions): this;
-    receiveTask(id: string, options?: ElementOptions): this;
+    sendTask(id: string, options?: MessageTaskOptions): this;
+    receiveTask(id: string, options?: MessageTaskOptions): this;
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     startEvent(id?: string, options?: StartEventOptions): this;
     endEvent(id?: string, options?: EndEventOptions): this;
     intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
@@ -264,6 +303,32 @@ export declare class BranchBuilder {
     parallelGateway(id: string, options?: ElementOptions): this;
     inclusiveGateway(id: string, options?: GatewayOptions): this;
     eventBasedGateway(id: string, options?: ElementOptions): this;
+    /**
+     * Add a boundary event attached to an existing activity in this branch.
+     *
+     * The boundary event is NOT connected by a sequence flow — it attaches via
+     * `attachedToRef`. The builder cursor advances to the boundary event so
+     * subsequent elements chain from it. Use `withBoundary()` if you want the
+     * cursor to return to the task afterward.
+     */
+    boundaryEvent(id: string, options: BoundaryEventOptions): this;
+    /**
+     * Attach a boundary event to the preceding task and build its outgoing path,
+     * then restore the branch cursor to the preceding task so the main branch 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: string, options: Omit<BoundaryEventOptions, "attachedTo">, handler: (b: BranchBuilder) => void): this;
+    /**
+     * Create a named branch from the last gateway added inside this branch.
+     *
+     * Works identically to the top-level `ProcessBuilder.branch()` — use
+     * `.condition(expr)` or `.defaultFlow()` inside the callback, finish with
+     * `.connectTo(id)` or an `.endEvent()` to terminate the nested branch.
+     */
+    branch(name: string, callback: (b: BranchBuilder) => void): this;
 }
 /** Builder for the contents of a sub-process or ad-hoc sub-process. */
 export declare class SubProcessContentBuilder {
@@ -279,6 +344,9 @@ export declare class SubProcessContentBuilder {
     private lastNodeId;
     private currentGatewayId;
     private openBranchEnds;
+    private readonly rootMessages;
+    /** @internal */
+    constructor(rootMessages?: BpmnMessage[]);
     private addElement;
     startEvent(id?: string, options?: StartEventOptions): this;
     endEvent(id?: string, options?: EndEventOptions): this;
@@ -289,8 +357,10 @@ export declare class SubProcessContentBuilder {
     userTask(id: string, options?: UserTaskOptions): this;
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     callActivity(id: string, options: CallActivityOptions): this;
-    sendTask(id: string, options?: ElementOptions): this;
-    receiveTask(id: string, options?: ElementOptions): this;
+    sendTask(id: string, options?: MessageTaskOptions): this;
+    receiveTask(id: string, options?: MessageTaskOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     exclusiveGateway(id: string, options?: GatewayOptions): this;
     parallelGateway(id: string, options?: ElementOptions): this;
     inclusiveGateway(id: string, options?: GatewayOptions): this;
@@ -313,6 +383,8 @@ export declare class ProcessBuilder {
     private readonly sequenceFlows;
     private readonly rootErrors;
     private readonly rootMessages;
+    private readonly rootSignals;
+    private readonly rootEscalations;
     private readonly _textAnnotations;
     private readonly _associations;
     private readonly _annCounters;
@@ -322,6 +394,7 @@ export declare class ProcessBuilder {
     private _autoLayout;
     private _executionPlatformVersion;
     private _serviceTaskDefaults;
+    private _savedMainFlowId;
     constructor(processId: string);
     /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
     withAutoLayout(): this;
@@ -386,13 +459,15 @@ export declare class ProcessBuilder {
     /** Add a user task with optional form reference. */
     userTask(id: string, options?: UserTaskOptions): this;
     /** Add a send task (aspirational). */
-    sendTask(id: string, options?: ElementOptions): this;
+    sendTask(id: string, options?: MessageTaskOptions): this;
     /** Add a receive task (aspirational). */
-    receiveTask(id: string, options?: ElementOptions): this;
+    receiveTask(id: string, options?: MessageTaskOptions): this;
     /** Add a business rule task. */
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     /** Add a call activity referencing another process. */
     callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     /** Add an exclusive gateway (XOR split/join). */
     exclusiveGateway(id: string, options?: GatewayOptions): this;
     /** Add a parallel gateway (AND split/join). */
@@ -432,7 +507,7 @@ export declare class ProcessBuilder {
     adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
     /** Add a sub-process (aspirational). */
     subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): 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: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
     /** Attach a text annotation to the element at the current cursor position. */
     textAnnotation(text: string): this;

package/dist/bpmn/bpmn-builder.js

@@ -7,7 +7,15 @@ const EXPORTER_VERSION = "0.0.23";
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-function buildEventDefinitions(opts, rootErrors, rootMessages) {
+function resolveMessage(messageName, rootMessages) {
+    let existing = rootMessages.find((m) => m.name === messageName);
+    if (!existing) {
+        existing = { id: generateId("Message"), name: messageName, unknownAttributes: {} };
+        rootMessages.push(existing);
+    }
+    return existing.id;
+}
+function buildEventDefinitions(opts, rootErrors, rootMessages, rootSignals, rootEscalations) {
     const defs = [];
     if (opts.timerDuration || opts.timerDate || opts.timerCycle) {
         defs.push({
@@ -18,28 +26,57 @@ 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;
-        }
+        const messageRef = rootMessages
+            ? resolveMessage(opts.messageName, rootMessages)
+            : opts.messageName;
         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;
 }
@@ -213,10 +250,12 @@ function makeServiceTaskEl(id, options) {
         extensionElements: buildServiceTaskExtensions(options),
     });
     el.unknownAttributes = unknownAttributes;
+    if (options.isForCompensation)
+        el.isForCompensation = true;
     return el;
 }
 function makeScriptTaskEl(id, options) {
-    return makeFlowElement(id, "scriptTask", {
+    const el = makeFlowElement(id, "scriptTask", {
         name: options.name,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [
@@ -228,13 +267,19 @@ function makeScriptTaskEl(id, options) {
             ],
         }),
     });
+    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 } } : {}),
     });
-    return makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
+    const el = makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
+    if (options?.isForCompensation)
+        el.isForCompensation = true;
+    return el;
 }
 function makeBusinessRuleTaskEl(id, options) {
     const ext = [];
@@ -249,19 +294,28 @@ function makeBusinessRuleTaskEl(id, options) {
             },
         }));
     }
-    return makeFlowElement(id, "businessRuleTask", { name: options?.name, extensionElements: ext });
+    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);
     }
-    return makeFlowElement(id, "callActivity", {
+    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);
@@ -332,15 +386,17 @@ function insertJoinGateways(elements, flows) {
             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 === gwType)
+            if (targetType === joinType)
                 continue;
             const joinId = `${splitId}_join`;
             if (elementTypes.has(joinId))
                 continue;
-            const joinElement = makeFlowElement(joinId, gwType, {});
+            const joinElement = makeFlowElement(joinId, joinType, {});
             elements.push(joinElement);
-            elementTypes.set(joinId, gwType);
+            elementTypes.set(joinId, joinType);
             for (const flow of convergingFlows)
                 flow.targetRef = joinId;
             flows.push({
@@ -400,12 +456,24 @@ export class BranchBuilder {
     _textAnnotations = [];
     /** @internal */
     _associations = [];
+    /** @internal – ID of the last gateway added in this branch (for nested branch() support). */
+    currentGatewayId;
+    /** @internal – Open ends of nested branches waiting to auto-connect to the next element. */
+    openBranchEnds = [];
     _annCounters = new Map();
+    rootErrors;
+    rootMessages;
+    rootSignals;
+    rootEscalations;
     /** @internal */
-    constructor(gatewayId, branchName) {
+    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) {
@@ -419,22 +487,34 @@ export class BranchBuilder {
     }
     addElement(element) {
         this._elements.push(element);
-        const flowId = generateId("Flow");
-        const flow = {
-            id: flowId,
-            sourceRef: this.lastNodeId,
-            targetRef: element.id,
-            name: this.isFirstElement ? this.branchName : undefined,
-            conditionExpression: this.isFirstElement && this.pendingCondition
-                ? makeConditionExpression(this.pendingCondition)
-                : undefined,
-            extensionElements: [],
-            unknownAttributes: {},
-        };
-        this._flows.push(flow);
-        if (this.isFirstElement && this.pendingDefault) {
-            this._defaultFlowId = flowId;
+        if (this.lastNodeId) {
+            const flowId = generateId("Flow");
+            const flow = {
+                id: flowId,
+                sourceRef: this.lastNodeId,
+                targetRef: element.id,
+                name: this.isFirstElement ? this.branchName : undefined,
+                conditionExpression: this.isFirstElement && this.pendingCondition
+                    ? makeConditionExpression(this.pendingCondition)
+                    : undefined,
+                extensionElements: [],
+                unknownAttributes: {},
+            };
+            this._flows.push(flow);
+            if (this.isFirstElement && this.pendingDefault) {
+                this._defaultFlowId = flowId;
+            }
+        }
+        for (const branchEnd of this.openBranchEnds) {
+            this._flows.push({
+                id: generateId("Flow"),
+                sourceRef: branchEnd,
+                targetRef: element.id,
+                extensionElements: [],
+                unknownAttributes: {},
+            });
         }
+        this.openBranchEnds = [];
         this.isFirstElement = false;
         this.lastNodeId = element.id;
         return this;
@@ -447,6 +527,7 @@ export class BranchBuilder {
         const flowId = generateId("Flow");
         const flow = {
             id: flowId,
+            // biome-ignore lint/style/noNonNullAssertion: lastNodeId starts as gatewayId and is always defined in pre-branch context
             sourceRef: this.lastNodeId,
             targetRef: targetId,
             name: this.isFirstElement ? this.branchName : undefined,
@@ -465,13 +546,18 @@ export class BranchBuilder {
         this._connected = true;
         return this;
     }
-    /** @internal – ID of the last element added (or the gateway if branch is empty) */
+    /** @internal – ID of the last element added (or undefined if branches are open). */
     get _lastNodeId() {
         return this.lastNodeId;
     }
+    /** @internal – Open ends of nested branches that have not yet been connected. */
+    get _openBranchEnds() {
+        return this.openBranchEnds;
+    }
     // ---- Annotations ----
     /** Attach a text annotation to the element at the current cursor position. */
     textAnnotation(text) {
+        // biome-ignore lint/style/noNonNullAssertion: lastNodeId starts as gatewayId and is always defined in pre-branch context
         return this.annotate(this.lastNodeId, text);
     }
     /** Attach a text annotation to an element by explicit ID. */
@@ -500,10 +586,20 @@ export class BranchBuilder {
         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;
+        if (options?.messageName)
+            el.messageRef = resolveMessage(options.messageName, this.rootMessages);
+        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;
+        if (options?.messageName)
+            el.messageRef = resolveMessage(options.messageName, this.rootMessages);
+        return this.addElement(el);
     }
     businessRuleTask(id, options) {
         return this.addElement(makeBusinessRuleTaskEl(id, options));
@@ -511,47 +607,157 @@ export class BranchBuilder {
     callActivity(id, options) {
         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) {
         const el = makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options);
         if (el.type === "endEvent" && options) {
-            el.eventDefinitions = buildEventDefinitions(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) {
+        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));
     }
+    /**
+     * Add a boundary event attached to an existing activity in this branch.
+     *
+     * The boundary event is NOT connected by a sequence flow — it attaches via
+     * `attachedToRef`. The builder cursor advances to the boundary event so
+     * subsequent elements chain from it. Use `withBoundary()` if you want the
+     * cursor to return to the task afterward.
+     */
+    boundaryEvent(id, options) {
+        const element = makeFlowElement(id, "boundaryEvent", options);
+        if (element.type === "boundaryEvent") {
+            element.attachedToRef = options.attachedTo;
+            element.cancelActivity = options.cancelActivity;
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
+        }
+        // Push directly — no sequence flow, boundary events attach via attachedToRef
+        this._elements.push(element);
+        this.lastNodeId = element.id;
+        this.isFirstElement = false;
+        return this;
+    }
+    /**
+     * Attach a boundary event to the preceding task and build its outgoing path,
+     * then restore the branch cursor to the preceding task so the main branch 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 || attachedTo === this.gatewayId) {
+            throw new Error("withBoundary() must follow a task element inside the branch. Current builder position has no active task.");
+        }
+        const attachedEl = this._elements.find((n) => n.id === attachedTo);
+        if (attachedEl?.type === "boundaryEvent") {
+            throw new Error("withBoundary() cannot attach to a boundary event. It must follow a task or activity element.");
+        }
+        const savedLast = this.lastNodeId;
+        const savedGateway = this.currentGatewayId;
+        const savedConnected = this._connected;
+        const savedOpenEnds = [...this.openBranchEnds];
+        this.openBranchEnds = [];
+        // Create and push the boundary event (no sequence flow)
+        this.boundaryEvent(id, { ...options, attachedTo });
+        // Build the boundary event's outgoing path
+        handler(this);
+        // Restore cursor to the task so the branch main flow continues
+        this.lastNodeId = savedLast;
+        this.currentGatewayId = savedGateway;
+        this._connected = savedConnected;
+        this.openBranchEnds = savedOpenEnds;
+        return this;
+    }
+    /**
+     * Create a named branch from the last gateway added inside this branch.
+     *
+     * Works identically to the top-level `ProcessBuilder.branch()` — use
+     * `.condition(expr)` or `.defaultFlow()` inside the callback, finish with
+     * `.connectTo(id)` or an `.endEvent()` to terminate the nested branch.
+     */
+    branch(name, callback) {
+        if (!this.currentGatewayId) {
+            throw new Error("branch() must be called after a gateway element");
+        }
+        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._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) {
+            const allEnds = [
+                ...(b._lastNodeId !== undefined ? [b._lastNodeId] : []),
+                ...b._openBranchEnds,
+            ];
+            for (const endId of allEnds) {
+                const endEl = this._elements.find((n) => n.id === endId);
+                if (endEl && endEl.type !== "endEvent") {
+                    this.openBranchEnds.push(endId);
+                }
+            }
+        }
+        this.lastNodeId = undefined;
+        return this;
+    }
 }
 // ---------------------------------------------------------------------------
 // Sub-process content builder
@@ -570,6 +776,11 @@ export class SubProcessContentBuilder {
     lastNodeId;
     currentGatewayId;
     openBranchEnds = [];
+    rootMessages;
+    /** @internal */
+    constructor(rootMessages = []) {
+        this.rootMessages = rootMessages;
+    }
     addElement(element) {
         if (this._elements.some((n) => n.id === element.id)) {
             throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
@@ -600,8 +811,11 @@ export class SubProcessContentBuilder {
     // ---- 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);
+            if (options.isInterrupting === false)
+                el.isInterrupting = false;
+        }
         return this.addElement(el);
     }
     endEvent(id, options) {
@@ -639,10 +853,27 @@ export class SubProcessContentBuilder {
         return this.addElement(makeCallActivityEl(id, options));
     }
     sendTask(id, options) {
-        return this.addElement(makeFlowElement(id, "sendTask", options));
+        const el = makeFlowElement(id, "sendTask", options);
+        if (options?.isForCompensation)
+            el.isForCompensation = true;
+        if (options?.messageName)
+            el.messageRef = resolveMessage(options.messageName, this.rootMessages);
+        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;
+        if (options?.messageName)
+            el.messageRef = resolveMessage(options.messageName, this.rootMessages);
+        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) {
@@ -709,10 +940,16 @@ export class SubProcessContentBuilder {
                 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);
+        if (!b._connected) {
+            const allEnds = [
+                ...(b._lastNodeId !== undefined ? [b._lastNodeId] : []),
+                ...b._openBranchEnds,
+            ];
+            for (const endId of allEnds) {
+                const endEl = this._elements.find((n) => n.id === endId);
+                if (endEl && endEl.type !== "endEvent") {
+                    this.openBranchEnds.push(endId);
+                }
             }
         }
         this.lastNodeId = undefined;
@@ -753,6 +990,8 @@ export class ProcessBuilder {
     sequenceFlows = [];
     rootErrors = [];
     rootMessages = [];
+    rootSignals = [];
+    rootEscalations = [];
     _textAnnotations = [];
     _associations = [];
     _annCounters = new Map();
@@ -762,6 +1001,7 @@ export class ProcessBuilder {
     _autoLayout = false;
     _executionPlatformVersion = "8.9.0";
     _serviceTaskDefaults = {};
+    _savedMainFlowId = undefined;
     constructor(processId) {
         this.processId = processId;
     }
@@ -811,7 +1051,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;
@@ -850,7 +1092,7 @@ export class ProcessBuilder {
         const nodeId = id ?? generateId("EndEvent");
         const element = makeFlowElement(nodeId, "endEvent", options);
         if (element.type === "endEvent" && options) {
-            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages);
+            element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
         this.addFlowElement(element);
         return this;
@@ -860,7 +1102,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;
@@ -870,7 +1112,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;
@@ -886,12 +1128,17 @@ 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;
@@ -921,6 +1168,7 @@ export class ProcessBuilder {
         this.lastNodeId = savedLast;
         this.currentGatewayId = savedGateway;
         this.openBranchEnds = savedOpenEnds;
+        this._savedMainFlowId = undefined;
         return this;
     }
     // ---- Tasks ----
@@ -971,12 +1219,22 @@ export class ProcessBuilder {
     }
     /** 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;
+        if (options?.messageName)
+            el.messageRef = resolveMessage(options.messageName, this.rootMessages);
+        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;
+        if (options?.messageName)
+            el.messageRef = resolveMessage(options.messageName, this.rootMessages);
+        this.addFlowElement(el);
         return this;
     }
     /** Add a business rule task. */
@@ -989,6 +1247,14 @@ export class ProcessBuilder {
         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) {
@@ -1036,7 +1302,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)) {
@@ -1060,10 +1326,16 @@ export class ProcessBuilder {
         }
         // Track the branch's open end so the next element auto-connects from it.
         // Skip branches that terminated at an end event (those are intentional dead-ends).
-        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);
+        if (!b._connected) {
+            const allEnds = [
+                ...(b._lastNodeId !== undefined ? [b._lastNodeId] : []),
+                ...b._openBranchEnds,
+            ];
+            for (const endId of allEnds) {
+                const endEl = this.flowElements.find((n) => n.id === endId);
+                if (endEl && endEl.type !== "endEvent") {
+                    this.openBranchEnds.push(endId);
+                }
             }
         }
         this.lastNodeId = undefined;
@@ -1102,7 +1374,7 @@ export class ProcessBuilder {
     // ---- Sub-processes ----
     /** Add an ad-hoc sub-process with optional AI agent or multi-instance configuration. */
     adHocSubProcess(id, content, options) {
-        const sub = new SubProcessContentBuilder();
+        const sub = new SubProcessContentBuilder(this.rootMessages);
         content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
@@ -1170,7 +1442,7 @@ export class ProcessBuilder {
     }
     /** Add a sub-process (aspirational). */
     subProcess(id, content, options) {
-        const sub = new SubProcessContentBuilder();
+        const sub = new SubProcessContentBuilder(this.rootMessages);
         content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
@@ -1187,20 +1459,29 @@ 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();
+        const sub = new SubProcessContentBuilder(this.rootMessages);
         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 ----
@@ -1283,9 +1564,9 @@ export class ProcessBuilder {
                 "modeler:executionPlatformVersion": this._executionPlatformVersion,
             },
             errors: this.rootErrors,
-            escalations: [],
+            escalations: this.rootEscalations,
             messages: this.rootMessages,
-            signals: [],
+            signals: this.rootSignals,
             collaborations: [],
             processes: [process],
             // Seed diagram stub so applyAutoLayout preserves process-specific IDs.
@@ -1323,6 +1604,24 @@ export class ProcessBuilder {
             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({
@@ -1345,6 +1644,9 @@ 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;
     }
 }

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

@@ -105,10 +105,12 @@ interface BpmnFlowNodeBase {
     documentation?: string;
     extensionElements: XmlElement[];
     unknownAttributes: Record<string, string>;
+    isForCompensation?: boolean;
 }
 export interface BpmnStartEvent extends BpmnFlowNodeBase {
     type: "startEvent";
     eventDefinitions: BpmnEventDefinition[];
+    isInterrupting?: boolean;
 }
 export interface BpmnEndEvent extends BpmnFlowNodeBase {
     type: "endEvent";
@@ -150,10 +152,12 @@ export interface BpmnCallActivity extends BpmnFlowNodeBase {
 }
 export interface BpmnSendTask extends BpmnFlowNodeBase {
     type: "sendTask";
+    messageRef?: string;
     loopCharacteristics?: BpmnMultiInstanceLoopCharacteristics;
 }
 export interface BpmnReceiveTask extends BpmnFlowNodeBase {
     type: "receiveTask";
+    messageRef?: string;
     loopCharacteristics?: BpmnMultiInstanceLoopCharacteristics;
 }
 export interface BpmnAdHocSubProcess extends BpmnFlowNodeBase {

package/dist/bpmn/bpmn-parser.js

@@ -42,6 +42,7 @@ const KNOWN_ATTRS = new Set([
     "default",
     "attachedToRef",
     "cancelActivity",
+    "isForCompensation",
     "sourceRef",
     "targetRef",
     "associationDirection",
@@ -275,7 +276,15 @@ function parseFlowElement(element) {
         unknownAttributes: unknownAttrs(element),
     };
     switch (ln) {
-        case "startEvent":
+        case "startEvent": {
+            const isInterruptingAttr = attr(element, "isInterrupting");
+            return {
+                ...base,
+                type: "startEvent",
+                eventDefinitions: parseEventDefinitions(element),
+                ...(isInterruptingAttr === "false" ? { isInterrupting: false } : {}),
+            };
+        }
         case "endEvent":
         case "intermediateCatchEvent":
         case "intermediateThrowEvent":
@@ -294,12 +303,24 @@ function parseFlowElement(element) {
         case "serviceTask":
         case "scriptTask":
         case "userTask":
-        case "sendTask":
-        case "receiveTask":
         case "businessRuleTask":
         case "manualTask":
         case "callActivity":
-            return { ...base, type: ln, loopCharacteristics: parseLoopCharacteristics(element) };
+            return {
+                ...base,
+                type: ln,
+                loopCharacteristics: parseLoopCharacteristics(element),
+                isForCompensation: attr(element, "isForCompensation") === "true" ? true : undefined,
+            };
+        case "sendTask":
+        case "receiveTask":
+            return {
+                ...base,
+                type: ln,
+                messageRef: attr(element, "messageRef"),
+                loopCharacteristics: parseLoopCharacteristics(element),
+                isForCompensation: attr(element, "isForCompensation") === "true" ? true : undefined,
+            };
         case "adHocSubProcess":
             return {
                 ...base,

package/dist/bpmn/bpmn-serializer.js

@@ -157,6 +157,8 @@ function serializeFlowElement(fe, ns) {
     const attrs = { id: fe.id, ...fe.unknownAttributes };
     if (fe.name !== undefined)
         attrs.name = fe.name;
+    if (fe.isForCompensation)
+        attrs.isForCompensation = "true";
     const children = [];
     // Documentation
     if (fe.documentation !== undefined) {
@@ -169,6 +171,10 @@ function serializeFlowElement(fe, ns) {
     children.push(...flowRefs(fe.outgoing, "outgoing", bp));
     switch (fe.type) {
         case "startEvent":
+            if (fe.isInterrupting === false)
+                attrs.isInterrupting = "false";
+            children.push(...serializeEventDefinitions(fe.eventDefinitions, bp));
+            break;
         case "endEvent":
         case "intermediateCatchEvent":
         case "intermediateThrowEvent":
@@ -184,13 +190,17 @@ function serializeFlowElement(fe, ns) {
         case "serviceTask":
         case "scriptTask":
         case "userTask":
-        case "sendTask":
-        case "receiveTask":
         case "businessRuleTask":
         case "manualTask":
         case "callActivity":
             children.push(...serializeLoopCharacteristics(fe.loopCharacteristics, bp));
             break;
+        case "sendTask":
+        case "receiveTask":
+            if (fe.messageRef)
+                attrs.messageRef = fe.messageRef;
+            children.push(...serializeLoopCharacteristics(fe.loopCharacteristics, bp));
+            break;
         case "adHocSubProcess":
             children.push(...serializeLoopCharacteristics(fe.loopCharacteristics, bp));
             children.push(...serializeProcessContents(fe, ns));

package/dist/layout/layout-engine.js

@@ -36,6 +36,7 @@ function repositionBoundaryEvents(flowElements, result) {
         ps.add(edge.sourceRef);
         predIds.set(edge.targetRef, ps);
     }
+    const allChainNodes = new Set();
     for (const [hostId, beIds] of boundaryMap) {
         const hostNode = nodeById.get(hostId);
         if (!hostNode)
@@ -72,6 +73,9 @@ function repositionBoundaryEvents(flowElements, result) {
                     queue.push(...(succIds.get(id) ?? []));
                 }
             }
+            // Record all chain members so the forward pass can identify them.
+            for (const cid of chainSet)
+                allChainNodes.add(cid);
             // Each boundary event's chain gets its own vertical lane
             let maxChainH = 0;
             for (const id of chainOrder) {
@@ -133,6 +137,116 @@ function repositionBoundaryEvents(flowElements, result) {
             }
         }
     }
+    // Forward-placement pass: any node not in any chain but whose predecessor
+    // has been relocated further right must be pushed rightward.
+    // Process in topological order (Kahn's algorithm over the sequenceFlow graph).
+    const inDegree = new Map();
+    for (const id of nodeById.keys()) {
+        inDegree.set(id, (predIds.get(id) ?? new Set()).size);
+    }
+    const topoQueue = [];
+    for (const [id, deg] of inDegree) {
+        if (deg === 0)
+            topoQueue.push(id);
+    }
+    const topoOrder = [];
+    while (topoQueue.length > 0) {
+        const id = topoQueue.shift();
+        if (!id)
+            break;
+        topoOrder.push(id);
+        for (const succId of succIds.get(id) ?? []) {
+            const newDeg = (inDegree.get(succId) ?? 1) - 1;
+            inDegree.set(succId, newDeg);
+            if (newDeg === 0)
+                topoQueue.push(succId);
+        }
+    }
+    const movedInPass = new Set();
+    for (const id of topoOrder) {
+        if (allChainNodes.has(id))
+            continue;
+        const node = nodeById.get(id);
+        if (!node)
+            continue;
+        const preds = predIds.get(id) ?? new Set();
+        if (preds.size === 0)
+            continue;
+        let maxPredRight = 0;
+        for (const predId of preds) {
+            const pred = nodeById.get(predId);
+            if (pred)
+                maxPredRight = Math.max(maxPredRight, pred.bounds.x + pred.bounds.width);
+        }
+        const minX = maxPredRight + CHAIN_GAP;
+        if (minX > node.bounds.x) {
+            const delta = minX - node.bounds.x;
+            node.bounds.x = minX;
+            if (node.labelBounds)
+                node.labelBounds.x += delta;
+            movedInPass.add(id);
+        }
+    }
+    // Spatial bump: if a moved node now overlaps a non-chain node on a parallel
+    // path (no predecessor/successor relationship), push it clear and cascade.
+    let bumped = true;
+    while (bumped) {
+        bumped = false;
+        for (const movedId of movedInPass) {
+            const moved = nodeById.get(movedId);
+            if (!moved)
+                continue;
+            const movedRight = moved.bounds.x + moved.bounds.width;
+            for (const [otherId, other] of nodeById) {
+                if (otherId === movedId)
+                    continue;
+                if (allChainNodes.has(otherId))
+                    continue;
+                if (movedInPass.has(otherId))
+                    continue;
+                // Check y overlap
+                if (other.bounds.y + other.bounds.height <= moved.bounds.y)
+                    continue;
+                if (other.bounds.y >= moved.bounds.y + moved.bounds.height)
+                    continue;
+                // Check x overlap (moved node intrudes into other's space)
+                if (other.bounds.x >= movedRight)
+                    continue;
+                if (other.bounds.x + other.bounds.width <= moved.bounds.x)
+                    continue;
+                // Push other right of moved
+                const newX = movedRight + CHAIN_GAP;
+                if (newX > other.bounds.x) {
+                    const delta = newX - other.bounds.x;
+                    other.bounds.x = newX;
+                    if (other.labelBounds)
+                        other.labelBounds.x += delta;
+                    movedInPass.add(otherId);
+                    bumped = true;
+                }
+            }
+        }
+    }
+    // Re-route edges where a chain source now points at a moved target,
+    // or where the source itself was moved by the forward pass.
+    for (const edge of result.edges) {
+        const srcMoved = movedInPass.has(edge.sourceRef);
+        const tgtMoved = movedInPass.has(edge.targetRef);
+        if (!srcMoved && !tgtMoved)
+            continue;
+        const src = nodeById.get(edge.sourceRef);
+        const tgt = nodeById.get(edge.targetRef);
+        if (!src || !tgt)
+            continue;
+        const srcX = Math.round(src.bounds.x + src.bounds.width);
+        const srcY = Math.round(src.bounds.y + src.bounds.height / 2);
+        const tgtX = Math.round(tgt.bounds.x);
+        const tgtY = Math.round(tgt.bounds.y + tgt.bounds.height / 2);
+        edge.waypoints = [
+            { x: srcX, y: srcY },
+            { x: tgtX, y: tgtY },
+        ];
+    }
 }
 /**
  * Auto-layout a BPMN process using the Sugiyama/layered algorithm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/core",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",