@bpmnkit/core 1.4.1 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/dist/bpmn/agentic.d.ts +9 -2
  2. package/dist/bpmn/agentic.js +8 -3
  3. package/dist/bpmn/auto-layout.d.ts +7 -2
  4. package/dist/bpmn/auto-layout.js +111 -7
  5. package/dist/bpmn/bpmn-builder.d.ts +99 -5
  6. package/dist/bpmn/bpmn-builder.js +203 -69
  7. package/dist/bpmn/compact.d.ts +24 -0
  8. package/dist/bpmn/compact.js +78 -4
  9. package/dist/bpmn/full-operations.js +20 -0
  10. package/dist/bpmn/optimize/patterns.js +2 -2
  11. package/dist/bpmn/optimize/variable-flow.d.ts +1 -0
  12. package/dist/bpmn/optimize/variable-flow.js +1 -1
  13. package/dist/bpmn/process-delta.d.ts +21 -1
  14. package/dist/bpmn/process-delta.js +33 -3
  15. package/dist/bpmn/process-text-writer.js +80 -6
  16. package/dist/bpmn/process-text.d.ts +22 -1
  17. package/dist/bpmn/process-text.js +268 -9
  18. package/dist/bpmn/stable-ids.d.ts +11 -0
  19. package/dist/bpmn/stable-ids.js +76 -10
  20. package/dist/connectors/apply-many.d.ts +49 -0
  21. package/dist/connectors/apply-many.js +162 -0
  22. package/dist/connectors/index.d.ts +2 -0
  23. package/dist/connectors/index.js +1 -0
  24. package/dist/connectors/lines.d.ts +1 -1
  25. package/dist/connectors/lines.js +13 -3
  26. package/dist/connectors/select.d.ts +2 -0
  27. package/dist/connectors/select.js +11 -0
  28. package/dist/index.d.ts +3 -3
  29. package/dist/layout/annotations.d.ts +3 -1
  30. package/dist/layout/annotations.js +11 -4
  31. package/dist/layout/index.d.ts +1 -1
  32. package/dist/layout/layout-engine.d.ts +4 -2
  33. package/dist/layout/layout-engine.js +4 -2
  34. package/dist/layout/semantic/bands.d.ts +10 -1
  35. package/dist/layout/semantic/bands.js +16 -8
  36. package/dist/layout/semantic/index.d.ts +9 -3
  37. package/dist/layout/semantic/index.js +119 -24
  38. package/dist/layout/semantic/place.d.ts +23 -3
  39. package/dist/layout/semantic/place.js +127 -7
  40. package/dist/layout/semantic/route.js +23 -12
  41. package/dist/layout/types.d.ts +18 -0
  42. package/package.json +2 -2
@@ -3,7 +3,7 @@ import { generateId } from "../types/id-generator.js";
3
3
  import { applyAutoLayout } from "./auto-layout.js";
4
4
  import { createFlowElement } from "./element-shape.js";
5
5
  import { REST_CONNECTOR_TEMPLATE_VERSION, restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
6
- import { assignStableFlowIds, rootDefinitionId } from "./stable-ids.js";
6
+ import { assertExplicitFlowIdsUnique, assignStableFlowIds, markExplicitFlowId, rootDefinitionId, setFlowDiscriminatorSource, } from "./stable-ids.js";
7
7
  import { ensureZeebeExtension, zeebeExtensionsToXmlElements, } from "./zeebe-extensions.js";
8
8
  // Keep in sync with packages/core/package.json version
9
9
  const EXPORTER_VERSION = "0.0.23";
@@ -171,8 +171,20 @@ function buildEventDefinitions(opts, rootErrors, rootMessages, rootSignals, root
171
171
  if (opts.compensation) {
172
172
  defs.push({ type: "compensate", activityRef: opts.activityRef });
173
173
  }
174
+ if (opts.linkName !== undefined) {
175
+ defs.push({ type: "link", name: opts.linkName });
176
+ }
174
177
  return defs;
175
178
  }
179
+ /**
180
+ * A link event pair is a "go-to" within one scope: the throw has no outgoing
181
+ * sequence flow and the catch no incoming one. The builders' auto-chaining has
182
+ * to stop at a throw and restart at a catch, or it fabricates exactly the flows
183
+ * that make the pair invalid.
184
+ */
185
+ function isLinkEvent(element, type) {
186
+ return element.type === type && element.eventDefinitions.some((def) => def.type === "link");
187
+ }
176
188
  /**
177
189
  * Build an empty flow element.
178
190
  *
@@ -242,13 +254,9 @@ function recomputeIncomingOutgoing(elements, flows) {
242
254
  elementMap.get(flow.targetRef)?.incoming.push(flow.id);
243
255
  }
244
256
  }
245
- function buildServiceTaskExtensions(options) {
246
- const extensions = {
247
- taskDefinition: {
248
- type: options.taskType,
249
- retries: options.retries,
250
- },
251
- };
257
+ /** The ioMapping / taskHeaders / properties extensions shared by service and user tasks. */
258
+ function buildMappingExtensions(options) {
259
+ const extensions = {};
252
260
  if (options.ioMapping) {
253
261
  extensions.ioMapping = {
254
262
  inputs: options.ioMapping.inputs ?? [],
@@ -266,6 +274,16 @@ function buildServiceTaskExtensions(options) {
266
274
  if (options.zeebeProperties) {
267
275
  extensions.properties = { properties: options.zeebeProperties };
268
276
  }
277
+ return extensions;
278
+ }
279
+ function buildServiceTaskExtensions(options) {
280
+ const extensions = {
281
+ taskDefinition: {
282
+ type: options.taskType,
283
+ retries: options.retries,
284
+ },
285
+ ...buildMappingExtensions(options),
286
+ };
269
287
  if (options.agentDefinition)
270
288
  extensions.agentDefinition = options.agentDefinition;
271
289
  return zeebeExtensionsToXmlElements(extensions);
@@ -383,6 +401,30 @@ function makeScriptTaskEl(id, options) {
383
401
  el.isForCompensation = true;
384
402
  return el;
385
403
  }
404
+ function applyModelerTemplate(el, options) {
405
+ if (options.modelerTemplate)
406
+ el.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
407
+ if (options.modelerTemplateVersion) {
408
+ el.unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
409
+ }
410
+ if (options.modelerTemplateIcon) {
411
+ el.unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
412
+ }
413
+ }
414
+ /** Start-event shell shared by all three builders; the caller adds event definitions. */
415
+ function makeStartEventEl(id, options) {
416
+ const el = makeFlowElement(id, "startEvent", {
417
+ name: options?.name,
418
+ documentation: options?.documentation,
419
+ extensionElements: zeebeExtensionsToXmlElements({
420
+ ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
421
+ ...(options?.zeebeProperties ? { properties: { properties: options.zeebeProperties } } : {}),
422
+ }),
423
+ });
424
+ if (options)
425
+ applyModelerTemplate(el, options);
426
+ return el;
427
+ }
386
428
  function makeUserTaskEl(id, options) {
387
429
  const ext = zeebeExtensionsToXmlElements({
388
430
  ...(options?.zeebeUserTask ? { userTask: true } : {}),
@@ -402,12 +444,15 @@ function makeUserTaskEl(id, options) {
402
444
  ...(options?.priority !== undefined
403
445
  ? { priorityDefinition: { priority: String(options.priority) } }
404
446
  : {}),
447
+ ...(options ? buildMappingExtensions(options) : {}),
405
448
  });
406
449
  const el = makeFlowElement(id, "userTask", {
407
450
  name: options?.name,
408
451
  documentation: options?.documentation,
409
452
  extensionElements: ext,
410
453
  });
454
+ if (options)
455
+ applyModelerTemplate(el, options);
411
456
  if (options?.isForCompensation)
412
457
  el.isForCompensation = true;
413
458
  return el;
@@ -519,6 +564,19 @@ function resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions) {
519
564
  }
520
565
  return options;
521
566
  }
567
+ function emptyLayoutHints() {
568
+ return { grids: new Map(), annotationSides: new Map() };
569
+ }
570
+ /** Remembers an ad-hoc sub-process's `toolGrid` for the layout. */
571
+ function recordToolGrid(hints, id, options) {
572
+ const grid = options?.toolGrid;
573
+ if (!grid)
574
+ return;
575
+ if (grid.columns !== undefined && !(Number.isInteger(grid.columns) && grid.columns > 0)) {
576
+ throw new Error(`adHocSubProcess("${id}"): toolGrid.columns must be a positive integer, got ${grid.columns}`);
577
+ }
578
+ hints.grids.set(id, grid);
579
+ }
522
580
  /**
523
581
  * Build a transaction element from a content callback.
524
582
  *
@@ -528,9 +586,9 @@ function resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions) {
528
586
  * unlike `subProcess`, whose cursor handling differs per class, nothing here
529
587
  * varies between them.
530
588
  */
531
- function makeTransactionEl(id, content, options, rootMessages) {
589
+ function makeTransactionEl(id, content, options, roots) {
532
590
  const resolved = resolveSubProcessArgs(content, options);
533
- const sub = new SubProcessContentBuilder(rootMessages);
591
+ const sub = new SubProcessContentBuilder(roots);
534
592
  resolved.content(sub);
535
593
  finalizeScope(sub._elements, sub._flows);
536
594
  const element = makeFlowElement(id, "transaction", resolved.options);
@@ -674,6 +732,8 @@ export class BranchBuilder {
674
732
  branchName;
675
733
  isFirstElement = true;
676
734
  pendingCondition;
735
+ pendingLabel;
736
+ pendingFlowId;
677
737
  pendingDefault = false;
678
738
  /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
679
739
  _connected = false;
@@ -690,8 +750,9 @@ export class BranchBuilder {
690
750
  rootMessages;
691
751
  rootSignals;
692
752
  rootEscalations;
753
+ rootLayoutHints;
693
754
  /** @internal */
694
- constructor(gatewayId, branchName, rootErrors = [], rootMessages = [], rootSignals = [], rootEscalations = []) {
755
+ constructor(gatewayId, branchName, rootErrors = [], rootMessages = [], rootSignals = [], rootEscalations = [], rootLayoutHints = emptyLayoutHints()) {
695
756
  this.gatewayId = gatewayId;
696
757
  this.branchName = branchName;
697
758
  this.lastNodeId = gatewayId;
@@ -699,27 +760,63 @@ export class BranchBuilder {
699
760
  this.rootMessages = rootMessages;
700
761
  this.rootSignals = rootSignals;
701
762
  this.rootEscalations = rootEscalations;
763
+ this.rootLayoutHints = rootLayoutHints;
764
+ }
765
+ roots() {
766
+ return {
767
+ errors: this.rootErrors,
768
+ messages: this.rootMessages,
769
+ signals: this.rootSignals,
770
+ escalations: this.rootEscalations,
771
+ layoutHints: this.rootLayoutHints,
772
+ };
702
773
  }
703
774
  /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
704
775
  condition(expression) {
705
776
  this.pendingCondition = expression;
706
777
  return this;
707
778
  }
779
+ /**
780
+ * Set the name shown on this branch's first flow. Without it the branch id is
781
+ * the name. The generated flow id still follows the branch id, not the label.
782
+ */
783
+ label(text) {
784
+ this.pendingLabel = text;
785
+ return this;
786
+ }
787
+ /** Use `id` for this branch's first flow instead of a generated one. */
788
+ flowId(id) {
789
+ this.pendingFlowId = id;
790
+ return this;
791
+ }
708
792
  /** Mark this branch as the gateway's default (no-condition) flow. */
709
793
  defaultFlow() {
710
794
  this.pendingDefault = true;
711
795
  return this;
712
796
  }
797
+ /** Keeps label() and flowId() out of the stable-id derivation; see stable-ids.ts. */
798
+ registerFirstFlow(flow) {
799
+ setFlowDiscriminatorSource(flow, this.branchName);
800
+ if (this.pendingFlowId !== undefined)
801
+ markExplicitFlowId(flow);
802
+ }
713
803
  addElement(element) {
714
804
  this._elements.push(element);
715
805
  this._ids.add(element.id);
806
+ if (isLinkEvent(element, "intermediateCatchEvent")) {
807
+ this.isFirstElement = false;
808
+ this.lastNodeId = element.id;
809
+ return this;
810
+ }
716
811
  if (this.lastNodeId) {
717
- const flowId = generateId("Flow");
812
+ const flowId = this.isFirstElement
813
+ ? (this.pendingFlowId ?? generateId("Flow"))
814
+ : generateId("Flow");
718
815
  const flow = {
719
816
  id: flowId,
720
817
  sourceRef: this.lastNodeId,
721
818
  targetRef: element.id,
722
- name: this.isFirstElement ? this.branchName : undefined,
819
+ name: this.isFirstElement ? (this.pendingLabel ?? this.branchName) : undefined,
723
820
  conditionExpression: this.isFirstElement && this.pendingCondition
724
821
  ? makeConditionExpression(this.pendingCondition)
725
822
  : undefined,
@@ -727,6 +824,8 @@ export class BranchBuilder {
727
824
  unknownAttributes: {},
728
825
  };
729
826
  this._flows.push(flow);
827
+ if (this.isFirstElement)
828
+ this.registerFirstFlow(flow);
730
829
  if (this.isFirstElement && this.pendingDefault) {
731
830
  this._defaultFlowId = flowId;
732
831
  }
@@ -742,7 +841,7 @@ export class BranchBuilder {
742
841
  }
743
842
  this.openBranchEnds = [];
744
843
  this.isFirstElement = false;
745
- this.lastNodeId = element.id;
844
+ this.lastNodeId = isLinkEvent(element, "intermediateThrowEvent") ? undefined : element.id;
746
845
  return this;
747
846
  }
748
847
  /**
@@ -750,13 +849,15 @@ export class BranchBuilder {
750
849
  * Supports forward references (element created later) and backward references (loops).
751
850
  */
752
851
  connectTo(targetId) {
753
- const flowId = generateId("Flow");
852
+ const flowId = this.isFirstElement
853
+ ? (this.pendingFlowId ?? generateId("Flow"))
854
+ : generateId("Flow");
754
855
  const flow = {
755
856
  id: flowId,
756
857
  // biome-ignore lint/style/noNonNullAssertion: lastNodeId starts as gatewayId and is always defined in pre-branch context
757
858
  sourceRef: this.lastNodeId,
758
859
  targetRef: targetId,
759
- name: this.isFirstElement ? this.branchName : undefined,
860
+ name: this.isFirstElement ? (this.pendingLabel ?? this.branchName) : undefined,
760
861
  conditionExpression: this.isFirstElement && this.pendingCondition
761
862
  ? makeConditionExpression(this.pendingCondition)
762
863
  : undefined,
@@ -764,6 +865,8 @@ export class BranchBuilder {
764
865
  unknownAttributes: {},
765
866
  };
766
867
  this._flows.push(flow);
868
+ if (this.isFirstElement)
869
+ this.registerFirstFlow(flow);
767
870
  if (this.isFirstElement && this.pendingDefault) {
768
871
  this._defaultFlowId = flowId;
769
872
  }
@@ -787,10 +890,12 @@ export class BranchBuilder {
787
890
  return this.annotate(this.lastNodeId, text);
788
891
  }
789
892
  /** Attach a text annotation to an element by explicit ID. */
790
- annotate(elementId, text) {
893
+ annotate(elementId, text, options) {
791
894
  const n = (this._annCounters.get(elementId) ?? 0) + 1;
792
895
  this._annCounters.set(elementId, n);
793
896
  const annId = `TextAnnotation_${elementId}_${n}`;
897
+ if (options?.side)
898
+ this.rootLayoutHints.annotationSides.set(annId, options.side);
794
899
  this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
795
900
  this._associations.push({
796
901
  id: `Association_${elementId}_${n}`,
@@ -851,7 +956,7 @@ export class BranchBuilder {
851
956
  return this.addElement(el);
852
957
  }
853
958
  startEvent(id, options) {
854
- const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
959
+ const el = makeStartEventEl(id ?? generateId("StartEvent"), options);
855
960
  if (el.type === "startEvent" && options) {
856
961
  el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
857
962
  }
@@ -964,7 +1069,7 @@ export class BranchBuilder {
964
1069
  /** Add a sub-process (mirrors `ProcessBuilder.subProcess`). */
965
1070
  subProcess(id, content, options) {
966
1071
  const resolved = resolveSubProcessArgs(content, options);
967
- const sub = new SubProcessContentBuilder(this.rootMessages);
1072
+ const sub = new SubProcessContentBuilder(this.roots());
968
1073
  resolved.content(sub);
969
1074
  finalizeScope(sub._elements, sub._flows);
970
1075
  const element = makeFlowElement(id, "subProcess", resolved.options);
@@ -981,7 +1086,7 @@ export class BranchBuilder {
981
1086
  }
982
1087
  /** Add a transaction sub-process (mirrors `ProcessBuilder.transaction`). */
983
1088
  transaction(id, content, options) {
984
- return this.addElement(makeTransactionEl(id, content, options, this.rootMessages));
1089
+ return this.addElement(makeTransactionEl(id, content, options, this.roots()));
985
1090
  }
986
1091
  /**
987
1092
  * Add an ad-hoc sub-process (mirrors `ProcessBuilder.adHocSubProcess`).
@@ -993,8 +1098,9 @@ export class BranchBuilder {
993
1098
  */
994
1099
  adHocSubProcess(id, content, options) {
995
1100
  const resolved = resolveSubProcessArgs(content, options);
1101
+ recordToolGrid(this.rootLayoutHints, id, resolved.options);
996
1102
  // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
997
- const sub = new SubProcessContentBuilder(this.rootMessages, false);
1103
+ const sub = new SubProcessContentBuilder(this.roots(), false);
998
1104
  resolved.content(sub);
999
1105
  finalizeScope(sub._elements, sub._flows);
1000
1106
  const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
@@ -1009,7 +1115,7 @@ export class BranchBuilder {
1009
1115
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
1010
1116
  eventSubProcess(id, content, options) {
1011
1117
  const resolved = resolveSubProcessArgs(content, options);
1012
- const sub = new SubProcessContentBuilder(this.rootMessages);
1118
+ const sub = new SubProcessContentBuilder(this.roots());
1013
1119
  resolved.content(sub);
1014
1120
  finalizeScope(sub._elements, sub._flows);
1015
1121
  const element = makeFlowElement(id, "subProcess", resolved.options);
@@ -1040,7 +1146,7 @@ export class BranchBuilder {
1040
1146
  if (!this.currentGatewayId) {
1041
1147
  throw new Error("branch() must be called after a gateway element");
1042
1148
  }
1043
- const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1149
+ const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations, this.rootLayoutHints);
1044
1150
  callback(b);
1045
1151
  for (const el of b._elements) {
1046
1152
  if (this._ids.has(el.id)) {
@@ -1096,7 +1202,11 @@ export class SubProcessContentBuilder {
1096
1202
  lastNodeId;
1097
1203
  currentGatewayId;
1098
1204
  openBranchEnds = [];
1205
+ rootErrors;
1099
1206
  rootMessages;
1207
+ rootSignals;
1208
+ rootEscalations;
1209
+ rootLayoutHints;
1100
1210
  /**
1101
1211
  * Whether sequential calls chain themselves with sequence flows.
1102
1212
  *
@@ -1110,17 +1220,36 @@ export class SubProcessContentBuilder {
1110
1220
  */
1111
1221
  autoConnect;
1112
1222
  /** @internal */
1113
- constructor(rootMessages = [], autoConnect = true) {
1114
- this.rootMessages = rootMessages;
1223
+ constructor(roots = {
1224
+ errors: [],
1225
+ messages: [],
1226
+ signals: [],
1227
+ escalations: [],
1228
+ layoutHints: emptyLayoutHints(),
1229
+ }, autoConnect = true) {
1230
+ this.rootErrors = roots.errors;
1231
+ this.rootMessages = roots.messages;
1232
+ this.rootSignals = roots.signals;
1233
+ this.rootEscalations = roots.escalations;
1234
+ this.rootLayoutHints = roots.layoutHints;
1115
1235
  this.autoConnect = autoConnect;
1116
1236
  }
1237
+ roots() {
1238
+ return {
1239
+ errors: this.rootErrors,
1240
+ messages: this.rootMessages,
1241
+ signals: this.rootSignals,
1242
+ escalations: this.rootEscalations,
1243
+ layoutHints: this.rootLayoutHints,
1244
+ };
1245
+ }
1117
1246
  addElement(element) {
1118
1247
  if (this._ids.has(element.id)) {
1119
1248
  throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
1120
1249
  }
1121
1250
  this._elements.push(element);
1122
1251
  this._ids.add(element.id);
1123
- if (this.autoConnect) {
1252
+ if (this.autoConnect && !isLinkEvent(element, "intermediateCatchEvent")) {
1124
1253
  if (this.lastNodeId) {
1125
1254
  this._flows.push({
1126
1255
  id: generateId("Flow"),
@@ -1143,7 +1272,7 @@ export class SubProcessContentBuilder {
1143
1272
  }
1144
1273
  // The cursor still moves even when nothing is wired, so `connectTo()` after
1145
1274
  // an activity keeps naming that activity as the flow's source.
1146
- this.lastNodeId = element.id;
1275
+ this.lastNodeId = isLinkEvent(element, "intermediateThrowEvent") ? undefined : element.id;
1147
1276
  return this;
1148
1277
  }
1149
1278
  /**
@@ -1164,9 +1293,9 @@ export class SubProcessContentBuilder {
1164
1293
  }
1165
1294
  // ---- Events ----
1166
1295
  startEvent(id, options) {
1167
- const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
1296
+ const el = makeStartEventEl(id ?? generateId("StartEvent"), options);
1168
1297
  if (el.type === "startEvent" && options) {
1169
- el.eventDefinitions = buildEventDefinitions(options);
1298
+ el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1170
1299
  if (options.isInterrupting === false)
1171
1300
  el.isInterrupting = false;
1172
1301
  }
@@ -1175,13 +1304,13 @@ export class SubProcessContentBuilder {
1175
1304
  endEvent(id, options) {
1176
1305
  const el = makeFlowElement(id ?? generateId("EndEvent"), "endEvent", options);
1177
1306
  if (el.type === "endEvent" && options)
1178
- el.eventDefinitions = buildEventDefinitions(options);
1307
+ el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1179
1308
  return this.addElement(el);
1180
1309
  }
1181
1310
  intermediateThrowEvent(id, options) {
1182
1311
  const el = makeFlowElement(id ?? generateId("IntermediateThrowEvent"), "intermediateThrowEvent", options);
1183
1312
  if (el.type === "intermediateThrowEvent" && options)
1184
- el.eventDefinitions = buildEventDefinitions(options);
1313
+ el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1185
1314
  return this.addElement(el);
1186
1315
  }
1187
1316
  intermediateCatchEvent(id, options) {
@@ -1190,7 +1319,7 @@ export class SubProcessContentBuilder {
1190
1319
  extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
1191
1320
  });
1192
1321
  if (el.type === "intermediateCatchEvent" && options)
1193
- el.eventDefinitions = buildEventDefinitions(options);
1322
+ el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1194
1323
  return this.addElement(el);
1195
1324
  }
1196
1325
  // ---- Tasks ----
@@ -1272,10 +1401,12 @@ export class SubProcessContentBuilder {
1272
1401
  return this.annotate(this.lastNodeId, text);
1273
1402
  }
1274
1403
  /** Attach a text annotation to an element by explicit ID. */
1275
- annotate(elementId, text) {
1404
+ annotate(elementId, text, options) {
1276
1405
  const n = (this._annCounters.get(elementId) ?? 0) + 1;
1277
1406
  this._annCounters.set(elementId, n);
1278
1407
  const annId = `TextAnnotation_${elementId}_${n}`;
1408
+ if (options?.side)
1409
+ this.rootLayoutHints.annotationSides.set(annId, options.side);
1279
1410
  this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
1280
1411
  this._associations.push({
1281
1412
  id: `Association_${elementId}_${n}`,
@@ -1291,7 +1422,7 @@ export class SubProcessContentBuilder {
1291
1422
  if (!this.currentGatewayId) {
1292
1423
  throw new Error("branch() must be called after a gateway element");
1293
1424
  }
1294
- const b = new BranchBuilder(this.currentGatewayId, name);
1425
+ const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations, this.rootLayoutHints);
1295
1426
  callback(b);
1296
1427
  for (const el of b._elements) {
1297
1428
  if (this._ids.has(el.id)) {
@@ -1366,7 +1497,7 @@ export class SubProcessContentBuilder {
1366
1497
  if (element.type === "boundaryEvent") {
1367
1498
  element.attachedToRef = options.attachedTo;
1368
1499
  element.cancelActivity = options.cancelActivity;
1369
- element.eventDefinitions = buildEventDefinitions(options);
1500
+ element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1370
1501
  }
1371
1502
  // Push directly — no sequence flow, boundary events attach via attachedToRef
1372
1503
  this._elements.push(element);
@@ -1409,7 +1540,7 @@ export class SubProcessContentBuilder {
1409
1540
  /** Add a sub-process nested inside this sub-process's content. */
1410
1541
  subProcess(id, content, options) {
1411
1542
  const resolved = resolveSubProcessArgs(content, options);
1412
- const sub = new SubProcessContentBuilder(this.rootMessages);
1543
+ const sub = new SubProcessContentBuilder(this.roots());
1413
1544
  resolved.content(sub);
1414
1545
  finalizeScope(sub._elements, sub._flows);
1415
1546
  const element = makeFlowElement(id, "subProcess", resolved.options);
@@ -1426,7 +1557,7 @@ export class SubProcessContentBuilder {
1426
1557
  }
1427
1558
  /** Add a transaction sub-process nested inside this sub-process's content. */
1428
1559
  transaction(id, content, options) {
1429
- return this.addElement(makeTransactionEl(id, content, options, this.rootMessages));
1560
+ return this.addElement(makeTransactionEl(id, content, options, this.roots()));
1430
1561
  }
1431
1562
  /**
1432
1563
  * Add an ad-hoc sub-process nested inside this sub-process's content.
@@ -1438,8 +1569,9 @@ export class SubProcessContentBuilder {
1438
1569
  */
1439
1570
  adHocSubProcess(id, content, options) {
1440
1571
  const resolved = resolveSubProcessArgs(content, options);
1572
+ recordToolGrid(this.rootLayoutHints, id, resolved.options);
1441
1573
  // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
1442
- const sub = new SubProcessContentBuilder(this.rootMessages, false);
1574
+ const sub = new SubProcessContentBuilder(this.roots(), false);
1443
1575
  resolved.content(sub);
1444
1576
  finalizeScope(sub._elements, sub._flows);
1445
1577
  const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
@@ -1454,7 +1586,7 @@ export class SubProcessContentBuilder {
1454
1586
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
1455
1587
  eventSubProcess(id, content, options) {
1456
1588
  const resolved = resolveSubProcessArgs(content, options);
1457
- const sub = new SubProcessContentBuilder(this.rootMessages);
1589
+ const sub = new SubProcessContentBuilder(this.roots());
1458
1590
  resolved.content(sub);
1459
1591
  finalizeScope(sub._elements, sub._flows);
1460
1592
  const element = makeFlowElement(id, "subProcess", resolved.options);
@@ -1494,6 +1626,7 @@ export class ProcessBuilder {
1494
1626
  rootMessages = [];
1495
1627
  rootSignals = [];
1496
1628
  rootEscalations = [];
1629
+ rootLayoutHints = emptyLayoutHints();
1497
1630
  _textAnnotations = [];
1498
1631
  _associations = [];
1499
1632
  _annCounters = new Map();
@@ -1515,6 +1648,15 @@ export class ProcessBuilder {
1515
1648
  constructor(processId) {
1516
1649
  this.processId = processId;
1517
1650
  }
1651
+ roots() {
1652
+ return {
1653
+ errors: this.rootErrors,
1654
+ messages: this.rootMessages,
1655
+ signals: this.rootSignals,
1656
+ escalations: this.rootEscalations,
1657
+ layoutHints: this.rootLayoutHints,
1658
+ };
1659
+ }
1518
1660
  /**
1519
1661
  * Continues an existing model rather than generating a new one.
1520
1662
  *
@@ -1747,32 +1889,12 @@ export class ProcessBuilder {
1747
1889
  // ---- Events ----
1748
1890
  /** Add a start event. Start events never auto-connect from the previous element. */
1749
1891
  startEvent(id, options) {
1750
- const nodeId = id ?? generateId("StartEvent");
1751
- const extElements = [];
1752
- if (options?.zeebeProperties) {
1753
- extElements.push(...zeebeExtensionsToXmlElements({
1754
- properties: { properties: options.zeebeProperties },
1755
- }));
1756
- }
1757
- const element = makeFlowElement(nodeId, "startEvent", {
1758
- name: options?.name,
1759
- documentation: options?.documentation,
1760
- extensionElements: extElements,
1761
- });
1892
+ const element = makeStartEventEl(id ?? generateId("StartEvent"), options);
1762
1893
  if (element.type === "startEvent" && options) {
1763
1894
  element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1764
1895
  if (options.isInterrupting === false)
1765
1896
  element.isInterrupting = false;
1766
1897
  }
1767
- if (options?.modelerTemplate) {
1768
- element.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
1769
- }
1770
- if (options?.modelerTemplateVersion) {
1771
- element.unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
1772
- }
1773
- if (options?.modelerTemplateIcon) {
1774
- element.unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
1775
- }
1776
1898
  this.addFlowElement(element);
1777
1899
  return this;
1778
1900
  }
@@ -2035,7 +2157,7 @@ export class ProcessBuilder {
2035
2157
  if (!this.currentGatewayId) {
2036
2158
  throw new Error("branch() must be called after a gateway element");
2037
2159
  }
2038
- const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
2160
+ const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations, this.rootLayoutHints);
2039
2161
  callback(b);
2040
2162
  for (const el of b._elements) {
2041
2163
  if (this.elementIds.has(el.id)) {
@@ -2116,8 +2238,9 @@ export class ProcessBuilder {
2116
2238
  */
2117
2239
  adHocSubProcess(id, content, options) {
2118
2240
  const resolved = resolveSubProcessArgs(content, options);
2241
+ recordToolGrid(this.rootLayoutHints, id, resolved.options);
2119
2242
  // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
2120
- const sub = new SubProcessContentBuilder(this.rootMessages, false);
2243
+ const sub = new SubProcessContentBuilder(this.roots(), false);
2121
2244
  resolved.content(sub);
2122
2245
  finalizeScope(sub._elements, sub._flows);
2123
2246
  const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
@@ -2133,7 +2256,7 @@ export class ProcessBuilder {
2133
2256
  /** Add a sub-process (aspirational). */
2134
2257
  subProcess(id, content, options) {
2135
2258
  const resolved = resolveSubProcessArgs(content, options);
2136
- const sub = new SubProcessContentBuilder(this.rootMessages);
2259
+ const sub = new SubProcessContentBuilder(this.roots());
2137
2260
  resolved.content(sub);
2138
2261
  finalizeScope(sub._elements, sub._flows);
2139
2262
  const element = makeFlowElement(id, "subProcess", resolved.options);
@@ -2151,13 +2274,13 @@ export class ProcessBuilder {
2151
2274
  }
2152
2275
  /** Add a transaction sub-process — a sub-process with atomic semantics. */
2153
2276
  transaction(id, content, options) {
2154
- this.addFlowElement(makeTransactionEl(id, content, options, this.rootMessages));
2277
+ this.addFlowElement(makeTransactionEl(id, content, options, this.roots()));
2155
2278
  return this;
2156
2279
  }
2157
2280
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
2158
2281
  eventSubProcess(id, content, options) {
2159
2282
  const resolved = resolveSubProcessArgs(content, options);
2160
- const sub = new SubProcessContentBuilder(this.rootMessages);
2283
+ const sub = new SubProcessContentBuilder(this.roots());
2161
2284
  resolved.content(sub);
2162
2285
  finalizeScope(sub._elements, sub._flows);
2163
2286
  const element = makeFlowElement(id, "subProcess", resolved.options);
@@ -2189,10 +2312,12 @@ export class ProcessBuilder {
2189
2312
  return this.annotate(this.lastNodeId, text);
2190
2313
  }
2191
2314
  /** Attach a text annotation to any flow element by explicit ID. */
2192
- annotate(elementId, text) {
2315
+ annotate(elementId, text, options) {
2193
2316
  const n = (this._annCounters.get(elementId) ?? 0) + 1;
2194
2317
  this._annCounters.set(elementId, n);
2195
2318
  const annId = `TextAnnotation_${elementId}_${n}`;
2319
+ if (options?.side)
2320
+ this.rootLayoutHints.annotationSides.set(annId, options.side);
2196
2321
  this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
2197
2322
  this._associations.push({
2198
2323
  id: `Association_${elementId}_${n}`,
@@ -2252,6 +2377,7 @@ export class ProcessBuilder {
2252
2377
  // Flows the document already had keep their ids: continuing a model must
2253
2378
  // not renumber the part the caller did not touch.
2254
2379
  assignStableFlowIds(this.flowElements, this.sequenceFlows, this._source === undefined ? undefined : new Set(this._sourceFlowTargets.keys()));
2380
+ assertExplicitFlowIdsUnique(this.flowElements, this.sequenceFlows);
2255
2381
  recomputeIncomingOutgoing(this.flowElements, this.sequenceFlows);
2256
2382
  if (this._source !== undefined)
2257
2383
  return this.buildOntoSource(this._source);
@@ -2314,7 +2440,7 @@ export class ProcessBuilder {
2314
2440
  ]
2315
2441
  : [],
2316
2442
  };
2317
- return hoistMessageSubscriptions(this._autoLayout ? applyAutoLayout(defs) : defs);
2443
+ return hoistMessageSubscriptions(this._autoLayout ? applyAutoLayout(defs, "semantic", this.rootLayoutHints) : defs);
2318
2444
  }
2319
2445
  /**
2320
2446
  * Writes this process's contents back into the document it came from.
@@ -2350,7 +2476,9 @@ export class ProcessBuilder {
2350
2476
  definitions.messages = this.rootMessages;
2351
2477
  definitions.signals = this.rootSignals;
2352
2478
  definitions.escalations = this.rootEscalations;
2353
- return hoistMessageSubscriptions(this._autoLayout ? applyAutoLayout(definitions) : definitions);
2479
+ return hoistMessageSubscriptions(this._autoLayout
2480
+ ? applyAutoLayout(definitions, "semantic", this.rootLayoutHints)
2481
+ : definitions);
2354
2482
  }
2355
2483
  /**
2356
2484
  * Refuses to rewire a flow that was already in the document.
@@ -2425,6 +2553,12 @@ export class ProcessBuilder {
2425
2553
  // Do NOT connect open branch ends — handler is outside normal flow
2426
2554
  return;
2427
2555
  }
2556
+ // A link catch starts a new chain; open branch ends wait for the next element.
2557
+ if (isLinkEvent(element, "intermediateCatchEvent")) {
2558
+ this._savedMainFlowId = undefined;
2559
+ this.lastNodeId = element.id;
2560
+ return;
2561
+ }
2428
2562
  if (this.lastNodeId) {
2429
2563
  const flowId = generateId("Flow");
2430
2564
  this.sequenceFlows.push({
@@ -2450,7 +2584,7 @@ export class ProcessBuilder {
2450
2584
  // Clear any saved compensation cursor — a normal element advancing the cursor
2451
2585
  // means the compensation boundary/handler pattern has been interrupted.
2452
2586
  this._savedMainFlowId = undefined;
2453
- this.lastNodeId = element.id;
2587
+ this.lastNodeId = isLinkEvent(element, "intermediateThrowEvent") ? undefined : element.id;
2454
2588
  }
2455
2589
  }
2456
2590
  // ---------------------------------------------------------------------------